Configura il logging

La registrazione è 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 monitorare l'attività, monitorare l'esecuzione e ottimizzare le prestazioni. Questo documento descrive i metodi per scrivere e visualizzare i log per i tuoi 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 verranno indirizzati rispettivamente agli ID log reasoning_engine_stdout e reasoning_engine_stderr. Il limite è che devono essere di tipo testo.
Logging Python: il logger Python integrato può essere integrato con Cloud Logging. Rispetto alla scrittura su stdout o stderr, questa opzione supporta i log strutturati e richiede una configurazione minima.
Client Cloud Logging: gli utenti possono scrivere log strutturati e hanno il controllo completo del 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:

severity: ad esempio info, warn, error
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 implementato e interrogato, 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:

Per ottenere l'autorizzazione a visualizzare i log in Esplora log, chiedi all'amministratore di concederti il ruolo Visualizzatore log (roles/logging.viewer) sul progetto.
Vai a Esplora log nella console Google Cloud :

Vai a Esplora log
Seleziona il tuo progetto Google Cloud (corrispondente a PROJECT_ID) nella parte superiore della pagina.
In Tipo di risorsa, seleziona Motore di ragionamento della piattaforma di agenti Gemini Enterprise.

Per gli agenti basati su Agent Development Kit, puoi anche visualizzare i log del tuo agente nella console Google Cloud 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 di 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 con metodi sincroni e asincroni.
POST /api/stream_reasoning_engine: per le query effettuate ai metodi streaming e streaming asincrono.
POST /api/bidi_reasoning_engine: Per le query effettuate ai metodi di streaming bidirezionale.

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

Creazione di query

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

timeline: per cercare voci di log pertinenti in base all'ora
scope: per cercare voci di log pertinenti in base agli attributi canonici
- risorsa: separala dagli altri tipi di risorse del progetto.
  - type: viene visualizzato come "Motore di ragionamento della piattaforma agentica Gemini Enterprise" 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 compilazione hanno l'ID log reasoning_engine_build.
  - Le voci di log per stdout e stderr hanno rispettivamente ID log reasoning_engine_stdout e reasoning_engine_stderr.
  - Le voci di log di python logging o del client Cloud Logging avranno ID log personalizzati in base al codice in Scrivere log per un agente.
- Traccia e intervallo: 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.
Etichette: una mappa di coppie chiave-valore che fornisce ulteriori informazioni sulla voce di log. Le etichette possono essere definite dall'utente o dal sistema e sono utili per classificare i log e facilitarne 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 di cui è stato eseguito il 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 correttamente in 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 informazioni dettagliate, consulta Creare e salvare query utilizzando il linguaggio di query di Logging.

Esegui query sui log per un agente

Per un approccio programmatico ai log delle query, esistono due opzioni comuni:

Structured Query Language (SQL). Analisi dei log consente di eseguire query su viste log o viste Analytics.
- Le visualizzazioni log hanno uno schema fisso che corrisponde alle voci di log.
- Le viste Analytics hanno uno schema basato sui risultati di una query SQL.
Python. Chiama l'API Cloud Logging tramite la libreria client per il tuo linguaggio di programmazione (Python in questo caso).

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 informazioni dettagliate 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`

Vista Analytics:

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

Configura il logging Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Scrivere log per un agente

stdout o stderr

Logging Python

Client Cloud Logging

stdout o stderr

Logging Python

Client Cloud Logging

Visualizzare i log per un agente

Query di runtime

Creazione di query

Esegui query sui log per un agente

Python

SQL

Configura il logging