VM 확장 프로그램 로그 보기

VM 확장 프로그램 관리자를 사용하여 Compute Engine 인스턴스(VM)에서 확장 프로그램을 관리하면 각 VM의 게스트 에이전트가 확장 프로그램 시행에 관한 이벤트를 로깅합니다. Cloud Logging을 사용하여 로그 탐색기에서 이러한 로그를 확인하여 VM 확장 프로그램의 문제를 모니터링하고 해결합니다.

시작하기 전에

  • VM 확장 프로그램 관리자 문서를 읽어보세요.
  • 로그 탐색기 사용 방법 읽어보기
  • 아직 인증을 설정하지 않았다면 설정합니다. 인증은 Google Cloud 서비스 및 API에 액세스하기 위해 ID를 확인합니다. 로컬 개발 환경에서 코드 또는 샘플을 실행하려면 다음 옵션 중 하나를 선택하여 Compute Engine에 인증하면 됩니다.

    이 페이지의 샘플 사용 방법에 대한 탭을 선택하세요.

    콘솔

    Google Cloud 콘솔을 사용하여 Google Cloud 서비스 및 API에 액세스하는 경우 인증을 설정할 필요가 없습니다.

    gcloud

    1. Google Cloud CLI를 설치한 후 제휴 ID로 gcloud CLI에 로그인합니다. 로그인한 후 다음 명령어를 실행하여 Google Cloud CLI를 초기화합니다. 

      gcloud init
  • 기본 리전 및 영역을 설정합니다.

    • REST

    로컬 개발 환경에서 이 페이지의 REST API 샘플을 사용하려면 gcloud CLI에 제공한 사용자 인증 정보를 사용합니다.

      Google Cloud CLI를 설치한 후 제휴 ID로 gcloud CLI에 로그인합니다.

    자세한 내용은 Google Cloud 인증 문서의 REST 사용을 위한 인증을 참조하세요.

VM 확장 프로그램 로그 보기

VM 확장 프로그램 로그를 보려면 다음 옵션 중 하나를 선택합니다.

콘솔

Google Cloud 콘솔에서 VM 확장 프로그램 로그를 보려면 다음 단계를 완료합니다.

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

    로그 탐색기로 이동

  2. 쿼리 필드에 다음 쿼리를 입력합니다.

    resource.type="gce_instance"
resource.labels.instance_id="INSTANCE_ID"
jsonPayload.@type="type.googleapis.com/google.compute.logging.agentcontrolplane.v1.VmExtensionEvent"
jsonPayload.extensionName="EXTENSION_NAME"
timestamp >= START_TIME
timestamp <= END_TIME

    다음을 바꿉니다.

    • INSTANCE_ID: VM 인스턴스의 ID입니다.
    • EXTENSION_NAME: 확장 프로그램의 이름입니다(예: ops-agent).
    • START_TIME: 기간의 시작 지점(예: 2024-01-01T00:00:00Z)
    • END_TIME: 기간의 종료 시간(예: 2024-02-01T00:00:00Z)

    다음 예시 쿼리는 인스턴스 123456에서 ops-agent 확장 프로그램의 로그를 필터링합니다.

    resource.type="gce_instance"
resource.labels.instance_id="123456"
jsonPayload.@type="type.googleapis.com/google.compute.logging.agentcontrolplane.v1.VmExtensionEvent"
jsonPayload.extensionName="ops-agent"
timestamp >= "2024-01-01T00:00:00Z"
timestamp <= "2024-02-01T01:00:00Z"

  3. 쿼리 실행을 클릭합니다.

gcloud

Google Cloud CLI를 사용하여 VM 확장 프로그램 로그를 조회하려면 VM 인스턴스 및 확장 프로그램에 대한 필터와 함께 logging read 명령어를 실행합니다.

gcloud logging read 'resource.type="gce_instance" AND \
    resource.labels.instance_id="INSTANCE_ID" AND \
    jsonPayload.@type="type.googleapis.com/google.compute.logging.agentcontrolplane.v1.VmExtensionEvent" AND \
    jsonPayload.extensionName="EXTENSION_NAME" AND \
    timestamp >= "START_TIME" AND \
    timestamp <= "END_TIME"'

다음 변수를 환경 값으로 바꿉니다.

  • INSTANCE_ID: VM 인스턴스의 ID입니다.
  • EXTENSION_NAME: 확장 프로그램의 이름입니다(예: ops-agent).
  • START_TIME: 기간의 시작(예: 2024-01-01T00:00:00Z)
  • END_TIME: 기간의 끝입니다(예: 2024-02-01T00:00:00Z).

REST

REST API를 사용하여 VM 확장 프로그램 로그를 검색하려면 요청 본문에 filter 매개변수를 포함하여 Logging V2 API에 POST 요청을 보냅니다.

POST https://logging.googleapis.com/v2/entries:list

{
  "filter": "resource.type=\"gce_instance\" AND
            resource.labels.instance_id=\"INSTANCE_ID\" AND
            jsonPayload.@type=\"type.googleapis.com/google.compute.logging.agentcontrolplane.v1.VmExtensionEvent\" AND
            jsonPayload.extensionName=\"EXTENSION_NAME\" AND
            timestamp >= \"START_TIME\" AND
            timestamp <= \"END_TIME\"",
  "pageSize": 10,
  "resourceNames": [
    "projects/PROJECT_ID"
  ]
}

다음 변수를 환경 값으로 바꿉니다.

  • INSTANCE_ID: VM 인스턴스의 ID입니다.
  • EXTENSION_NAME: 확장 프로그램의 이름입니다(예: ops-agent).
  • START_TIME: 기간의 시작(예: 2024-01-01T00:00:00Z)
  • END_TIME: 기간의 끝(예: 2024-02-01T00:00:00Z)
  • PROJECT_ID: Google Cloud 프로젝트 ID입니다.

VM 확장 프로그램 이벤트 로그 항목

다음 JSON 스니펫은 VM 확장 프로그램 이벤트의 로그 항목 예시를 보여줍니다.

{
  "insertId": "rsiudxbck",
  "jsonPayload": {
    "eventMessage": "Enforcement State: Installing ops-agent@4bda61add3e5c989.; Extension Health: Plugin is running ok",
    "timestamp": "2026-03-23T16:13:40.496755675Z",
    "extensionName": "ops-agent",
    "revisionId": "4bda61add3e5c989",
    "@type": "type.googleapis.com/google.compute.logging.agentcontrolplane.v1.VmExtensionEvent",
    "eventType": "INSTALLED"
  },
  "resource": {
    "type": "gce_instance",
    "labels": {
      "project_id": "27654321",
      "instance_id": "1234567",
      "zone": "us-west1-a"
    }
  },
  "timestamp": "2026-03-23T16:13:40.496854498Z",
  "severity": "INFO",
  "logName": "projects/my-project/logs/compute.googleapis.com%2Fvm_extension_policies",
  "receiveTimestamp": "2026-03-23T16:13:40.906133199Z"
}

로그 항목 세부정보

다음 표에서는 VM 확장 프로그램 이벤트 로그에 표시되는 매개변수를 설명합니다.

필드 설명
eventMessage 시행 상태 및 확장 프로그램 상태를 포함하여 이벤트를 설명하는 메시지입니다.
extensionName 확장 프로그램의 이름입니다(예: ops-agent).

지원되는 확장 프로그램 및 이름 목록은 지원되는 확장 프로그램을 참조하세요.
extensionVersion VM 확장 프로그램 관리자가 설치를 위해 선택한 확장 프로그램 버전입니다. 이 값은 확장 프로그램 정책에서 고정한 버전 또는 사용 가능한 최신 버전입니다.
revisionId 확장 프로그램 버전의 특정 바이너리입니다. 각 확장 프로그램 버전에는 다양한 운영체제를 지원하는 여러 버전이 있을 수 있으며 Google은 특정 VM에 적합한 바이너리를 자동으로 선택합니다. Cloud Customer Care에 문의할 때 이 버전 ID를 제공하면 Google에서 VM에 올바른 바이너리를 선택했는지 확인하는 데 도움이 됩니다.
eventType 이벤트 유형입니다. 가능한 값은 다음과 같습니다.
  • CRASHED: 확장 프로그램이 비정상 종료되었습니다. 이 값은 게스트 에이전트가 확장 프로그램을 설치하고 시작했지만 나중에 확장 프로그램 실행이 중지되었음을 나타냅니다.
  • INSTALL_FAILED: 확장 프로그램 설치에 실패했습니다.
  • INSTALLED: 게스트 에이전트가 확장 프로그램을 설치하고 성공적으로 시작했습니다.
  • ROLLBACK_FAILED: 확장 프로그램 롤백에 실패했습니다.
  • ROLLED_BACK: 확장 프로그램 롤백이 완료되었습니다.
  • INCOMPATIBLE: 확장 프로그램 버전 후보 중 어느 것도 설치 요구사항(예: 운영체제 또는 아키텍처)을 충족하지 않습니다.
  • SERVICE_DISABLED: 이 확장 프로그램이 필요한 서비스가 사용 중지되었습니다.

다음 단계