Use esta página para saber como visualizar registros, monitorar solicitações e acompanhar traces distribuídos para o tráfego roteado pela implantação do Gateway de Agente.
Cloud Logging
Os registros do Gateway de Agente são gerados usando o
recurso monitorado networkservices.googleapis.com/Gateway.
É possível usar esses registros para monitorar solicitações de acesso ao gateway. Isso inclui os registros criados quando o Gateway de Agente é implantado no modo de teste. Para consultar registros de violação da política de simulação em políticas de acesso unificado (UAPs) do Identity-Aware Proxy (IAP), políticas de governança semântica, Model Armor e VPC Service Controls e gerar um relatório consolidado de "teria sido bloqueado", consulte Auditar violações de política de simulação em controles.
Ver registros de um gateway específico
Para conferir os registros de um gateway específico, siga as etapas abaixo.
Consulta do console
No console do Google Cloud , acesse a página Análise de registros.
Clique no botão Mostrar consulta.
Cole o seguinte no campo de consulta.
resource.type="networkservices.googleapis.com/Gateway" resource.labels.location="REGION" resource.labels.gateway_name="AGENT_GATEWAY_NAME"
Substitua:
REGION: a região do gateway.AGENT_GATEWAY_NAME: o nome do gateway.
Clique em Executar consulta.
Nomes de registro da Agent Platform
Para consultar tipos específicos de entradas de registro na Análise de registros, é possível
filtrar a consulta por nome de registro usando o campo logName. A tabela a seguir
descreve os principais nomes de registro gerados pelo Gateway de Agente
e pelas operações do agente:
| Nome do registro | Descrição |
|---|---|
projects/PROJECT_ID/logs/networkservices.googleapis.com%2Fgateway_requests |
Registros de decisões de permissão e negação do gateway. |
projects/PROJECT_ID/logs/cloudaudit.googleapis.com%2Fdata_access |
Registros de auditoria do Cloud para decisões de AuthorizeUser do IAP. |
projects/PROJECT_ID/logs/aiplatform.googleapis.com%2Freasoning_engine_stderr |
Erros de inicialização e execução do agente (mecanismo de raciocínio stderr). |
projects/PROJECT_ID/logs/aiplatform.googleapis.com%2Freasoning_engine_stdout |
Saída padrão do agente (mecanismo de raciocínio stdout). |
Substitua PROJECT_ID pelo ID do projeto Google Cloud .
Se você usa o Model Armor para limpar o conteúdo, esses registros são emitidos separadamente. Para instruções sobre como consultar registros do Model Armor, consulte Ver registros de segurança de conteúdo brutos na Análise de Registros.
O que é registrado
As entradas de registro do Gateway de Agente contêm informações úteis para monitorar e depurar o tráfego de entrada e saída do gateway.
| Campo | Formato do campo | Tipo de campo: obrigatório ou opcional | Descrição |
|---|---|---|---|
| severity insertID timestamp receiveTimestamp trace traceSampled logName |
LogEntry | Obrigatório | Os campos gerais, conforme descrito em uma entrada de registro. |
| httpRequest | HttpRequest | Obrigatório | Um protocolo comum para o registro de solicitações HTTP. |
| resource | Recurso monitorado | Obrigatório | O |
| jsonPayload: | objeto (formato Struct) | Obrigatório | O payload da entrada de registro, expresso como um objeto JSON. O objeto JSON contém os seguintes campos do Gateway de Agente:
|
Propagação de políticas e latência de ingestão de registros
Ao atualizar as regras de acesso do gateway ou investigar ocorrências de segurança, considere as seguintes janelas de propagação e ingestão:
- Propagação de Políticas de Acesso Unificadas (UAPs):
as atualizações das UAPs aplicadas pelo Gateway de Agente
(como adicionar uma regra
DENYou alternariamEnforcementModede"DRY_RUN"para"ENFORCE") têm consistência posterior. As mudanças diretas na política geralmente entram em vigor em até dois minutos, mas podem levar sete minutos ou mais para serem propagadas globalmente (consulte Propagação de mudanças no acesso). As mudanças na associação a umprincipalSetpodem levar de vários minutos a horas para serem sincronizadas. - Interrupção de tráfego de emergência: as regras de UAP são avaliadas em novas verificações de autorização no Gateway de Agente e não encerram um contêiner de agente nem fecham à força conexões de streaming já estabelecidas. Para interromper imediatamente um agente comprometido ou com comportamento inadequado durante um incidente ativo, exclua o ambiente de execução do agente ou redirecione o tráfego de revisão além de aplicar uma regra de negação de gateway. Para instruções, consulte Parada de emergência e revogação de acesso.
- Latência de registro, rastreamento e descoberta: o Gateway de Agente avalia
as políticas do IAP e do Model Armor de forma síncrona no
caminho da solicitação e grava entradas de registro
networkservices.googleapis.com/gateway_requestsecloudaudit.googleapis.com/data_access(AuthorizeUser) em tempo quase real (normalmente pesquisáveis na Análise de Registros em segundos). Os períodos de trace distribuídos exportados para o Trace também aparecem em segundos após a conclusão do período, enquanto as detecções de ameaças fora de banda da Detecção de Agentes com Anomalias são avaliadas de forma assíncrona (consulte Latência de telemetria e descoberta de segurança).
Reter e exportar registros de auditoria do gateway para um SIEM
Para preservar as decisões de acesso do Gateway de Agente como evidências de conformidade à prova de adulteração e centralizar o monitoramento de ameaças, bloqueie os buckets do Logging e transmita os registros do gateway para uma plataforma de gerenciamento de eventos e informações de segurança (SIEM):
- Retenção inviolável (buckets de registro bloqueados): encaminhe os registros de
networkservices.googleapis.com/gateway_requestsecloudaudit.googleapis.com/data_accesspara um bucket personalizado do Logging com um período de armazenamento configurado (--retention-days) e bloqueie permanentemente o bucket (gcloud logging buckets update BUCKET_ID --location=LOCATION --locked) para aplicar o armazenamento de conformidade de gravação única e várias leituras (WORM, na sigla em inglês). Para instruções detalhadas, consulte Retenção inviolável para registros de auditoria. - Exportação de SIEM: crie um coletor de registros do Logging (ou um
coletor agregado no nível da organização)
com um filtro de inclusão para
logName:("networkservices.googleapis.com%2Fgateway_requests" OR "cloudaudit.googleapis.com%2Fdata_access")para exportar continuamente as decisões de permissão e negação do gateway para o Google Security Operations (Google SecOps), o Pub/Sub (para ingestão de SIEM de terceiros), o BigQuery ou o Cloud Storage. Para comandos de criação de coletores da CLI gcloud e exemplos de filtros, consulte Exportar registros de auditoria para um SIEM.
Cloud Monitoring
O Gateway de Agente exporta algumas métricas de extensões de serviço para o Monitoring. Se você estiver delegando autorização para as extensões de serviço, use essas métricas para monitorar o tráfego de entrada e saída da extensão. Para mais detalhes, consulte Geração de registros e monitoramento para chamadas do Cloud Load Balancing.
Painel de observabilidade
O Gateway de Agente oferece um painel de observabilidade que permite monitorar, auditar e depurar o tráfego roteado pelos gateways:
- Visões gerais: acompanhe o número total de tentativas de autorização, falhas de autorização e solicitações por segundo.
- Gráficos: visualize as taxas de falha de autorização (%) e as solicitações por segundo ao longo do tempo.
- Registros de tráfego de saída: analise registros detalhados de consultas de saída, incluindo
negações de
403, tráfego para endpoints não registrados e tendências gerais de tráfego.
Siga estas etapas para acessar o painel de observabilidade de um gateway no console do Google Cloud :
No console do Google Cloud , acesse a página Gateway de Agente.
Clique no nome do gateway que você quer monitorar.
Clique na guia Observabilidade.
Requisitos de dados do painel
O painel de observabilidade do Gateway de Agente usa
a Análise de Observabilidade para mostrar dados. Se o painel não estiver carregando dados,
faça upgrade do bucket de registros _Default para usar a
Análise de Observabilidade. O painel
recupera dados da _AllLogs
visualização _Default do bucket.
Usar o Cloud Trace
O Gateway de Agente se integra ao Cloud Trace para fornecer observabilidade de solicitações de ponta a ponta para cargas de trabalho de agentes. Como o Gateway de Agente serve como o ponto de controle central para agentes de IA, ativar o Trace oferece visibilidade de como as solicitações viajam dos seus agentes pelo gateway e por vários serviços, ferramentas, agentes e servidores MCP do Google Cloud . Ao rastrear fluxos de solicitação entre esses limites de serviço, o Trace oferece rastreamento distribuído completo para suas arquiteturas de agente.
Com o Trace, é possível:
- Depurar interações de agentes com precisão: acompanhe toda a jornada de uma solicitação entre os limites do serviço para isolar gargalos de latência e chamadas de back-end com falha.
- Respeitar as decisões de amostragem upstream: use a amostragem baseada em pai para manter a continuidade do trace de ponta a ponta quando agentes ou clientes upstream iniciarem o rastreamento, garantindo que as solicitações de alta prioridade sejam totalmente capturadas sem aumentar as taxas de amostragem de referência para o tráfego de rotina.
- Unifique a observabilidade com padrões abertos: criados com base nos padrões OpenTelemetry e W3C TraceContext, os traces propagam o contexto de forma integrada entre seus agentes de IA, o Gateway de Agente, os servidores MCP de destino ou ferramentas e as plataformas de monitoramento de terceiros.
- Acelere a análise da causa raiz: correlacione os períodos de trace diretamente com
os registros e as métricas de solicitação do gateway usando o
trace_idpara resolver problemas de produção com mais rapidez.
Para saber mais sobre o Trace, consulte Visão geral do Cloud Trace.
Funções exigidas
É necessário ter os seguintes papéis do Identity and Access Management (IAM) no projeto:
- Para configurar e atualizar uma política de rastreamento: Administrador de rede do Compute
(
roles/compute.networkAdmin) ou Administrador do Compute (roles/compute.admin) - Para visualizar traces no console do Google Cloud : usuário do Cloud Trace
(
roles/cloudtrace.user)
Além disso, para permitir que o Gateway de Agente grave períodos de trace no Trace, é necessário conceder o papel de agente do Cloud Trace (roles/cloudtrace.agent) às seguintes contas de serviço:
- Agente de serviço do Compute Engine:
service-PROJECT_NUMBER@compute-system.iam.gserviceaccount.com - Agente de serviço de segurança de rede:
service-PROJECT_NUMBER@gcp-sa-networksecurity.iam.gserviceaccount.com - Agente de serviço do Gateway de Agente:
service-PROJECT_NUMBER@gcp-sa-agentgateway.iam.gserviceaccount.com - Conta de serviço da carga de trabalho do agente ou do cliente: se o agente de IA ou a carga de trabalho do cliente que faz a chamada iniciar o trace e exportar os próprios períodos pai para o Trace, a conta de serviço da carga de trabalho ou a conta de serviço personalizada anexada ao agente também precisa receber o papel
roles/cloudtrace.agentno projeto. Caso contrário, apenas o período filho do Gateway de Agente será gravado, e o período pai não vai aparecer no Trace.
Substitua PROJECT_NUMBER pelo número do projeto do Google Cloud .
Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.
Ativar rastreamento
Para ativar o rastreamento do Gateway de Agente, crie um arquivo YAML de política de observabilidade e importe-o usando a CLI gcloud.
Crie um arquivo de configuração chamado
tracing-policy.yaml:name: "projects/PROJECT_ID/locations/REGION/telemetryPolicies/POLICY_NAME" telemetryTarget: resources: # You can attach a policy to multiple gateways - "//networkservices.googleapis.com/projects/PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_NAME" displayName: "Tracing policy for Agent Gateway traffic" tracingConfiguration: samplingRate: SAMPLING_RATE parentBasedSampling: enabled: ENABLE_PARENT_BASED_SAMPLING samplingRate: PARENT_BASED_SAMPLING_RATESubstitua:
PROJECT_ID: o ID do projeto do Google Cloud .REGION: a região do gateway (por exemplo,europe-west1).POLICY_NAME: um nome para a política de observabilidade (por exemplo,my-agw-tracing-policy).AGENT_GATEWAY_NAME: o nome do gateway.SAMPLING_RATE: a fração de solicitações a serem rastreadas. Defina um valor de0.0a1.0. Para ambientes de produção de alto tráfego, recomendamos uma taxa de 1% (0.01) ou 0,1% (0.001) para equilibrar os custos de observabilidade e ingestão.ENABLE_PARENT_BASED_SAMPLING: controla se o bit de amostragem nos cabeçalhostraceparentrecebidos de autores de chamadas upstream será respeitado. Defina comotrueoufalse.PARENT_BASED_SAMPLING_RATE: a fração de solicitações pré-amostradas a serem rastreadas. Defina como um valor de0.0a1.0. Por exemplo,1.0rastreia 100% das solicitações pré-amostradas.
Importe a política de observabilidade:
gcloud beta network-services telemetry-policies import POLICY_NAME \ --source=tracing-policy.yaml \ --location=REGION
Ver traces
Depois de ativar o rastreamento distribuído e enviar tráfego pelo gateway, é possível conferir os detalhes do trace no console do Google Cloud :
-
No console Google Cloud , acesse a página
Explorador de traces:
Acessar o Explorador de traces
Também é possível encontrar essa página usando a barra de pesquisa.
Na barra Filtro, insira uma expressão de filtro de trace (por exemplo, para filtrar por limite de latência, código de status HTTP ou URI de solicitação) ou pesquise pelo ID de trace específico.
Para saber como usar a UI do Buscador de traces, consulte Encontrar e analisar traces.
Explorador de traces
Visualização do Explorador de traces no Trace Visualização da linha do tempo de trace
Visualização da linha do tempo no Trace Visualização de gráfico de trace
Visualização de gráfico no Trace
Correlacionar traces com registros e métricas
O Gateway de Agente oferece uma correlação perfeita entre traces, registros e métricas:
Correlação de registro e trace: cada entrada de registro de solicitação de gateway gravada no Logging contém um campo
tracecom o formato:projects/PROJECT_ID/traces/TRACE_ID.- Na Análise de registros, clique na entrada de registro e selecione Ver detalhes do trace para navegar diretamente para o período correspondente no Trace.
- No Trace, clique em Mostrar registros no painel Detalhes do trace para ver todos os registros de solicitação de gateway associados a essa solicitação.
Correlação de métricas: compare os picos de latência observados nas métricas do Monitoring, como
networkservices.googleapis.com/agentgateway/total_latencies, com os detalhamentos de períodos de trace para identificar se um pico de latência ocorreu no gateway ou na ferramenta ou no servidor de destino.
Solução de problemas
Nesta seção, descrevemos problemas comuns e as soluções para eles.
Os traces não aparecem no Cloud Trace:
Verifique se a API Cloud Trace (
cloudtrace.googleapis.com) está ativada no seu projeto:gcloud services enable cloudtrace.googleapis.com --project=PROJECT_ID
Verifique se os papéis do IAM de agente do Cloud Trace (
roles/cloudtrace.agent) necessários foram concedidos a todas as contas de serviço necessárias.Verifique se a política de observabilidade existe na região correta e se ela faz referência ao gateway de agente apropriado:
gcloud beta network-services telemetry-policies describe POLICY_NAME \ --location=REGIONVerifique o
samplingRateconfigurado. Se o volume de tráfego ou a taxa de amostragem forem baixos, os traces podem não ser capturados imediatamente. Para confirmar se o rastreamento está funcionando, atualize temporariamente sua política para usar 100% de amostragem (samplingRate: 1.00). Restaure a taxa de produção quando terminar o teste.
Períodos de trace incompletos:
Se os períodos de trace aparecerem como traces raiz independentes ou desconectados, em vez de períodos filhos das solicitações do aplicativo, faça o seguinte:
- Verifique se
parentBasedSamplingestá ativado (definido comotrue) na sua política de observabilidade. - Verifique se o agente de IA que faz a chamada ou a conta de serviço da carga de trabalho recebeu o papel de Agente do Cloud Trace (
roles/cloudtrace.agent) no projeto para que os períodos pai possam ser exportados para o Trace. - Verifique se o aplicativo usa um SDK do OpenTelemetry com a propagação de contexto de trace distribuído ativada para que o cabeçalho
traceparentdo W3C seja propagado entre os limites do serviço. Para mais informações, consulte a documentação do propagador TraceContext do OpenTelemetry.
- Verifique se
A seguir
Codelab: controlar cargas de trabalho de agentes com a Agent Platform
Saiba como controlar cargas de trabalho agênticas com o Gateway de Agente na Gemini Enterprise Agent Platform.
Resolver problemas do Gateway de Agente
Saiba como resolver problemas de conectividade do Gateway de Agente.