Questa pagina è stata tradotta dall'API Cloud Translation.

Registrazione di un agente

Per utilizzare Cloud Logging negli agenti quando vengono dipartiti, utilizza uno dei seguenti metodi:

stdout / 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. L'unica limitazione è che devono essere di testo.
Logging di Python: il logger Python integrato può essere integrato con Cloud Logging. Rispetto alla scrittura in 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 sul logger (ad es. impostando logName e il tipo di risorsa).

Scrivere log per un agente

Quando scrivi i log per un agente, determina:

severity: ad esempio info, warn, error
payload: i contenuti del log (ad es. testo o JSON)
Campi aggiuntivi: per la correlazione tra i log (ad es. traccia/segmento, 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 in 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("K_SERVICE", "").split("-")[-1],
                },
            ),
        )

    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("K_SERVICE", "").split("-")[-1],
                },
            ),
        )

    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 viene eseguita una query, genera voci di log. Ad esempio, il codice

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

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

genererà 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 in 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 di un agente

Puoi visualizzare le voci di log utilizzando Esplora log:

Vai a Esplora log nella console Google Cloud:

Vai a Esplora log
Seleziona il tuo Google Cloud progetto (corrispondente a PROJECT_ID) nella parte superiore della pagina.
In Tipo di risorsa, seleziona Vertex AI Reasoning Engine.

Creazione di query

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

timeline: per cercare voci di log pertinenti in base al tempo
scope: per cercare voci di log pertinenti in base agli attributi canonici
- resource: separala dagli altri tipi di risorse del progetto.
  - type: viene visualizzato come "Vertex AI Reasoning Engine" in Logs Explorer e "aiplatform.googleapis.com/ReasoningEngine" nella voce del 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 logreasoning_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 monitoraggio 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 del log. Le etichette possono essere definite dall'utente o dal sistema e sono utili per classificare i log e semplificarne la ricerca in Logs Explorer.
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://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 e gli altri parametri sono come segue:

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

Per informazioni dettagliate, vedi Creare e salvare query utilizzando il linguaggio di query di Logging.

Esegui query sui log di un agente

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

Structured Query Language (SQL). Log Analytics ti consente di eseguire query sulle viste dei log o sulle viste di analisi.
- Le visualizzazioni log hanno uno schema fisso che corrisponde alle voci di log.
- Le viste di 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 (in questo caso Python).

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 all'API.

SQL

Visualizzazione log:

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

Visualizzazione Dati:

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