Configura il logging

Il logging è essenziale per comprendere ed eseguire il debug del comportamento degli agenti. Quando esegui il deployment di un agente in Agent Runtime, puoi utilizzare Cloud Logging per rilevare l'attività, monitorare l'esecuzione e ottimizzare le prestazioni. Questo documento descrive i metodi per scrivere e visualizzare i log per gli agenti.

Per utilizzare Cloud Logging negli agenti quando vengono sottoposti a deployment in Agent Runtime, utilizza uno dei seguenti metodi:

  • stdout o stderr: per impostazione predefinita (senza alcuna configurazione aggiuntiva), i log scritti su stdout e stderr vengono indirizzati rispettivamente agli ID log reasoning_engine_stdout e reasoning_engine_stderr. La limitazione è che devono essere di testo.
  • Logging Python: il logger Python integrato può essere integrato con Cloud Logging. Rispetto alla scrittura su stdout o stderr, supporta i log strutturati e richiede una configurazione minima.
  • Client Cloud Logging: gli utenti possono scrivere log strutturati e hanno il controllo completo sul logger (ad esempio, impostando logName e il tipo di risorsa).

Scrivere log per un agente

Quando scrivi i log per un agente, determina quanto segue:

  • Gravità: ad esempio informazioni, avviso, errore
  • Payload: i contenuti del log (ad esempio testo o JSON)
  • Campi aggiuntivi: per la correlazione tra i log (ad esempio trace/span, tag, etichette)

Ad esempio, per registrare l'input di ogni query durante lo sviluppo di un agente:

stdout o stderr 

from typing import Dict

class MyAgent:

    def set_up(self):
        # No set up required. The logs from stdout and stderr are routed to
        # `reasoning_engine_stdout` and `reasoning_engine_stderr` respectively.
        pass

    def query(self, input: Dict):
        import sys

        print(
            f"input: {input}",
            file=sys.stdout,  # or sys.stderr
        )

Logging Python 

from typing import Dict

class MyAgent:

    def set_up(self):
        import os
        import google.cloud.logging

        self.logging_client = google.cloud.logging.Client(project="PROJECT_ID")
        self.logging_client.setup_logging(
            name="LOG_ID",  # the ID of the logName in Cloud Logging.
            resource=google.cloud.logging.Resource(
                type="aiplatform.googleapis.com/ReasoningEngine",
                labels={
                    "location": "LOCATION",
                    "resource_container": "PROJECT_ID",
                    "reasoning_engine_id": os.environ.get("GOOGLE_CLOUD_AGENT_ENGINE_ID", ""),
                },
            ),
        )

    def query(self, input: Dict):
        import logging
        import json

        logging_extras = {
            "labels": {"foo": "bar"},
            "trace": "TRACE_ID",
        }

        logging.info( # or .warning(), .error()
            json.dumps(input),
            extra=logging_extras,
        )

Client Cloud Logging 

from typing import Dict

class MyAgent:

    def set_up(self):
        import os
        import google.cloud.logging

        self.logging_client = google.cloud.logging.Client(project="PROJECT_ID")
        self.logger = self.logging_client.logger(
            name="LOG_ID",  # the ID of the logName in Cloud Logging.
            resource=google.cloud.logging.Resource(
                type="aiplatform.googleapis.com/ReasoningEngine",
                labels={
                    "location": "LOCATION",
                    "resource_container": "PROJECT_ID",
                    "reasoning_engine_id": os.environ.get("GOOGLE_CLOUD_AGENT_ENGINE_ID", ""),
                },
            ),
        )

    def query(self, input: Dict):
        logging_extras = {
            "labels": {"foo": "bar"},
            "trace": "TRACE_ID",
        }

        self.logger.log_struct(
            input,
            severity="INFO",  # or "DEBUG", "WARNING", "ERROR", "CRITICAL"
            **logging_extras,
        )

Quando l'agente viene sottoposto a deployment e viene eseguita una query, genera voci di log. Ad esempio, il seguente codice:

remote_agent = agent_engines.create(
    MyAgent(),
    requirements=["cloudpickle==3", "google-cloud-logging"],
)

remote_agent.query(input={"hello": "world"})

genera una voce di log simile alla seguente:

stdout o stderr 

{
  "insertId": "67a3bb3b000cc2df444361ab",
  "textPayload": "input: {'hello': 'world'}",
  "resource": {
    "type": "aiplatform.googleapis.com/ReasoningEngine",
    "labels": {
      "location": "LOCATION",
      "resource_container": "PROJECT_ID",
      "reasoning_engine_id": "RESOURCE_ID"
    }
  },
  "timestamp": "2025-02-05T19:25:47.836319Z",
  "logName": "projects/PROJECT_ID/logs/aiplatform.googleapis.com%2Freasoning_engine_stdout",  # or `*_stderr`
  "receiveTimestamp": "2025-02-05T19:25:47.842550772Z"
}

Logging Python 

{
  "insertId": "1ek9a2jfqh777z",
  "jsonPayload": {"hello": "world"},
  "resource": {
    "type": "aiplatform.googleapis.com/ReasoningEngine",
    "labels": {
      "location": "LOCATION",
      "resource_container": "PROJECT_ID",
      "reasoning_engine_id": "RESOURCE_ID",
    }
  },
  "timestamp": "2025-02-05T20:30:19.348067Z",
  "severity": "INFO",
  "labels": {
    "foo": "bar",
    "python_logger": "root",
  },
  "logName": "projects/PROJECT_ID/logs/LOG_ID",
  "trace": "TRACE_ID",
  "receiveTimestamp": "2025-01-30T21:38:50.776813191Z"
}

Client Cloud Logging 

{
  "insertId": "1ek9a2jfqh777z",
  "jsonPayload": {"hello": "world"},
  "resource": {
    "type": "aiplatform.googleapis.com/ReasoningEngine",
    "labels": {
      "location": "LOCATION",
      "resource_container": "PROJECT_ID",
      "reasoning_engine_id": "RESOURCE_ID",
    }
  },
  "timestamp": "2025-01-30T21:38:50.776813191Z",
  "severity": "INFO",
  "labels": {"foo": "bar"},
  "logName": "projects/PROJECT_ID/logs/LOG_ID",
  "trace": "TRACE_ID",
  "receiveTimestamp": "2025-01-30T21:38:50.776813191Z"
}

Visualizzare i log per un agente

Puoi visualizzare le voci di log utilizzando Esplora log:

  1. Per ottenere l'autorizzazione a visualizzare i log in Esplora log, chiedi all'amministratore di concederti il ruolo Visualizzatore log (roles/logging.viewer) sul tuo progetto.

  2. Vai a Esplora log nella Google Cloud console:

    Vai a Esplora log

  3. Seleziona il tuo Google Cloud progetto (corrispondente a PROJECT_ID) nella parte superiore della pagina.

  4. In Tipo di risorsa, seleziona Motore di ragionamento della piattaforma agentica Gemini Enterprise.

Per gli agenti basati su Agent Development Kit, puoi anche visualizzare i log del tuo agente in la Google Cloud console utilizzando la dashboard di Agent Runtime.

Query di runtime

Puoi filtrare i log in Cloud Logging in base a ogni operazione supportata di un agente sottoposto a deployment. Per farlo, filtra i log in base all'endpoint REST sottostante per ogni query di operazione:

  • POST /api/reasoning_engine: per le query effettuate su metodi sincroni e asincroni.
  • POST /api/stream_reasoning_engine: per le query effettuate su metodi di streaming e streaming asincroni.
  • POST /api/bidi_reasoning_engine: per le query effettuate su metodi di streaming bidirezionali.

Le query di runtime vengono indirizzate agli endpoint REST a seconda del campo api_mode nell'elenco delle operazioni supportate di un agente sottoposto a deployment.

Creazione di query

Puoi utilizzare Esplora log per creare query in modo incrementale. Le query vengono in genere create in base alle seguenti considerazioni:

  • Sequenza temporale: per cercare voci di log pertinenti in base all'ora
  • Ambito: per cercare voci di log pertinenti in base agli attributi canonici
    • Risorsa: separala da altri tipi di risorse nel tuo progetto.
      • type: viene visualizzato come "Gemini Enterprise Agent Platform Reasoning Engine" in Esplora log e "aiplatform.googleapis.com/ReasoningEngine" nella voce di log.
      • labels: per la località (LOCATION), il progetto PROJECT_ID e la risorsa RESOURCE_ID.
    • logName: il log a cui appartiene la voce di log:
      • Le voci di log in fase di build hanno l'ID log reasoning_engine_build.
      • Le voci di log per stdout e stderr hanno rispettivamente gli ID log reasoning_engine_stdout e reasoning_engine_stderr.
      • Le voci di log del logging Python o del client Cloud Logging avranno ID log personalizzati in base al codice in Scrivere log per un agente.
    • trace e span: per i log durante il tracciamento delle query.
    • severity: per la gravità della voce di log.
    • insertId: l'identificatore univoco di una voce di log.
  • labels: una mappa di coppie chiave-valore che fornisce informazioni aggiuntive sulla voce di log. Le etichette possono essere definite dall'utente o dal sistema e sono utili per classificare i log e semplificarne la ricerca in Esplora log.
  • payload: i contenuti della voce di log.

Di seguito è riportato un esempio di query per tutti i log INFO di un agente sottoposto a deployment con RESOURCE_ID:

resource.labels.reasoning_engine_id=RESOURCE_ID AND
severity=INFO

Puoi visualizzarlo in Esplora log all'indirizzo

https://https://console.cloud.google.com/logs/query;query=severity%3DINFO%0Aresource.labels.reasoning_engine_id%3D%22RESOURCE_ID%22;duration=DURATION?project=PROJECT_ID

dove la query è stata codificata in modo appropriato tramite URL e gli altri parametri sono i seguenti:

  • DURATION: ad esempio PT30M per gli ultimi 30 minuti (o PT10M per gli ultimi 10 minuti) e
  • PROJECT_ID: il Google Cloud progetto.

Per i dettagli, consulta Creare e salvare query utilizzando il linguaggio di query di Logging.

Eseguire query sui log per un agente

Per un approccio programmatico alle query sui log, esistono due opzioni comuni:

Python 

from google.cloud import logging

logging_client = logging.Client(project="PROJECT_ID")
logger = logging_client.logger("LOG_ID")  # E.g. "logging_client"
print("Listing entries for logger {}:".format(logger.name))
for entry in logger.list_entries(
    filter_="resource.labels.reasoning_engine_id=RESOURCE_ID"  # Optional
):
    timestamp = entry.timestamp.isoformat()
    print("* {}: {}".format(timestamp, entry.payload))

Ogni entry corrisponderà a un LogEntry. Per i dettagli sugli argomenti di input di logger.list_entries, consulta il riferimento API.

SQL

Visualizzazione log:

SELECT *
FROM `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID`

Visualizzazione di analisi:

SELECT *
FROM `analytics_view.PROJECT_ID.LOCATION.ANALYTICS_VIEW_ID`