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

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

gcpdiag를 사용하여 에이전트 상태 확인

gcpdiag를 사용하여 프로젝트 내 개별 VM이나 전체 VM Fleet에서 운영 에이전트 상태를 보고해 에이전트가 설치되어 있고 로그와 측정항목을 활발하게 전송하고 있는지 확인할 수 있습니다. gcpdiag는 CSV 또는 JSON 형식을 포함하여 다양한 형식으로 상태 보고서를 만들 수 있습니다.

다음에서는 CSV 형식의 Fleet 전체 에이전트 상태 보고서를 보여줍니다.

🔎 gce/ERR/2024_004: Verify Ops Agent is installed on GCE VMs and is sending logs and metrics.

gce/ERR/2024_004,projects/my-project/zones/my-location/instances/instance-1,failed,Ops Agent not installed on the VM,https://gcpdiag.dev/rules/gce/ERR/2024_004
gce/ERR/2024_004,projects/my-project/zones/my-location/instances/instance-2,skipped,VM Manager is needed for the ops agent detection. Please enable it at: https://cloud.google.com/compute/docs/manage-os#automatic and run this check again.,https://gcpdiag.dev/rules/gce/ERR/2024_004
gce/ERR/2024_004,projects/my-project/zones/my-location/instances/instance-3,skipped,VM Manager is needed for the ops agent detection. Please enable it at: https://cloud.google.com/compute/docs/manage-os#automatic and run this check again.,https://gcpdiag.dev/rules/gce/ERR/2024_004
gce/ERR/2024_004,projects/my-project/zones/my-location/instances/instance-4,ok,"Ops Agent installed on the VM, and is successfully sending logs and metrics.",https://gcpdiag.dev/rules/gce/ERR/2024_004
gce/ERR/2024_004,projects/my-project/zones/my-location/instances/instance-5,ok,"Ops Agent installed on the VM, and is successfully sending logs and metrics.",https://gcpdiag.dev/rules/gce/ERR/2024_004

Google Cloud 지원팀에서 만든 gcpdiag 도구를 사용하면 운영 에이전트 문제를 포함하여 Google Cloud 프로젝트의 일반 문제를 자가 진단할 수 있습니다. gcpdiag는 공식 Google Cloud 제품이 아닌 오픈소스 도구이지만 Google Cloud 지원팀에서 적극적으로 개발하여 관리하고 있습니다. GitHub에서 의견을 제공하거나 문제를 신고하세요.

시작하기 전에

gcpdiag는 Cloud Shell과 통합되어 있으므로 설치할 필요 없이 실행할 수 있습니다. gcpdiag를 실행하려면 먼저 다음 기본 요건을 충족해야 합니다.

• 승인: gcpdiag는 Cloud Shell에서 애플리케이션 기본 사용자 인증 정보(ADC)를 사용하여 인증합니다.
  gcpdiag와 함께 사용되는 사용자 인증 정보에는 운영 에이전트가 실행 중인 Google Cloud 프로젝트에 대한 다음과 같은 최소한의 역할이 있어야 합니다.

  • 뷰어(roles/viewer)
  • 서비스 사용량 소비자(roles/serviceusage.serviceUsageConsumer)

• API: 프로젝트에서 gcpdiag를 사용하려면 다음 API를 사용 설정해야 합니다.

  • Cloud Resource Manager API: cloudresourcemanager.googleapis.com
  • Identity and Access Management API: iam.googleapis.com
  • Cloud Logging API: logging.googleapis.com
  • 서비스 사용량: serviceusage.googleapis.com

  이러한 API를 사용 설정하려면 Cloud Shell 또는 다른 명령줄에서 다음 명령어를 실행합니다.

   gcloud --project=PROJECT_ID services enable \
     cloudresourcemanager.googleapis.com \
     iam.googleapis.com \
     logging.googleapis.com \
     serviceusage.googleapis.com
  

• VM Manager: 인스턴스에서 VM Manager를 무료 등급으로 사용 설정합니다. VM 생성 중에 운영 에이전트를 설치했거나 에이전트 정책에서 VM 인스턴스의 운영 에이전트 설치를 관리하는 경우에는 이미 VM Manager의 요구사항을 충족했습니다.

gcpdiag 실행

운영 에이전트와 함께 사용할 gcpdiag 명령어의 기본 문법은 다음과 같습니다.

gcpdiag lint --project=PROJECT_ID [--name=INSTANCE_NAME] --show-skipped --include=gce/err/2024_004 [--output=[CSV|JSON]]

• PROJECT_ID는 Google Cloud 프로젝트의 ID입니다.
• INSTANCE_NAME은 Compute Engine VM 이름입니다. 특정 VM을 쿼리하려면 --name 옵션을 사용합니다. 전체 Fleet를 쿼리하는 옵션을 생략합니다.
• 보고서를 CSV 또는 JSON 형식의 파일로 저장하려면 --output 옵션을 사용합니다. 출력 파일이 필요 없으면 옵션을 생략합니다.

--include 옵션 값은 gcpdiag 규칙을 하나 이상 지정합니다. gce/ERR/2024-004는 운영 에이전트의 규칙입니다. gcpdiag 명령어 문법에 대한 자세한 내용은 gcpdiag - Google Cloud Platform 진단을 참조하세요.

예를 들어 'my-project' 프로젝트에 대한 Fleet 전체 보고서를 생성하려면 다음 명령어를 실행합니다.

gcpdiag lint --project=my-project --show-skipped --include=gce/ERR/2024_004

다음과 유사한 결과가 출력됩니다.

🔎 gce/ERR/2024_004: Verify Ops Agent is installed on GCE VMs and is sending logs and metrics.
  - my-project/instance-1                                                 [FAIL] Ops Agent not installed on the VM
  - my-project/instance-2                                                 [FAIL] Ops Agent not installed on the VM
  - my-project/instance-3                                                 [SKIP] Unable to confirm Ops Agent installation
  VM Manager is needed for the ops agent detection. Please enable it at: https://cloud.google.com/compute/docs/manage-os#automatic and run this check again.
  - my-project/instance-4                                            [FAIL] Ops Agent is installed, but it's failing to send both logs and metrics to Google Cloud.
  Is Ops Agent sending logs? (Yes)  Is Ops Agent sending metrics? (No)
  - my-project/instance-5                                                 [FAIL] Ops Agent is installed, but it's failing to send both logs and metrics to Google Cloud.
  Is Ops Agent sending logs? (No)   Is Ops Agent sending metrics? (No)
  - my-project/instance-6                                                 [ OK ] Ops Agent installed on the VM, and is successfully sending logs and metrics.
  - my-project/instance-7                                                 [ OK ] Ops Agent installed on the VM, and is successfully sending logs and metrics.

'my-project' 프로젝트에서 'my-instance' 인스턴스에 대한 보고서를 생성하려면 다음 명령어를 실행합니다.

gcpdiag lint  --project=my-project --name=my-instance --show-skipped --include=gce/err/2024_004

다음과 유사한 결과가 출력됩니다.

🔎 gce/ERR/2024_004: Verify Ops Agent is installed on GCE VMs and is sending logs and metrics.
  - my-project/my-instance   [ OK ] Ops Agent installed on the VM, and is successfully sending logs and metrics.

다음과 유사한 출력이 표시되면서 gcpdiag 명령어가 실패하면 도구 실행에 대한 모든 기본 요건이 충족되어 있는지 확인합니다.

WARNING:googleapiclient.http:Encountered 403 Forbidden with reason "PERMISSION_DENIED"
[ERROR]:can't access project my-project: Cloud Resource Manager API has not been used in project my-project before or it is disabled. Enable it by visiting https://console.developers.google.com/apis/api/cloudresourcemanager.googleapis.com/overview?project=my-project then retry. If you enabled this API recently, wait a few minutes for the action to propagate to our systems and retry..
[DEBUG]: An Http Error occurred whiles accessing projects.get

HttpError 403 when requesting https://cloudresourcemanager.googleapis.com/v3/projects/my-project?alt=json returned Cloud Resource Manager API has not been used in project my-project before or it is disabled. Enable it by visiting https://console.developers.google.com/apis/api/cloudresourcemanager.googleapis.com/overview?project=my-project then retry. If you enabled this API recently, wait a few minutes for the action to propagate to our systems and retry. Details: ...
[ERROR]:exiting program...
error getting project details

gcpdiag 출력 해석

이 섹션에서는 gcpdiag에서 생성한 보고서를 이해하고 사용하는 데 도움이 되는 정보를 제공합니다.

gcpdiag 명령어는 다음 정보가 포함된 보고서를 생성합니다.

• 명령어가 호출된 gcpdiag 규칙의 표시기입니다. 운영 에이전트의 경우 이 정보는 다음과 같이 표시됩니다.
  🔎 gce/ERR/2024_004: Verify Ops Agent is installed on GCE VMs and is sending logs and metrics
• PROJECT_ID/INSTANCE_ID 형식의 특정 VM에 대한 결과 식별자. Fleet 전체 보고서의 경우 출력에는 각 VM의 항목이 포함됩니다. 단일 VM 보고서의 경우 출력에는 단일 항목이 포함됩니다.
• 확인 상태입니다. 상태에는 다음 값 중 하나가 포함됩니다.
  • OK
  • FAIL
  • SKIP
• 상태 값에 대한 설명입니다.

다음 섹션에서는 상태 값과 그 의미를 자세히 설명합니다.

상태: OK

OK 상태는 운영 에이전트가 VM에서 실행 중이며 VM에서 로그와 측정항목 모두 보내고 있음을 의미합니다. 보고서에는 다음 상태 설명이 포함됩니다.
Ops Agent installed on the VM, and is successfully sending logs and metrics.

상태: FAIL

FAIL 상태는 운영 에이전트가 설치되어 있지 않거나 VM에서 로그와 측정항목 모두 전송하지 않고 있음을 의미합니다. 상태 설명은 감지된 문제를 나타냅니다.

• 운영 에이전트가 설치되지 않은 경우에는 다음 상태 설명이 표시됩니다.
  Ops Agent not installed on the VM
• 운영 에이전트가 VM에서 로그와 측정항목을 모두 전송하지 않는 경우 다음과 같은 상태 설명이 표시됩니다.
  Agent is installed, but it's failing to send both logs and metrics to Google Cloud.
Is Ops Agent sending logs? (Yes) Is Ops Agent sending metrics? (No)

운영 에이전트가 설치되어 있지 않으면 운영 에이전트를 설치합니다. 설치가 실패한 경우 문제는 다음 중 하나일 수 있습니다.

• VM에 연결된 서비스 계정이 없습니다. 이 문제를 해결하려면 VM에 서비스 계정을 연결한 후 다시 운영 에이전트를 설치해 봅니다.
• VM에 기존 에이전트(Monitoring 에이전트 또는 Logging 에이전트) 중 하나가 이미 설치되어 있습니다. 이 문제를 해결하려면 기존 에이전트를 제거한 후 다시 운영 에이전트를 설치해 봅니다.

운영 에이전트가 VM에서 로그나 측정항목을 전송하지 않는 경우 시작 시간 오류에 대한 에이전트 상태 점검을 사용하여 문제를 파악하고 해결합니다.

상태: SKIP

SKIP 상태는 gcpdiag에서 운영 에이전트가 VM에 설치되어 있는지 확인할 수 없음을 의미합니다 보고서에는 다음 상태 설명이 포함됩니다.
Unable to confirm Ops Agent installation
  VM Manager is needed for the ops agent detection.
  Please enable it at: https://cloud.google.com/compute/docs/manage-os#automatic and run this check again.

에이전트 상태를 테스트하려면 gcpdiag에 VM에서 실행할 VM Manager가 필요합니다. 이 문제를 해결하려면 VM Manager 무료 등급을 인스턴스에 설치합니다. 설치 후 15분 정도 기다리고 다시 gcpdiag 명령어를 실행해 봅니다.

에이전트 상태 점검

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

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

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

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

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

시작 시간 오류 찾기

버전 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의 운영 에이전트에서 런타임 오류를 보려면 다음을 수행하세요.

1. Google Cloud 콘솔에서 로그 탐색기 페이지로 이동합니다.

   로그 탐색기로 이동

   검색창을 사용하여 이 페이지를 찾은 경우 부제목이 Logging인 결과를 선택합니다.

2. 다음 쿼리를 입력한 다음 쿼리 실행을 클릭합니다.
   

   log_id("ops-agent-health")

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

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

   Error Reporting으로 이동

   검색창을 사용하여 이 페이지를 찾을 수도 있습니다.

2. 운영 에이전트의 오류를 보려면 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용 에이전트 진단 도구

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

에이전트 자체 로그

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

Linux

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

journalctl -u google-cloud-ops-agent*

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

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

Windows

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

Get-WinEvent -FilterHashtable @{ Logname='Application'; ProviderName='google-cloud-ops-agent*' } | Format-Table -AutoSize -Wrap

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

notepad "C:\ProgramData\Google\Cloud Operations\Ops Agent\log\logging-module.log"

운영 에이전트 서비스의 Windows Service Control Manager에서 로그를 검사하려면 다음 명령어를 실행합니다.

Get-WinEvent -FilterHashtable @{ Logname='System'; ProviderName='Service Control Manager' } | Where-Object -Property Message -Match 'Google Cloud Ops Agent' | Format-Table -AutoSize -Wrap

Cloud Monitoring에서 측정항목 사용 및 진단 보기

Cloud Monitoring 측정항목 관리 페이지에서는 관측 가능성에 영향을 주지 않고 청구 가능 측정항목에 지출하는 금액을 제어할 수 있는 정보를 제공합니다. 측정항목 관리 페이지에서는 다음 정보를 보고합니다.

• 측정항목 도메인 및 개별 측정항목의 바이트 기반 및 샘플 기반 청구에 대한 수집량
• 측정항목의 라벨 및 카디널리티에 대한 데이터
• 각 측정항목의 읽기 수
• 알림 정책 및 커스텀 대시보드의 측정항목 사용
• 측정항목 쓰기 오류의 비율

또한 측정항목 관리를 사용하면 불필요한 측정항목을 제외하여 수집 비용을 절감할 수 있습니다.

측정항목 관리 페이지를 보려면 다음을 수행합니다.

1. Google Cloud 콘솔에서 query_stats 측정항목 관리 페이지로 이동합니다.

   측정항목 관리로 이동

   검색창을 사용하여 이 페이지를 찾은 경우 부제목이 Monitoring인 결과를 선택합니다.

2. 툴바에서 기간을 선택합니다. 기본적으로 측정항목 관리 페이지에는 이전 1일 동안 수집된 측정항목에 대한 정보가 표시됩니다.

측정항목 관리 페이지에 대한 자세한 내용은 측정항목 사용량 보기 및 관리를 참조하세요.