查看虚拟机扩展程序日志

当您使用虚拟机扩展程序管理器管理 Compute Engine 实例（虚拟机）上的扩展程序时，每个虚拟机上的客机代理都会记录与扩展程序强制执行相关的事件。 使用 Cloud Logging 在 Logs Explorer 中查看这些日志，以监控虚拟机扩展程序并排查其问题。

准备工作

  • 阅读虚拟机扩展程序管理器文档。
  • 了解如何使用Logs Explorer。
  • 如果您尚未设置身份验证，请进行设置。身份验证用于验证您的身份，以便访问 Google Cloud 服务和 API。如需从本地开发环境运行代码或示例，您可以通过选择以下选项之一向 Compute Engine 进行身份验证：

    选择标签页以了解您打算如何使用本页面上的示例：

    控制台

    当您使用 Google Cloud 控制台访问 Google Cloud 服务和 API 时，无需设置身份验证。

    gcloud

    1. 安装 Google Cloud CLI，然后使用联合身份登录 gcloud CLI。 登录后，运行以下命令来初始化 Google Cloud CLI： 

      gcloud init
  • 设置默认区域和可用区。

    • REST

    如需在本地开发环境中使用本页面上的 REST API 示例，请使用您提供给 gcloud CLI 的凭证。

      安装 Google Cloud CLI，然后使用联合身份登录 gcloud CLI。

    如需了解详情，请参阅 Google Cloud 身份验证文档中的使用 REST 时进行身份验证。

查看虚拟机扩展程序日志

如需查看虚拟机扩展程序日志，请选择以下选项之一：

控制台

如需在 Google Cloud 控制台中查看虚拟机扩展程序日志，请完成以下步骤：

  1. 在 Google Cloud 控制台中，前往 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：虚拟机实例的 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 查找虚拟机扩展程序日志，请运行 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：虚拟机实例的 ID。
  • EXTENSION_NAME：扩展程序的名称（例如 ops-agent）。
  • START_TIME：时间范围的开始时间（例如 2024-01-01T00:00:00Z）。
  • END_TIME：时间范围的结束时间（例如 2024-02-01T00:00:00Z）。

REST

如需使用 REST API 检索虚拟机扩展程序日志，请向 Logging V2 API 发送 POST 请求，并在请求正文中添加 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：虚拟机实例的 ID。
  • EXTENSION_NAME：扩展程序的名称（例如 ops-agent）。
  • START_TIME：时间范围的开始时间（例如 2024-01-01T00:00:00Z）。
  • END_TIME：时间范围的结束时间（例如 2024-02-01T00:00:00Z）。
  • PROJECT_ID：您的 Google Cloud 项目 ID。

虚拟机扩展程序事件日志条目

以下 JSON 代码段展示了虚拟机扩展程序事件的示例日志条目：

{
  "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"
}

日志条目详情

下表介绍了虚拟机扩展程序事件日志中显示的参数：

字段 说明
eventMessage 描述事件的消息，包括违规处置状态和扩展程序健康状况。
extensionName 扩展程序的名称（例如 ops-agent）。

如需查看支持的扩展程序及其名称的列表，请参阅支持的扩展程序。
extensionVersion 虚拟机扩展程序管理器选择安装的扩展程序版本。 此值是您在扩展程序政策中固定的版本，或最新的可用版本。
revisionId 扩展程序版本的特定二进制文件。每个扩展程序版本都可以有多个修订版本，以支持不同的操作系统，并且 Google 会自动为特定虚拟机选择正确的二进制文件。 与 Cloud Customer Care 联系时，请提供此修订版本 ID，以帮助验证 Google 是否为您的虚拟机选择了正确的二进制文件。
eventType 事件的类型。可能的值包括下列项：
  • CRASHED：扩展程序崩溃。此值表示客机代理已成功安装并启动扩展程序，但扩展程序随后停止运行。
  • INSTALL_FAILED：扩展程序安装失败。
  • INSTALLED：客体代理已成功安装并启动扩展程序。
  • ROLLBACK_FAILED：扩展程序回滚失败。
  • ROLLED_BACK：扩展程序回滚成功。
  • INCOMPATIBLE：没有任何扩展程序修订版本候选版本满足安装要求（例如操作系统或架构）。
  • SERVICE_DISABLED：需要此扩展程序的服务已被停用。

后续步骤