Monitorar o tráfego pelo Agent Gateway

Use esta página para saber como ver registros, monitorar solicitações e rastrear traces distribuídos para o tráfego roteado pela implantação do Gateway de Agente.

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.

Ver registros de um gateway específico

Para conferir os registros de um gateway específico, siga estas etapas.

Consulta do console

1. No console do Google Cloud , acesse a página Análise de registros.

   Acessar Análise de registros

2. Clique no botão Mostrar consulta.

3. 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.

4. Clique em Executar consulta.

Nomes de registros da Agent Platform

Para consultar tipos específicos de entradas de registro na Análise de registros, filtre a consulta por nome do registro usando o campo logName. A tabela a seguir descreve os principais nomes de registros gerados pelo Gateway de Agente e pelas operações do lado 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 do Identity-Aware Proxy (IAP) AuthorizeUser.
projects/PROJECT_ID/logs/aiplatform.googleapis.com%2Freasoning_engine_stderr	Erros de inicialização e execução do lado do agente (mecanismo de raciocínio stderr).
projects/PROJECT_ID/logs/aiplatform.googleapis.com%2Freasoning_engine_stdout	Saída padrão do lado do agente (mecanismo de raciocínio stdout).

Substitua PROJECT_ID pelo ID do projeto Google Cloud .

Se você usa o Model Armor para higienização de conteúdo, esses registros são emitidos separadamente. Para instruções sobre como consultar registros do Model Armor, consulte Ver registros brutos de segurança de conteúdo na Análise de registros.

Importante:ao consultar registros, um período de atualização curto (por exemplo, --freshness=6h em consultas de linha de comando) às vezes pode retornar zero linhas, mesmo que os registros tenham sido gerados recentemente. Se a consulta retornar resultados vazios, tente ampliar a janela de pesquisa (por exemplo, para --freshness=1d) e verifique se a geração de registros está desativada.

O que é registrado

As entradas de registro do gateway de agente contêm informações úteis para monitorar e depurar o tráfego de e para o 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 MonitoredResource é o tipo de recurso associado a uma entrada de registro. O tipo de recurso do Gateway de Agente é networkservices.googleapis.com/Gateway.
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: agentGatewayInfo: inclui informações sobre solicitações do Gateway de Agente. mcpInfo: inclui informações sobre o método MCP da solicitação (por exemplo, "tools/list" ou "tools/call") e o parâmetro principal associado ao método, se houver. Por exemplo, no caso do método "tools/call", o parâmetro é o nome da ferramenta. agentRegistryResource: o nome do recurso do Agent Registry do servidor MCP, do agente ou do endpoint que correspondeu à solicitação. Também é possível inspecionar os detalhes do campo serviceExtensionsInfo para informações sobre a extensão de autorização (IAP, Model Armor ou outra) que processou a solicitação.

Monitoramento

O Gateway de Agente exporta algumas métricas de Service Extensions para o Cloud Monitoring. Se você estiver delegando a autorização para Service Extensions, use essas métricas para monitorar o tráfego de e para sua extensão. Para mais detalhes, consulte Geração de registros e monitoramento de destaques 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:

• Scorecards: acompanhe o número total de autorizações tentadas, 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 :

1. No console Google Cloud , acesse a página Gateway de agente.

   Acessar o Gateway de Agente

2. Clique no nome do gateway que você quer monitorar.

3. 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 do bucket _Default.

Usar o Cloud Trace

Visualizar

Este produto ou recurso está sujeito aos "Termos das Soluções Pré-GA" na seção "Termos Gerais de Serviço" dos Termos Específicos de Serviço. Os produtos e recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

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, a ativação do rastreamento oferece visibilidade de como as solicitações viajam dos seus agentes pelo gateway e por vários Google Cloud serviços, ferramentas, agentes e servidores MCP. Ao rastrear fluxos de solicitações entre esses limites de serviço, o Trace oferece rastreamento distribuído completo para suas arquiteturas de agentes.

Com o Trace, é possível fazer o seguinte:

• Depure interações do agente com precisão: acompanhe toda a jornada de uma solicitação nas fronteiras 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 com base no pai para manter a continuidade do rastreamento de ponta a ponta quando agentes ou clientes upstream iniciam o rastreamento, garantindo que as solicitações de alta prioridade sejam totalmente capturadas sem aumentar as taxas de amostragem de linha de base para o tráfego rotineiro.
• Unifique a observabilidade com padrões abertos: criado com base nos padrões OpenTelemetry e W3C TraceContext, os rastreamentos propagam o contexto de maneira integrada nos seus agentes de IA, no Gateway de Agente, nos servidores ou ferramentas MCP de destino e nas plataformas de monitoramento de terceiros.
• Acelere a análise da causa raiz: correlacione intervalos de rastreamento diretamente com registros e métricas de solicitações de gateway usando trace_id para resolver problemas de produção mais rápido.

Para saber mais sobre o Trace, consulte a visão geral do Cloud Trace.

Funções exigidas

Você precisa ter os seguintes papéis do Identity and Access Management (IAM) no seu 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 ver traces no console Google Cloud : usuário do Cloud Trace (roles/cloudtrace.user)

Além disso, para permitir que o Agent Gateway grave intervalos de rastreamento no Trace, conceda o papel de agente do Cloud Trace (roles/cloudtrace.agent) às seguintes contas de serviço:

• Agente de serviço do Compute Engine: [e-mail]
• Agente de serviço de segurança de rede: [e-mail]
• Agente de serviço do Gateway de Agente: [e-mail]
• Conta de serviço do agente ou da carga de trabalho do cliente: se o agente de IA ou a carga de trabalho do cliente que faz a chamada iniciar o rastreamento e exportar os próprios intervalos principais para o Trace, a conta de serviço da carga de trabalho ou a conta de serviço personalizada anexada ao agente também precisará receber a função roles/cloudtrace.agent no projeto. Caso contrário, apenas o intervalo filho do gateway do agente será gravado, e o intervalo pai vai ficar faltando no rastreamento.

Substitua PROJECT_NUMBER pelo número do projeto 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.

1. 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_RATE
   

   Substitua:

   • 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 como um valor de 0.0 a 1.0. Para ambientes de produção com tráfego alto, recomendamos uma taxa de 1% (0.01) ou 0,1% (0.001) para equilibrar a capacidade de observação e os custos de ingestão.
   • ENABLE_PARENT_BASED_SAMPLING: controla se o bit de amostra nos cabeçalhos traceparent recebidos de chamadores upstream será respeitado. Defina como true ou false.
   • PARENT_BASED_SAMPLING_RATE: a fração de solicitações pré-amostradas a serem rastreadas. Defina como um valor de 0.0 a 1.0. Por exemplo, 1.0 rastreia 100% das solicitações pré-amostradas.

2. 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 rastreamento no console Google Cloud :

1. 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.

2. Na barra Filtro, insira uma expressão de filtro de rastreamento (por exemplo, para filtrar por limite de latência, código de status HTTP ou URI de solicitação) ou pesquise pelo ID de rastreamento específico.

   Para saber mais sobre como usar a UI do explorador de rastreamentos, consulte Encontrar e explorar rastreamentos.

   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 do gráfico de rastreamento

   

   Visualização de gráfico no Trace

Correlacionar traces com registros e métricas

O Gateway de Agente oferece correlação perfeita entre rastreamentos, registros e métricas:

• Correlação de registros e rastreamentos: cada entrada de registro de solicitação de gateway gravada no Cloud Logging contém um campo trace com o formato projects/PROJECT_ID/traces/TRACE_ID.

  • No Análise de registros, clique na entrada de registro e selecione Ver detalhes do trace para navegar diretamente até 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 do gateway associados a essa solicitação.

• Correlação de métricas: compare picos de latência observados nas métricas do Cloud Monitoring, como networkservices.googleapis.com/agentgateway/total_latencies, com detalhamentos de intervalos de rastreamento para identificar se um pico de latência ocorreu no gateway ou na ferramenta ou servidor de destino.

Solução de problemas

Esta seção descreve problemas comuns e as respectivas soluções.

• Os traces não aparecem no Cloud Trace:

  1. Verifique se a API Cloud Trace (cloudtrace.googleapis.com) está ativada no seu projeto:

     gcloud services enable cloudtrace.googleapis.com --project=PROJECT_ID
     

  2. Verifique se os papéis do IAM do agente do Cloud Trace (roles/cloudtrace.agent) necessários foram concedidos a todas as contas de serviço necessárias.

  3. Verifique se a política de observabilidade existe na região correta e se ela faz referência ao gateway do Gateway de Agente apropriado:

     gcloud beta network-services telemetry-policies describe POLICY_NAME \
         --location=REGION
     

  4. Verifique o samplingRate configurado. Se o volume de tráfego ou a taxa de amostragem for baixa, os rastreamentos poderão não ser capturados imediatamente. Para confirmar se o rastreamento está funcionando, atualize temporariamente sua política para usar amostragem de 100% (samplingRate: 1.00). Restaure a taxa de produção quando terminar o teste.

• Períodos de trace incompletos:

  Se os intervalos de rastreamento aparecerem como rastreamentos raiz independentes ou desconectados em vez de intervalos filhos das solicitações do aplicativo, faça o seguinte:

  1. Verifique se parentBasedSampling está ativado (definido como true) na política de observabilidade.
  2. Verifique se a conta de serviço do agente de IA ou da carga de trabalho que está fazendo a chamada recebeu o papel de agente do Cloud Trace (roles/cloudtrace.agent) no projeto para que os intervalos principais possam ser exportados para o Trace.
  3. Verifique se o aplicativo usa um SDK do OpenTelemetry com a propagação de contexto de rastreamento distribuído ativada para que o cabeçalho traceparent do W3C seja propagado entre os limites do serviço. Para mais informações, consulte a documentação do propagador TraceContext do OpenTelemetry.

A seguir

Codelab

Codelab: governar cargas de trabalho de agentes com a Agent Platform

Aprenda a governar cargas de trabalho com agentes com o Gateway de Agente na Gemini Enterprise Agent Platform.

Solução de problemas

Resolver problemas do Gateway de Agente

Saiba como resolver problemas de conectividade do Gateway de Agente.