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 Google Cloud 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 Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.
gcloud
-
Install the Google Cloud CLI. After installation, initialize the Google Cloud CLI by running the following command:
gcloud initIf you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
- 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.
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
For more information, see Authenticate for using REST in the Google Cloud authentication documentation.
-
View VM extension logs
To view VM extension logs, use the Google Cloud console, the Google Cloud CLI, or REST.
Console
- In the Google Cloud console, go to the Logs Explorer page.
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_TIMEReplace 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).
Example query:
resource.type="gce_instance" resource.labels.instance_id="projects/7654321/zones/us-central1-a/instances/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"Click Run query.
gcloud
To look up VM extension logs, use the logging read
command. For example:
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="YOUR_EXTENSION_NAME" AND \
timestamp >= "START_TIME" AND \
timestamp <= "END_TIME"'
Replace the following:
INSTANCE_ID: the ID of the VM instance.YOUR_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
Make a request to the Logging V2
API. The request body must
contain the filter parameter. For example:
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:
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 Google Cloud project ID.
VM extension event log entry
The following is an example of a 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": "projects/7654321/zones/us-west1-a/instances/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 you can find in the VM extension 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 version of the extension that's been selected for installation. This version is either the version pinned in the extension policy or the latest version if no version was pinned. |
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 one for a specific VM. Providing this revision ID to the Google support team can help debug whether the correct binary was chosen for the VM. |
eventType |
The type of event. It can be one of the following values:
|