Monitorar o tráfego pelo Agent Gateway

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

  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 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 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, agente ou endpoint que correspondeu à solicitação.
  • Também é possível inspecionar os detalhes do campo serviceExtensionsInfo para conferir informações sobre a extensão de autorização (IAP, Model Armor ou outra) que processou a solicitação.

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 DENY ou alternar iamEnforcementMode de "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 um principalSet podem 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_requests e cloudaudit.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_requests e cloudaudit.googleapis.com/data_access para 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 :

  1. No console do 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 _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_id para 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.agent no 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.

  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 um valor de 0.0 a 1.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çalhos traceparent recebidos de autores de chamadas 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 trace no console do 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 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 do Explorador de traces no Trace

    Visualização da linha do tempo de trace

    Visualização da linha do tempo no Trace
    Visualização da linha do tempo no Trace

    Visualização de gráfico de trace

    Visualização de gráfico no 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 trace com 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:

    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 de 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 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 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:

    1. Verifique se parentBasedSampling está ativado (definido como true) na sua política de observabilidade.
    2. 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.
    3. 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 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

Saiba como controlar cargas de trabalho agênticas com o Gateway de Agente na Gemini Enterprise Agent Platform.

Solução de problemas

Saiba como resolver problemas de conectividade do Gateway de Agente.