운영 에이전트 문제 해결 정보 찾기

이 문서에서는 운영 에이전트를 설치 또는 실행할 때 문제를 식별하기 위해 사용할 수 있는 진단 정보 소스를 설명합니다.

에이전트 상태 점검

버전 2.25.1에는 운영 에이전트에 대한 시작 상태 점검이 도입되었습니다. 운영 에이전트가 시작되면 에이전트의 올바른 실행을 방해하는 상황에 대해 일련의 검사를 수행합니다. 에이전트에서 이러한 상황 중 하나가 감지되면 해당 문제를 기술하는 메시지를 기록합니다. 운영 에이전트는 다음을 확인합니다.

연결 문제
에이전트 자체에 대해 측정항목을 보고하기 위해 에이전트에 사용되는 포트 가용성
권한 문제
로그 또는 측정항목을 기록하기 위해 에이전트에 사용되는 API의 가용성
상태 점검 루틴 자체의 문제

시작 시간 오류 찾기에 대한 자세한 내용은 시작 시간 오류 찾기를 참조하세요.

버전 2.37.0에는 운영 에이전트에 대한 런타임 상태 점검이 포함되었습니다. 이러한 오류는 Cloud Logging 및 Error Reporting에 보고됩니다. 런타임 오류 찾기에 대한 자세한 내용은 런타임 오류 찾기를 참조하세요.

버전 2.46.0에는 정보 제공용 LogPingOpsAgent 코드가 도입되었습니다. 이 코드는 오류를 나타내지 않습니다. 자세한 내용은 성공적인 로그 수집 확인을 참조하세요.

다음 표에서는 각 상태 점검 코드를 알파벳 순서로 나열하고 각 코드의 의미를 설명합니다. Err 문자열로 끝나는 코드는 오류를 나타내며, 다른 코드는 정보 제공용입니다.

상태 점검 코드	카테고리	의미	제안
`DLApiConnErr`	연결	다운로드 하위 도메인 `dl.google.com`에 대한 요청이 실패했습니다.	인터넷 연결 및 방화벽 규칙을 확인합니다. 자세한 내용은 네트워크 연결 문제를 참조하세요.
`FbMetricsPortErr`	포트 가용성	운영 에이전트 자체 측정항목에 필요한 포트 20202를 사용할 수 없습니다.	포트 20202가 열려 있는지 확인합니다. 자세한 내용은 필요한 포트를 사용할 수 없음을 참조하세요.
`HcFailureErr`	일반	운영 에이전트 상태 점검 루틴에 내부 오류가 발생했습니다.	Google Cloud 콘솔에서 지원 케이스를 제출합니다. 자세한 내용은 지원 받기를 참조하세요.
`LogApiConnErr`	연결	Logging API 요청이 실패했습니다.	인터넷 연결 및 방화벽 규칙을 확인합니다. 자세한 내용은 네트워크 연결 문제를 참조하세요.
`LogApiDisabledErr`	API	현재 Google Cloud 프로젝트에서 Logging API가 사용 중지되었습니다.	Logging API를 사용 중지합니다.
`LogApiPermissionErr`	권한	서비스 계정에 로그 작성자 역할(`roles/logging.logWriter`)이 없습니다.	서비스 계정에 로그 작성자 역할을 부여합니다. 자세한 내용은 에이전트에 API 권한이 없음을 참조하세요.
`LogApiScopeErr`	권한	VM에 https://www.googleapis.com/auth/logging.write 액세스 범위가 없습니다.	VM에 https://www.googleapis.com/auth/logging.write 범위를 추가합니다. 자세한 내용은 액세스 범위 확인을 참조하세요.
`LogApiUnauthenticatedErr`	API	현재 VM이 Logging API에 인증할 수 없습니다.	사용자 인증 정보 파일, VM 액세스 범위, 권한이 올바르게 설정되었는지 확인하세요. 자세한 내용은 운영 에이전트 승인을 참조하세요.
`LogPingOpsAgent`		10분마다 `ops-agent-health` 로그에 기록되는 정보 제공용 페이로드 메시지입니다. 결과로 생성된 로그 항목을 사용하여 에이전트가 로그를 전송하고 있는지 확인할 수 있습니다. 이 메시지는 오류가 아닙니다.	이 메시지는 10분마다 표시됩니다. 메시지가 20분 이상 표시되지 않으면 에이전트에 문제가 발생한 것일 수 있습니다. 문제 해결 정보는 운영 에이전트 문제 해결을 참조하세요.
`LogParseErr`	런타임	운영 에이전트가 하나 이상의 로그를 파싱하지 못했습니다.	생성한 모든 로깅 프로세서 구성을 확인하세요. 자세한 내용은 로그 파싱 오류를 참조하세요.
`LogPipeLineErr`	런타임	운영 에이전트의 로깅 파이프라인이 실패했습니다.	에이전트가 버퍼 파일에 액세스할 수 있는지 확인하세요. 전체 디스크를 점검하고 운영 에이전트 구성이 올바른지 확인합니다. 자세한 내용은 파이프라인 오류를 참조하세요.
`MetaApiConnErr`	연결	VM 액세스 범위, OAuth 토큰, 리소스 라벨을 쿼리하기 위한 GCE 메타데이터 서버 요청이 실패했습니다.	인터넷 연결 및 방화벽 규칙을 확인합니다. 자세한 내용은 네트워크 연결 문제를 참조하세요.
`MonApiConnErr`	연결	Monitoring API 요청이 실패했습니다.	인터넷 연결 및 방화벽 규칙을 확인합니다. 자세한 내용은 네트워크 연결 문제를 참조하세요.
`MonApiDisabledErr`	API	현재 Google Cloud 프로젝트에서 Monitoring API가 사용 중지되었습니다.	Monitoring API를 사용 설정합니다.
`MonApiPermissionErr`	권한	서비스 계정에 모니터링 측정항목 작성자 역할(`roles/monitoring.metricWriter`)이 없습니다.	서비스 계정에 모니터링 측정항목 작성자 역할을 부여합니다. 자세한 내용은 에이전트에 API 권한이 없음을 참조하세요.
`MonApiScopeErr`	권한	VM에 https://www.googleapis.com/auth/monitoring.write 액세스 범위가 없습니다.	VM에 https://www.googleapis.com/auth/monitoring.write 범위를 추가합니다. 자세한 내용은 액세스 범위 확인을 참조하세요.
`MonApiUnauthenticatedErr`	API	현재 VM이 Monitoring API에 인증할 수 없습니다.	사용자 인증 정보 파일, VM 액세스 범위, 권한이 올바르게 설정되었는지 확인하세요. 자세한 내용은 운영 에이전트 승인을 참조하세요.
`OtelMetricsPortErr`	포트 가용성	운영 에이전트 자체 측정항목에 필요한 포트 20201을 사용할 수 없습니다.	포트 20201이 열려 있는지 확인합니다. 자세한 내용은 필요한 포트를 사용할 수 없음을 참조하세요.
`PacApiConnErr`	연결	이 상태 점검 코드는 신뢰할 수 없습니다. 이 코드는 운영 에이전트 버전 2.46.1에서 사용 중지되었습니다.	운영 에이전트 버전 2.46.1 이상으로 업데이트하세요.

시작 시간 오류 찾기

버전 2.35.0부터 상태 점검 정보가 Cloud Logging API에 의해 ops-agent-health 로그에 기록됩니다(버전 2.33.0, 2.34.0은 ops-agent-health-checks 사용). 동일한 정보가 health-checks.log 파일에 다음과 같이 기록됩니다.

Linux: /var/log/google-cloud-ops-agent/health-checks.log
Windows: C:\ProgramData\Google\Cloud Operations\Ops Agent\log\health-checks.log

또한 다음과 같이 운영 에이전트 서비스 상태를 쿼리하여 모든 상태 점검 메시지를 볼 수 있습니다.

Linux에서는 다음 명령어를 실행합니다.
```
   sudo systemctl status google-cloud-ops-agent"*"
   
```
"[Ports Check] Result: PASS"과 같은 메시지를 찾으세요. 다른 결과에는 'ERROR' 및 'FAIL'이 포함됩니다.
Windows에서는 Windows 이벤트 뷰어를 사용합니다. google-cloud-ops-agent 서비스와 연관된 '정보', '오류' 또는 '실패'를 찾습니다.

문제를 해결한 후 에이전트를 다시 시작해야 합니다. 에이전트가 시작될 때 상태 점검이 실행되므로 상태 점검을 다시 실행하려면 에이전트를 다시 시작해야 합니다.

런타임 오류 찾기

런타임 상태 점검은 Cloud Logging 및 Error Reporting 모두에 보고됩니다. 에이전트를 시작할 수 없지만 실패하기 전에 오류를 보고할 수 있는 경우 시작 시간 오류도 표시될 수 있습니다.

Logging의 운영 에이전트에서 런타임 오류를 보려면 다음을 수행하세요.

Google Cloud 콘솔의 탐색 패널에서 Logging을 선택한 후 로그 탐색기를 선택합니다.
로그 탐색기로 이동
다음 쿼리를 입력한 다음 쿼리 실행을 클릭합니다.
```
log_id("ops-agent-health")
```

Error Reporting에서 운영 에이전트의 런타임 오류를 보려면 다음을 수행합니다.

Google Cloud 콘솔에서 Error Reporting 페이지로 이동합니다.
Error Reporting으로 이동

검색창을 사용하여 이 페이지를 찾을 수도 있습니다.
운영 에이전트의 오류를 보려면 Ops Agent의 오류를 필터링합니다.

성공적인 로그 수집 확인

운영 에이전트 버전 2.46.0에는 정보 제공을 위한 LogPingOpsAgent 상태 점검이 도입되었습니다. 이 검사는 10분마다 ops-agent-health에 정보 메시지를 기록합니다. 이러한 메시지가 있으면 다음을 수행하여 운영 에이전트가 로그를 기록 중인지 확인할 수 있습니다.

로그 탐색기를 사용하여 특정 VM의 로그에서 핑 메시지를 검색합니다.
측정항목 탐색기를 사용하여 특정 VM의 측정항목 log_entry_count 값을 확인합니다.
특정 VM이 log_entry_count 측정항목을 업데이트하지 않는 경우 알림을 제공하는 알림 정책을 만듭니다.

이 중에서 로그 메시지가 수집되지 않음을 나타내는 옵션이 있으면 다음을 수행할 수 있습니다.

시작 오류 또는 런타임 오류를 나타내는 오류 코드를 확인합니다.
운영 에이전트가 실행 중인지 확인합니다.
에이전트 진단 스크립트를 실행합니다.

특정 VM에서 운영 에이전트 상태를 확인하려면 VM의 인스턴스 ID가 필요합니다. 인스턴스 ID를 찾으려면 다음을 수행합니다.

Google Cloud 콘솔에서 VM 인스턴스 페이지로 이동합니다.
VM 인스턴스로 이동

검색창을 사용하여 이 페이지를 찾은 경우 부제목이 Compute Engine인 결과를 선택합니다.
VM 인스턴스의 이름을 클릭합니다.
세부정보 탭에서 기본 정보 섹션을 찾습니다. 인스턴스 ID는 숫자 문자열로 표시됩니다. 이후 섹션에서 이 문자열을 INSTANCE_ID 값에 사용합니다.

로그 탐색기를 사용하여 메시지 검색

로그 탐색기를 사용해서 VM 로그에서 핑 메시지를 검색하려면 다음을 수행합니다.

Google Cloud 콘솔의 탐색 패널에서 Logging을 선택한 후 로그 탐색기를 선택합니다.
로그 탐색기로 이동
특정 VM 인스턴스의 운영 에이전트에서 핑 메시지를 찾으려면 다음 쿼리를 입력하고INSTANCE_ID를 Compute Engine VM의 식별자로 바꾸고 쿼리 실행을 클릭합니다.
```
resource.type="gce_instance"
resource.labels.instance_id="INSTANCE_ID"
log_id("ops-agent-health")
jsonPayload.code="LogPingOpsAgent"
    
```

`log_entry_count` 측정항목 보기

측정항목 탐색기를 사용하여 VM의 log_entry_count 측정항목 값을 확인하려면 다음을 수행합니다.

Google Cloud 콘솔의 탐색 패널에서 Monitoring을 선택한 후 측정항목 탐색기를 선택합니다.
측정항목 탐색기로 이동
측정항목 선택 필드에서 다음을 수행합니다.
1. log entries를 입력합니다.
2. 리소스 유형에서 VM 인스턴스를 선택합니다.
3. 측정항목 카테고리에서 로그 기반 측정항목을 선택합니다.
4. 측정항목에서 로그 항목을 선택합니다.
5. 적용을 선택합니다.
필터 입력란에 다음 필터를 추가합니다.
- 특정 VM 인스턴스 ID로 필터링합니다.
  1. 리소스 라벨 instance_id를 선택합니다.
  2. 비교 연산자 = (등호)를 선택합니다.
  3. VM의 INSTANCE_ID를 입력합니다.
- ops-agent-health 로그를 필터링합니다.
  1. 리소스 라벨 log를 선택합니다.
  2. 비교 연산자 = (등호)를 선택합니다.
  3. ops-agent-heath 값을 선택합니다.

`log_entry_count` 측정항목에 대한 알림 정책 만들기

특정 VM의 log_entry_count 측정항목 값에서 로그 핑을 모니터링하는 알림 정책을 만들려면 다음을 수행합니다.

Google Cloud 콘솔의 탐색 패널에서 Monitoring을 선택한 후 알림을 선택합니다.
알림으로 이동
알림 채널을 만들지 않고 알림을 받으려면 알림 채널 수정을 클릭하고 알림 채널을 추가합니다. 채널을 추가한 후 알림 페이지로 돌아갑니다.
알림 페이지에서 정책 만들기를 클릭합니다.
측정항목 선택 필드에서 다음을 수행합니다.
1. log entries를 입력합니다.
2. 리소스 유형에서 VM 인스턴스를 선택합니다.
3. 측정항목 카테고리에서 로그 기반 측정항목을 선택합니다.
4. 측정항목에서 로그 항목을 선택합니다.
5. 적용을 선택합니다.
필터 입력란에 다음 필터를 추가합니다.
- 특정 VM 인스턴스 ID로 필터링합니다.
  1. 리소스 라벨 instance_id를 선택합니다.
  2. 비교 연산자 = (등호)를 선택합니다.
  3. VM의 INSTANCE_ID를 입력합니다.
- ops-agent-health 로그를 필터링합니다.
  1. 리소스 라벨 log를 선택합니다.
  2. 비교 연산자 = (등호)를 선택합니다.
  3. ops-agent-heath 값을 선택합니다.
변환 데이터 섹션에서 다음을 선택합니다.
- 순환 기간 필드에서 10분을 선택합니다. 더 긴 기간 동안 누락된 로그 항목을 찾으려면 더 긴 값을 입력합니다.
- 순환 기간 함수 필드에 델타를 선택합니다.
다음을 클릭합니다.

알림 트리거 구성 페이지의 설정에 따라 알림이 트리거되는 시점이 결정됩니다. 다음 표의 설정으로 이 페이지를 작성합니다.

알림 트리거 구성 페이지 필드	값
`Condition type`	`Threshold`
`Alert trigger`	`Any time series violates`
`Threshold position`	`Below threshold`
`Threshold value`	`1`
`Advanced Options: Retest window`	`No retest`

다음을 클릭합니다.
선택사항: 알림 정책에 알림을 추가하려면 알림 채널을 클릭합니다. 대화상자의 메뉴에서 하나 이상의 알림 채널을 선택한 다음 확인을 클릭합니다.
선택사항: 이슈 자동 종료 기간을 업데이트합니다. 이 필드는 측정항목 데이터가 없을 때 Monitoring에서 이슈를 닫는 시기를 결정합니다.
선택사항: 문서를 클릭하고 알림 메시지에 포함할 정보를 추가합니다.
알림 이름을 클릭하고 알림 정책 이름을 입력합니다.
정책 만들기를 클릭합니다.

자세한 내용은 알림 정책을 참조하세요.

VM용 에이전트 진단 도구

에이전트 진단 도구는 VM에서 운영 에이전트, 기존 Logging 에이전트, 기존 Monitoring 에이전트 모두에 중요한 로컬 디버깅 정보를 수집합니다. 디버깅 정보에는 프로젝트 정보, VM 정보, 에이전트 구성, 에이전트 로그, 에이전트 서비스 상태, 일반적으로 수집하려면 수동 작업이 필요한 정보가 포함됩니다. 또한 이 도구는 로컬 VM 환경이 에이전트가 올바르게 작동하기 위한 특정 요구사항(예: 네트워크 연결 및 필요한 권한)을 충족하는지 확인합니다.

VM에서 에이전트의 고객 케이스를 제출할 때 에이전트 진단 도구를 실행하고 수집된 정보를 케이스에 연결합니다. 이 정보를 제공하면 지원 케이스 문제를 해결하는 데 필요한 시간이 줄어듭니다. 지원 케이스에 정보를 연결하기 전에 비밀번호와 같은 모든 민감한 정보를 수정합니다.

에이전트 진단 도구는 VM 내에서 실행되어야 하므로 일반적으로 먼저 VM에 SSH를 통해 연결해야 합니다. 다음 명령어는 에이전트 진단 도구를 검색하여 실행합니다.

Linux

curl -sSO https://dl.google.com/cloudagents/diagnose-agents.sh
sudo bash diagnose-agents.sh

Windows

(New-Object Net.WebClient).DownloadFile("https://dl.google.com/cloudagents/diagnose-agents.ps1", "${env:UserProfile}\diagnose-agents.ps1")
Invoke-Expression "${env:UserProfile}\diagnose-agents.ps1"

스크립트 실행 출력을 따라 수집된 정보가 포함된 파일을 찾습니다. 일반적으로 스크립트를 실행할 때 출력 디렉터리를 맞춤설정하지 않는 한 Linux의 /var/tmp/google-agents 디렉터리와 Windows의 $env:LOCALAPPDATA/Temp 디렉터리에서 해당 파일을 찾을 수 있습니다.

자세한 내용은 Linux의 경우 diagnose-agents.sh 스크립트를, Windows의 경우 diagnose-agents.ps1 스크립트를 검토하세요.

자동 설치 정책을 위한 에이전트 진단 도구

운영 에이전트 OS 정책을 사용하여 운영 에이전트를 설치하려고 시도하면 이 섹션에 설명된 진단 스크립트를 사용하여 디버깅할 수 있습니다. 예를 들어 다음 사례 중 하나가 나타날 수 있습니다.

Monitoring 및 Logging용 운영 에이전트 설치 체크박스를 사용하여 VM을 만드는 동안 운영 에이전트 설치를 수행하면 운영 에이전트 설치가 실패합니다.
Cloud Monitoring VM 인스턴스 대시보드 또는 Compute Engine VM 세부정보 페이지의 관측 가능성 탭에 있는 에이전트 상태가 10분 이상 대기 중 상태입니다. 장시간 대기 중 상태는 다음 중 하나를 의미할 수 있습니다.
- 정책을 적용하는 데 문제가 있음
- 운영 에이전트의 실제 설치에 문제가 있음
- VM과 Cloud Monitoring 간의 연결 문제가 있음
이러한 문제 중 일부의 경우에는 일반적인 에이전트 진단 스크립트 및 상태 점검도 유용할 수 있습니다.

정책 진단 스크립트를 실행하려면 다음 명령어를 실행합니다.

curl -sSO https://dl.google.com/cloudagents/diagnose-ui-policies.sh
bash diagnose-ui-policies.sh VM_NAME VM_ZONE

이 스크립트는 영향을 받는 VM 및 관련 자동 설치 정책에 대한 정보를 보여줍니다.

에이전트 상태

VM에서 운영 에이전트 프로세스 상태를 확인하여 에이전트가 실행 중인지 여부를 확인할 수 있습니다.

Linux

운영 에이전트 상태를 확인하려면 다음 명령어를 사용합니다.

sudo systemctl status google-cloud-ops-agent"*"

다음 샘플 출력에 표시된 것처럼 '측정항목 에이전트' 및 'Logging 에이전트' 구성요소가 '실행 중'으로 나열되는지 확인합니다(간결함을 위해 일부 줄은 삭제됨).

● google-cloud-ops-agent.service - Google Cloud Ops Agent
     Loaded: loaded (/lib/systemd/system/google-cloud-ops-agent.service; enabled; vendor preset: enabled)
     Active: active (exited) since Wed 2023-05-03 21:22:28 UTC; 4 weeks 0 days ago
    Process: 3353828 ExecStartPre=/opt/google-cloud-ops-agent/libexec/google_cloud_ops_agent_engine -in /etc/go>
    Process: 3353837 ExecStart=/bin/true (code=exited, status=0/SUCCESS)
   Main PID: 3353837 (code=exited, status=0/SUCCESS)
        CPU: 195ms

[...]

● google-cloud-ops-agent-opentelemetry-collector.service - Google Cloud Ops Agent - Metrics Agent
     Loaded: loaded (/lib/systemd/system/google-cloud-ops-agent-opentelemetry-collector.service; static)
     Active: active (running) since Wed 2023-05-03 21:22:29 UTC; 4 weeks 0 days ago
    Process: 3353840 ExecStartPre=/opt/google-cloud-ops-agent/libexec/google_cloud_ops_agent_engine -service=ot>
   Main PID: 3353855 (otelopscol)
      Tasks: 9 (limit: 2355)
     Memory: 65.3M
        CPU: 40min 31.555s
     CGroup: /system.slice/google-cloud-ops-agent-opentelemetry-collector.service
             └─3353855 /opt/google-cloud-ops-agent/subagents/opentelemetry-collector/otelopscol --config=/run/g>

[...]

● google-cloud-ops-agent-fluent-bit.service - Google Cloud Ops Agent - Logging Agent
     Loaded: loaded (/lib/systemd/system/google-cloud-ops-agent-fluent-bit.service; static)
     Active: active (running) since Wed 2023-05-03 21:22:29 UTC; 4 weeks 0 days ago
    Process: 3353838 ExecStartPre=/opt/google-cloud-ops-agent/libexec/google_cloud_ops_agent_engine -service=fl>
   Main PID: 3353856 (google_cloud_op)
      Tasks: 31 (limit: 2355)
     Memory: 58.3M
        CPU: 29min 6.771s
     CGroup: /system.slice/google-cloud-ops-agent-fluent-bit.service
             ├─3353856 /opt/google-cloud-ops-agent/libexec/google_cloud_ops_agent_wrapper -config_path /etc/goo>
             └─3353872 /opt/google-cloud-ops-agent/subagents/fluent-bit/bin/fluent-bit --config /run/google-clo>

[...]

● google-cloud-ops-agent-diagnostics.service - Google Cloud Ops Agent - Diagnostics
     Loaded: loaded (/lib/systemd/system/google-cloud-ops-agent-diagnostics.service; disabled; vendor preset: e>
     Active: active (running) since Wed 2023-05-03 21:22:26 UTC; 4 weeks 0 days ago
   Main PID: 3353819 (google_cloud_op)
      Tasks: 8 (limit: 2355)
     Memory: 36.0M
        CPU: 3min 19.488s
     CGroup: /system.slice/google-cloud-ops-agent-diagnostics.service
             └─3353819 /opt/google-cloud-ops-agent/libexec/google_cloud_ops_agent_diagnostics -config /etc/goog>

[...]

Windows

운영 에이전트 상태를 확인하려면 다음 명령어를 사용합니다.

Get-Service google-cloud-ops-agent*

다음 샘플 출력에 표시된 것처럼 '측정항목 에이전트' 및 'Logging 에이전트' 구성요소가 '실행 중'으로 나열되는지 확인합니다.

Status   Name               DisplayName
------   ----               -----------
Running  google-cloud-op... Google Cloud Ops Agent
Running  google-cloud-op... Google Cloud Ops Agent - Logging Agent
Running  google-cloud-op... Google Cloud Ops Agent - Metrics Agent
Running  google-cloud-op... Google Cloud Ops Agent - Diagnostics

에이전트 자체 로그

에이전트에서 Cloud Logging에 로그를 수집하지 못하면 문제 해결을 위해 VM에서 로컬로 에이전트 로그를 검사해야 할 수 있습니다. 로그 순환을 사용하여 에이전트의 자체 로그를 관리할 수도 있습니다.

Linux

Journald에 기록된 자체 로그를 검사하려면 다음 명령어를 실행합니다.

journalctl -u google-cloud-ops-agent*

로깅 모듈에서 디스크에 기록한 자체 로그를 검사하려면 다음 명령어를 실행합니다.

vim -M /var/log/google-cloud-ops-agent/subagents/logging-module.log