Visualizza i log delle estensioni VM

Quando utilizzi il gestore di estensioni VM per gestire le estensioni sulle tue istanze Compute Engine (VM), l'agente guest su ogni VM registra gli eventi relativi all'applicazione delle estensioni. Utilizza Cloud Logging per visualizzare questi log in Esplora log per monitorare e risolvere eventuali problemi relativi alle estensioni VM.

Prima di iniziare

  • Leggi la documentazione relativa al gestore di estensioni VM.
  • Scopri come utilizzare Esplora log.
  • Se non l'hai ancora fatto, configura l'autenticazione. L'autenticazione verifica la tua identità per l'accesso ad API e servizi Google Cloud . Per eseguire codice o esempi da un ambiente di sviluppo locale, puoi autenticarti su Compute Engine selezionando una delle seguenti opzioni:

    Seleziona la scheda relativa al modo in cui prevedi di utilizzare gli esempi in questa pagina:

    Console

    Quando utilizzi la console Google Cloud per accedere ai servizi e alle API Google Cloud , non devi configurare l'autenticazione.

    gcloud

    1. Installa Google Cloud CLI, quindi accedi a gcloud CLI con la tua identità federata. Dopo aver eseguito l'accesso, inizializza Google Cloud CLI eseguendo il comando seguente: 

      gcloud init
  • Imposta una regione e una zona predefinite.

    • REST

    Per utilizzare gli esempi di API REST in questa pagina in un ambiente di sviluppo locale, utilizzi le credenziali che fornisci a gcloud CLI.

      Installa Google Cloud CLI, quindi accedi a gcloud CLI con la tua identità federata.

    Per saperne di più, consulta Autenticati per usare REST nella documentazione sull'autenticazione di Google Cloud .

Visualizza i log delle estensioni VM

Per visualizzare i log delle estensioni VM, seleziona una delle seguenti opzioni:

Console

Per visualizzare i log delle estensioni VM nella console Google Cloud , completa i seguenti passaggi:

  1. Nella console Google Cloud , vai alla pagina Esplora log.

    Vai a Esplora log

  2. Nel campo Query, inserisci la seguente 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

    Sostituisci quanto segue:

    • INSTANCE_ID: l'ID dell'istanza VM.
    • EXTENSION_NAME: il nome dell'estensione (ad esempio ops-agent).
    • START_TIME: l'inizio dell'intervallo di tempo (ad esempio, 2024-01-01T00:00:00Z).
    • END_TIME: la fine dell'intervallo di tempo (ad esempio 2024-02-01T00:00:00Z).

    La seguente query di esempio filtra i log per l'estensione ops-agent nell'istanza 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. Fai clic su Esegui query.

gcloud

Per cercare i log delle estensioni VM utilizzando Google Cloud CLI, esegui il comando logging read con un filtro per l'istanza VM e l'estensione:

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

Sostituisci le seguenti variabili con i valori del tuo ambiente:

  • INSTANCE_ID: l'ID dell'istanza VM.
  • EXTENSION_NAME: il nome dell'estensione (ad esempio ops-agent).
  • START_TIME: l'inizio dell'intervallo di tempo (ad esempio 2024-01-01T00:00:00Z).
  • END_TIME: la fine dell'intervallo di tempo (ad esempio 2024-02-01T00:00:00Z).

REST

Per recuperare i log delle estensioni VM utilizzando l'API REST, invia una richiesta POST all'API Logging V2 con il parametro filter nel corpo della richiesta:

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

Sostituisci le seguenti variabili con i valori del tuo ambiente:

  • INSTANCE_ID: l'ID dell'istanza VM.
  • EXTENSION_NAME: il nome dell'estensione (ad esempio ops-agent).
  • START_TIME: l'inizio dell'intervallo di tempo (ad esempio 2024-01-01T00:00:00Z).
  • END_TIME: la fine dell'intervallo di tempo (ad esempio, 2024-02-01T00:00:00Z).
  • PROJECT_ID: il tuo ID progetto Google Cloud .

Voce di log eventi dell'estensione VM

Il seguente snippet JSON mostra una voce di log di esempio per un evento di estensione 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"
}

Dettagli della voce di log

La seguente tabella descrive i parametri visualizzati nei log eventi delle estensioni VM:

Campo Descrizione
eventMessage Un messaggio che descrive l'evento, inclusi lo stato di applicazione e l'integrità dell'estensione.
extensionName Il nome dell'estensione (ad esempio ops-agent).

Per un elenco delle estensioni supportate e dei relativi nomi, consulta Estensioni supportate.
extensionVersion La versione dell'estensione selezionata per l'installazione dal gestore di estensioni VM. Questo valore corrisponde alla versione bloccata nella policy dell'estensione o all'ultima versione disponibile.
revisionId Un file binario specifico di una versione dell'estensione. Ogni versione dell'estensione può avere più revisioni per supportare sistemi operativi diversi e Google sceglie automaticamente il file binario corretto per una VM specifica. Quando contatti l'assistenza clienti Google Cloud, fornisci questo ID revisione per verificare se Google ha selezionato il file binario corretto per la tua VM.
eventType Il tipo di evento. I valori possibili includono:
  • CRASHED: l'estensione ha subito un arresto anomalo. Questo valore indica che l'agente guest ha installato e avviato l'estensione correttamente, ma l'estensione ha smesso di funzionare in un secondo momento.
  • INSTALL_FAILED: l'installazione dell'estensione non è riuscita.
  • INSTALLED: l'agente guest ha installato e avviato l'estensione correttamente.
  • ROLLBACK_FAILED: il rollback dell'estensione non è riuscito.
  • ROLLED_BACK: il rollback dell'estensione è riuscito.
  • INCOMPATIBLE: nessuno dei candidati alla revisione dell'estensione soddisfa i requisiti di installazione (ad esempio, sistema operativo o architettura).
  • SERVICE_DISABLED: il servizio che richiede questa estensione è disattivato.

Passaggi successivi