Esta página foi traduzida pela API Cloud Translation.

Como registrar um agente

Para trabalhar com o Cloud Logging em agentes implantados, use um dos seguintes métodos:

stdout / stderr: por padrão (sem nenhuma configuração adicional), os registros gravados em stdout e stderr serão roteados para os IDs de registro reasoning_engine_stdout e reasoning_engine_stderr, respectivamente. A limitação é que eles precisam ser textos.
Registros do Python: o registrador integrado do Python pode ser integrado ao Cloud Logging. Em comparação com a gravação em stdout ou stderr, essa opção oferece suporte a registros estruturados e requer uma configuração mínima.
Cliente do Cloud Logging: os usuários podem gravar registros estruturados e têm controle total sobre o registrador (por exemplo, definindo o logName e o tipo de recurso).

Gravar registros de um agente

Ao gravar registros de um agente, determine:

gravidade: por exemplo, informações, aviso, erro
Payload: o conteúdo do registro (por exemplo, texto ou JSON)
Outros campos: para correlacionar entre registros (por exemplo, trace/span, tags, rótulos)

Por exemplo, para registrar a entrada de cada consulta ao desenvolver um agente:

stdout ou 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
        )

Geração de registros do 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,
        )

Cliente do 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 o agente é implantado e consultado, ele gera entradas de registro. Por exemplo, o código

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

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

vai gerar uma entrada de registro semelhante a esta:

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

Geração de registros do 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 do 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"
}

Conferir os registros de um agente

É possível conferir as entradas de registro usando o Explorador de registros:

Acesse o Explorador de registros no console do Google Cloud:

Acessar o Explorador de registros
Selecione o projeto Google Cloud (correspondente a PROJECT_ID) na parte de cima da página.
Em Tipo de recurso, selecione Vertex AI Reasoning Engine.

Como criar consultas

É possível usar o Explorador de registros para criar consultas de forma incremental. As consultas geralmente são criadas com base nas seguintes considerações:

Linha do tempo: pesquisar entradas de registro relevantes com base no tempo.
Escopo: pesquisar entradas de registro relevantes com base em atributos canônicos
- resource: separe-o de outros tipos de recursos no projeto.
  - type: aparece como "Vertex AI Reasoning Engine" no Logs Explorer e "aiplatform.googleapis.com/ReasoningEngine" na entrada de registro.
  - labels: para o local (LOCATION), o projeto PROJECT_ID e o recurso RESOURCE_ID.
- logName: o registro ao qual a entrada de registro pertence:
  - As entradas de registro no momento da criação têm o ID reasoning_engine_build.
  - As entradas de registro para stdout e stderr têm o ID de registro reasoning_engine_stdout e reasoning_engine_stderr, respectivamente.
  - As entradas de registro do registro do Python ou do cliente do Cloud Logging terão IDs de registro personalizados com base no seu código em Gravar registros para um agente.
- trace e span: para os registros ao rastrear consultas.
- severity: para a gravidade da entrada de registro.
- insertId: o identificador exclusivo de uma entrada de registro.
rótulos: um mapa de pares de chave-valor que fornece informações adicionais sobre a entrada de registro. Os rótulos podem ser definidos pelo usuário ou pelo sistema e são úteis para categorizar registros e facilitar a pesquisa deles no Explorador de registros.
payload: o conteúdo da entrada de registro.

Confira a seguir um exemplo de consulta para todos os registros INFO de um agente implantado com RESOURCE_ID:

resource.labels.reasoning_engine_id=RESOURCE_ID AND
severity=INFO

É possível conferir essa informação no Explorador de registros em

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

em que a consulta foi codificada corretamente e os outros parâmetros são os seguintes:

DURATION: por exemplo, PT30M nos últimos 30 minutos (ou PT10M nos últimos 10 minutos) e
PROJECT_ID: o projeto Google Cloud .

Para mais detalhes, acesse Criar e salvar consultas usando a linguagem de consulta do Logging.

Consultar registros de um agente

Para uma abordagem programática de registros de consulta, há duas opções comuns:

Linguagem de consulta estruturada (SQL). A Análise de registros permite consultar vistas de registro ou de análise.
- As visualizações de registro têm um esquema fixo que corresponde às entradas de registro.
- As visualizações do Google Analytics têm um esquema baseado nos resultados de uma consulta SQL.
Python. Chame a API Cloud Logging pela biblioteca de cliente da linguagem de programação (Python, neste 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))

Cada entry corresponde a uma LogEntry. Para saber mais sobre os argumentos de entrada para logger.list_entries, acesse a referência da API.

SQL

Visualização de registro:

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

Vista do Google Analytics:

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