View VM extension logs

When you use VM Extension Manager to manage extensions on your Compute Engine instances (VMs), the guest agent on each VM logs events about the extension enforcement. Use Cloud Logging to view these logs in the Logs Explorer to monitor and troubleshoot any issues with your VM extensions.

Before you begin

  • Read the VM Extension Manager documentation.
  • Read how to use the Logs Explorer.
  • If you haven't already, set up authentication. Authentication verifies your identity for access to Cloud de Confiance by S3NS services and APIs. To run code or samples from a local development environment, you can authenticate to Compute Engine by selecting one of the following options:

    Select the tab for how you plan to use the samples on this page:

    Console

    When you use the Cloud de Confiance console to access Cloud de Confiance by S3NS services and APIs, you don't need to set up authentication.

    gcloud

    1. Install the Google Cloud CLI, and then sign in to the gcloud CLI with your federated identity. After signing in, initialize the Google Cloud CLI by running the following command: 

      gcloud init
    2. Set a default region and zone.

    REST

    To use the REST API samples on this page in a local development environment, you use the credentials you provide to the gcloud CLI.

      Install the Google Cloud CLI, and then sign in to the gcloud CLI with your federated identity.

    For more information, see Authenticate for using REST in the Cloud de Confiance authentication documentation.

View VM extension logs

To view VM extension logs, select one of the following options:

Console

To view VM extension logs in the Cloud de Confiance console, complete the following steps:

  1. In the Cloud de Confiance console, go to the Logs Explorer page.

    Go to Logs Explorer

  2. In the Query field, enter the following query:

    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

    Replace the following:

    • INSTANCE_ID: the ID of the VM instance.
    • EXTENSION_NAME: the name of the extension (for example, ops-agent).
    • START_TIME: the beginning of the time range (for example, 2024-01-01T00:00:00Z).
    • END_TIME: the end of the time range (for example, 2024-02-01T00:00:00Z).

    The following example query filters logs for the ops-agent extension on instance 123456:

    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. Click Run query.

gcloud

To look up VM extension logs by using the Google Cloud CLI, run the logging read command with a filter for your VM instance and extension:

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"'

Replace the following variables with values for your environment:

  • INSTANCE_ID: the ID of the VM instance.
  • EXTENSION_NAME: the name of the extension (for example, ops-agent).
  • START_TIME: the beginning of the time range (for example, 2024-01-01T00:00:00Z).
  • END_TIME: the end of the time range (for example, 2024-02-01T00:00:00Z).

REST

To retrieve VM extension logs by using the REST API, send a POST request to the Logging V2 API with the filter parameter in the request body:

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

Replace the following variables with values for your environment:

  • INSTANCE_ID: the ID of the VM instance.
  • EXTENSION_NAME: the name of the extension (for example, ops-agent).
  • START_TIME: the beginning of the time range (for example, 2024-01-01T00:00:00Z).
  • END_TIME: the end of the time range (for example, 2024-02-01T00:00:00Z).
  • PROJECT_ID: your Cloud de Confiance by S3NS project ID.

VM extension event log entry

The following JSON snippet shows an example log entry for a VM extension event:

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

Log entry details

The following table describes the parameters that appear in VM extension event logs:

Field Description
eventMessage A message that describes the event, including the enforcement state and extension health.
extensionName The name of the extension (for example, ops-agent).

For a list of supported extensions and their names, see supported extensions.
extensionVersion The extension version that VM Extension Manager selected for installation. This value is either the version that you pinned in the extension policy or the latest available version.
revisionId A specific binary of an extension version. Each extension version can have multiple revisions to support different operating systems, and Google automatically chooses the correct binary for a specific VM. When you contact Cloud Customer Care, provide this revision ID to help verify whether Google selected the correct binary for your VM.
eventType The type of event. Possible values include the following:
  • CRASHED: The extension crashed. This value indicates that the guest agent installed and started the extension successfully, but the extension later stopped running.
  • INSTALL_FAILED: The extension installation failed.
  • INSTALLED: The guest agent installed and started the extension successfully.
  • ROLLBACK_FAILED: The extension rollback failed.
  • ROLLED_BACK: The extension rollback succeeded.
  • INCOMPATIBLE: None of the extension revision candidates satisfy the installation requirements (for example, operating system or architecture).
  • SERVICE_DISABLED: The service that requires this extension is disabled.

What's next