Para trabalhar com o Cloud Logging em agentes quando eles são implantados no ambiente de execução do agente, use um dos seguintes métodos:
stdoutoustderr: por padrão (sem nenhuma configuração adicional), os registros gravados em stdout e stderr serão encaminhados para os IDs de registroreasoning_engine_stdoutereasoning_engine_stderr, respectivamente. A limitação é que eles precisam ser texto.- Geração de registros em Python: o logger integrado do Python pode ser integrado ao Cloud Logging. Em comparação com a gravação em stdout ou stderr, isso oferece suporte a registros estruturados e requer configuração mínima.
- Cliente do Cloud Logging: os usuários podem gravar registros estruturados e têm controle total sobre o logger (por exemplo, definindo o
logNamee o tipo de recurso).
Gravar registros para um agente
Ao gravar registros para um agente, determine o seguinte:
- severity: como info, warn, error
- payload: o conteúdo do registro (como texto ou JSON).
- Campos adicionais: para correlação entre registros (como trace/período, 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
)
Registro em 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 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("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 o agente é implantado e consultado, ele gera entradas de registro. Por exemplo, o código a seguir:
remote_agent = agent_engines.create(
MyAgent(),
requirements=["cloudpickle==3", "google-cloud-logging"],
)
remote_agent.query(input={"hello": "world"})
gera 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"
}
Registro em 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"
}
Ver registros de um agente
É possível ver as entradas de registro usando o Análise de registros:
Para receber permissão para ver registros na Análise de registros, peça ao administrador para conceder a você o papel de visualizador de registros (
roles/logging.viewer) no seu projeto.Acesse a Análise de registros no console do Google Cloud :
Selecione seu projeto Google Cloud (correspondente a
PROJECT_ID) na parte de cima da página.Em Tipo de recurso, selecione Mecanismo de raciocínio da plataforma de agentes do Gemini Enterprise.
Para agentes baseados no Kit de Desenvolvimento de Agente, também é possível conferir os registros do agente no console do Google Cloud usando o painel de controle do tempo de execução do agente.
Consultas de tempo de execução
É possível filtrar os registros no Cloud Logging por cada operação compatível de um agente implantado. Para isso, filtre os registros com base no endpoint REST subjacente de cada consulta de operação:
POST /api/reasoning_engine: para consultas feitas a métodos síncronos e assíncronos.POST /api/stream_reasoning_engine: para consultas feitas aos métodos de streaming e streaming assíncrono.POST /api/bidi_reasoning_engine: para consultas feitas a métodos de streaming bidirecional.
As consultas de tempo de execução são
encaminhadas para os endpoints REST dependendo do campo api_mode na lista de
operações compatíveis de um agente implantado.
Como criar consultas
É possível usar a Análise de registros para criar consultas de forma incremental. As consultas geralmente são criadas com base nas seguintes considerações:
- timeline: para pesquisar entradas de registro relevantes com base no tempo
- scope: para pesquisar entradas de registro relevantes com base em atributos canônicos
- resource: separe-o de outros tipos de recursos no seu projeto.
type: aparece como "Mecanismo de raciocínio da plataforma de agentes do Gemini Enterprise" na Análise de registros e"aiplatform.googleapis.com/ReasoningEngine"na entrada de registro.labels: para o local (LOCATION), o projetoPROJECT_IDe o recursoRESOURCE_ID.
- logName: o registro a que a entrada de registro pertence:
- As entradas de registro no momento da build têm o ID
reasoning_engine_build. - As entradas de registro para
stdoutestderrtêm ID de registroreasoning_engine_stdoutereasoning_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.
- As entradas de registro no momento da build têm o ID
- trace e span: para os registros ao consultar rastreamentos.
- severity: para a gravidade da entrada de registro.
- insertId: o identificador exclusivo de uma entrada de registro.
- resource: separe-o de outros tipos de recursos no seu projeto.
- labels: 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 na Análise 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 no Análise de registros em
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
em que a consulta foi codificada por URL de maneira adequada e os outros parâmetros são os seguintes:
DURATION: por exemplo,PT30Mnos últimos 30 minutos ouPT10Mnos últimos 10 minutos.PROJECT_ID: o Google Cloud projeto.
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 consulta de registros, há duas opções comuns:
- Structured Query Language (SQL). Com a Análise de Registros, é possível consultar vistas de registros ou vistas de análise.
- As visualizações de registros têm um esquema fixo que corresponde às entradas de registro.
- As visualizações de análise têm um esquema baseado nos resultados de uma consulta SQL.
Python. Chame a API Cloud Logging usando a biblioteca de cliente da sua 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 vai corresponder a um LogEntry.
Para detalhes sobre os argumentos de entrada de logger.list_entries, acesse a
referência da API.
SQL
SELECT *
FROM `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID`
SELECT *
FROM `analytics_view.PROJECT_ID.LOCATION.ANALYTICS_VIEW_ID`