Registrar un agente

Para trabajar con Cloud Logging en agentes cuando se implementan, utilice uno de los siguientes métodos:

• stdout/stderr: de forma predeterminada (sin ninguna configuración adicional), los registros escritos en stdout y stderr se dirigirán a los IDs de registro reasoning_engine_stdout y reasoning_engine_stderr, respectivamente. La limitación es que deben ser de texto.
• Registro de Python: el registrador de Python integrado se puede integrar con Cloud Logging. En comparación con la escritura en stdout o stderr, esta opción admite registros estructurados y requiere una configuración mínima.
• Cliente de Cloud Logging: los usuarios pueden escribir registros estructurados y tienen control total sobre el registrador (por ejemplo, pueden definir el logName y el tipo de recurso).

Escribir registros de un agente

Al escribir registros de un agente, determina lo siguiente:

• Gravedad: por ejemplo, info, warn o error.
• Carga útil: el contenido del registro (por ejemplo, texto o JSON).
• Campos adicionales: para correlacionar registros (por ejemplo, trazas o intervalos, etiquetas)

Por ejemplo, para registrar la entrada de cada consulta al desarrollar un agente, haz lo siguiente:

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
        )

Registro de 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,
        )

Cliente de 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,
        )

Cuando el agente se implemente y se consulte, generará entradas de registro. Por ejemplo, el código

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

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

generará una entrada de registro similar a la siguiente:

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

Registro de 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"
}

Cliente de 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"
}

Ver los registros de un agente

Puedes ver tus entradas de registro con el Explorador de registros:

1. Para obtener permiso para ver los registros en el Explorador de registros, pide a tu administrador que te conceda el rol Lector de registros (roles/logging.viewer) en tu proyecto.

2. Ve al Explorador de registros de la Google Cloud consola:

   Ir a Explorador de registros

3. Selecciona tu Google Cloud proyecto (correspondiente a PROJECT_ID) en la parte superior de la página.

4. En Tipo de recurso, selecciona Vertex AI Reasoning Engine.

Crear consultas

Puedes usar el Explorador de registros para crear consultas de forma incremental. Las consultas se suelen crear en función de los siguientes aspectos:

• Cronología: para buscar entradas de registro relevantes en función de la hora
• scope: para buscar entradas de registro relevantes en función de los atributos canónicos.
  • Recurso: sepáralo de otros tipos de recursos de tu proyecto.
    • type: se muestra como "Vertex AI Reasoning Engine" en el Explorador de registros y "aiplatform.googleapis.com/ReasoningEngine" en la entrada de registro.
    • labels: para la ubicación (LOCATION), el proyecto PROJECT_ID y el recurso RESOURCE_ID.
  • logName el registro al que pertenece la entrada de registro:
    • Las entradas de registro en tiempo de compilación tienen el ID de registro reasoning_engine_build.
    • Las entradas de registro de stdout y stderr tienen los IDs de registro reasoning_engine_stdout y reasoning_engine_stderr, respectivamente.
    • Las entradas de registro de python logging o del cliente de Cloud Logging tendrán IDs de registro personalizados basados en tu código en Escribir registros de un agente.
  • Trazas y intervalos: para los registros cuando se rastrean consultas.
  • severity: la gravedad de la entrada de registro.
  • insertId: el identificador único de una entrada de registro.
• labels: un mapa de pares clave-valor que proporciona información adicional sobre la entrada de registro. Las etiquetas pueden ser definidas por el usuario o por el sistema, y son útiles para clasificar los registros y facilitar su búsqueda en el Explorador de registros.
• Carga útil: el contenido de la entrada de registro.

A continuación se muestra un ejemplo de consulta de todos los registros INFO de un agente implementado con RESOURCE_ID:

resource.labels.reasoning_engine_id=RESOURCE_ID AND
severity=INFO

Puedes verlo en el explorador de registros en

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

donde la consulta se ha codificado correctamente como URL y los demás parámetros son los siguientes:

• DURATION: por ejemplo, PT30M durante los últimos 30 minutos (o PT10M durante los últimos 10 minutos).
• PROJECT_ID: el Google Cloud proyecto.

Para obtener más información, consulta el artículo Crear y guardar consultas con el lenguaje de consultas de registro.

Nota: El Explorador de registros no admite operaciones de agregación, como contar el número de entradas de registro que contienen un patrón específico. Para consultar información más avanzada sobre operaciones agregadas y otras cuestiones, consulta el artículo Consultar registros de un agente.

Consultar los registros de un agente

Si quieres consultar los registros de forma programática, tienes dos opciones habituales:

• Lenguaje de consulta estructurado (SQL). Analíticas de registros te permite consultar vistas de registros o vistas de analíticas.
  • Las vistas de registro tienen un esquema fijo que corresponde a las entradas de registro.
  • Las vistas de Analytics tienen un esquema basado en los resultados de una consulta de SQL.

• Python. Llama a la API Cloud Logging a través de la biblioteca de cliente de tu lenguaje de programación (en este 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))

Cada entry se corresponderá con un LogEntry. Para obtener información sobre los argumentos de entrada de logger.list_entries, consulta la referencia de la API.

SQL

Vista de registro:

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

Vista de Analytics:

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