查看 VM 擴充功能記錄

使用 VM 擴充功能管理工具管理 Compute Engine 執行個體 (VM) 的擴充功能時,每個 VM 上的訪客代理程式都會記錄擴充功能強制執行的相關事件。使用 Cloud Logging,在記錄檔探索工具中查看這些記錄,監控及排解 VM 擴充功能的問題。

事前準備

  • 參閱 VM 擴充功能管理工具說明文件。
  • 瞭解如何使用Logs Explorer。
  • 如果尚未設定驗證,請先完成設定。驗證程序會確認您的身分,以便您存取 Google Cloud 服務和 API。如要從本機開發環境執行程式碼或範例,您可以選取下列其中一個選項,向 Compute Engine 進行驗證:

    請根據您打算如何使用本頁範例,選取對應的分頁標籤:

    控制台

    使用 Google Cloud 控制台存取 Google Cloud 服務和 API 時,您不需要設定驗證機制。

    gcloud

    1. 安裝 Google Cloud CLI。 安裝完成後,請執行下列指令,初始化 Google Cloud CLI:

      gcloud init

      若您採用的是外部識別資訊提供者 (IdP),請先使用聯合身分登入 gcloud CLI。

  • 設定預設區域和可用區。
  • REST

    如要在本機開發環境中使用本頁的 REST API 範例,請使用您提供給 gcloud CLI 的憑證。

      安裝 Google Cloud CLI。

      若您採用的是外部識別資訊提供者 (IdP),請先使用聯合身分登入 gcloud CLI。

    詳情請參閱 Google Cloud 驗證說明文件中的「使用 REST 進行驗證」一節。

查看 VM 擴充功能記錄

如要查看 VM 擴充功能記錄,請選取下列其中一個選項:

控制台

如要在 Google Cloud 控制台查看 VM 擴充功能記錄,請完成下列步驟:

  1. 前往 Google Cloud 控制台的「Logs Explorer」頁面。

    前往 Logs Explorer

  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 擴充功能記錄,請執行 logging read 指令,並篩選 VM 執行個體和擴充功能:

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 擴充功能記錄,請將 POST 要求傳送至 Logging V2 API,並在要求主體中加入 filter 參數:

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:需要這項擴充功能的服務已停用。

後續步驟