使用 VM 擴充功能管理工具管理 Compute Engine 執行個體 (VM) 的擴充功能時,每個 VM 上的訪客代理程式都會記錄擴充功能強制執行的相關事件。使用 Cloud Logging,在記錄檔探索工具中查看這些記錄,監控及排解 VM 擴充功能的問題。
事前準備
- 參閱 VM 擴充功能管理工具說明文件。
- 瞭解如何使用Logs Explorer。
-
如果尚未設定驗證,請先完成設定。驗證程序會確認您的身分,以便您存取 Google Cloud 服務和 API。如要從本機開發環境執行程式碼或範例,您可以選取下列其中一個選項,向 Compute Engine 進行驗證:
請根據您打算如何使用本頁範例,選取對應的分頁標籤:
控制台
使用 Google Cloud 控制台存取 Google Cloud 服務和 API 時,您不需要設定驗證機制。
gcloud
-
安裝 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 擴充功能記錄,請完成下列步驟:
- 前往 Google Cloud 控制台的「Logs Explorer」頁面。
在「查詢」欄位中輸入下列查詢:
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"點選「執行查詢」。
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 |
事件類型。可能的值如下:
|
後續步驟
- 如要檢查推出進度和擴充功能健康狀態,請參閱「查看 VM 擴充功能詳細資料和狀態」。
- 如要診斷推出失敗、檢查執行中的訪客程序,或檢查訪客代理程式偵錯記錄,請參閱「排解 VM 擴充功能問題」。
- 如要建立 Cloud Monitoring 資訊主頁,並設定代理程式健康狀態、CPU 和記憶體用量的快訊,請參閱「監控 VM 擴充功能」。
- 如要修改配置設定、變更固定的版本,或移除已部署的代理,請參閱「使用擴充功能政策管理 VM 擴充功能」。