Observação:este conjunto de documentação é para as edições Standard, Plus e Frontline do Gemini Enterprise. Para acessar a documentação da edição Business, consulte a Central de Ajuda do Gemini Enterprise - edição Business.

O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Correlacionar registros do Model Armor com registros do Gemini Enterprise

Este documento descreve como correlacionar registros de sanitização do Model Armor com registros e intervalos de rastreamento da plataforma Gemini Enterprise no Cloud Logging. Ele explica os mecanismos de correlação para fluxos de tráfego do cliente para o agente (entrada) e do agente para qualquer lugar (saída), descreve os pré-requisitos para a geração de rastreamento e fornece instruções detalhadas e exemplos de código para unir essas entradas de registro no pipeline de processamento de registros.

Ao investigar um intervalo de rastreamento ou uma entrada de registro do Model Armor, talvez seja necessário localizar os registros correspondentes no Cloud Logging para ter o contexto completo da solicitação. Exemplo:

Se você começar com um trace span, talvez seja necessário determinar a identidade do usuário final ou inspecionar as descobertas detalhadas de sanitização.
Se você começar com uma entrada de registro de sanitização do Model Armor, talvez seja necessário correlacioná-la com a identidade do usuário ou informações de rastreamento.

Como funciona a correlação de registros

O Model Armor pode filtrar comandos e respostas nos seguintes pontos de comunicação no Gemini Enterprise:

Tráfego do cliente para o agente (entrada): quando um usuário envia um comando ao assistente do Gemini Enterprise, o Gemini Enterprise chama diretamente as APIs do Model Armor. Os registros da plataforma Model Armor resultantes (SanitizeOperation) não contêm diretamente os campos trace ou spanId do OpenTelemetry. Para correlacionar esses registros com identidades de usuário e intervalos de rastreamento, faça uma junção de registros no gerenciamento de informações de segurança e eventos (SIEM) ou no pipeline de processamento de registros usando o token de sessão.
Tráfego do agente para qualquer lugar (saída): quando um agente chama uma ferramenta externa, um servidor do Protocolo de Contexto de Modelo (MCP) ou um modelo de linguagem grande (LLM) externo, o tráfego é encaminhado pelo Gateway de Agente e pelo Secure Web Proxy. Para chamadas de saída, quando a instrumentação do OpenTelemetry está ativada, os registros SanitizeOperation do Model Armor contêm os campos trace e spanId diretamente. É possível filtrar registros e visualizar intervalos de rastreamento diretamente no Cloud Trace ou no Agent Registry.

Resumo dos mecanismos de correlação

Flow	Caminho e roteamento	Rastreamento no registro do Model Armor	Método de correlação
Do cliente para o agente (entrada)	Chamada de API direta do Gemini Enterprise para o Model Armor	Os campos `trace` e `spanId` não são preenchidos.	Junção de registros usando o token de sessão de `client_correlation_id` e `assistToken`
Do agente para qualquer lugar (saída)	Encaminhado pelo Gateway de Agente e pelo Secure Web Proxy	Os campos `trace` e `spanId` são preenchidos.	Correspondência direta no ID `trace` e inspeção do intervalo de rastreamento

Antes de começar

Antes de começar a correlacionar os registros do Model Armor com os registros do Gemini Enterprise, siga estas etapas:

Ative o Model Armor no Gemini Enterprise.
Para gerar o contexto de rastreamento e visualizar os detalhes do rastreamento nos registros do Gemini Enterprise e do Model Armor, ative a opção Ativar a instrumentação de rastreamentos e registros do OpenTelemetry e, opcionalmente, Ativar a geração de registros de entradas de comandos e saídas de respostas nas configurações de observabilidade. Para instruções, consulte Ativar as configurações de observabilidade.
Para a triagem de tráfego de saída, configure o Model Armor no Gateway de Agente.

Funções exigidas

Para receber as permissões necessárias para visualizar e correlacionar registros e intervalos de rastreamento, peça para o administrador conceder a você os seguintes papéis do IAM no projeto:

Usuário do Cloud Trace (roles/cloudtrace.user)
Visualizador de registros (roles/logging.viewer)

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias com papéis personalizados ou outros papéis predefinidos.

Para informações sobre outros papéis que você pode precisar, consulte Controle de acesso do Trace e Controle de acesso do Cloud Logging.

Correlacionar registros do cliente para o agente (entrada)

Uma única interação StreamAssist produz três entradas de registro distintas no Cloud Logging:

Registro de sanitização do Model Armor (SanitizeOperation):
- Recurso monitorado:modelarmor.googleapis.com/SanitizeOperation
- Propriedades:contém o veredito detalhado de sanitização e as descobertas de segurança (como redação de PII, correspondências de filtro de IA responsável ou detecção de injeção de comandos), mas não contém o contexto de rastreamento ou a identidade do usuário final.
- Chave de correlação: labels."modelarmor.googleapis.com/client_correlation_id"
Registro do StreamAssist do Gemini Enterprise (consumed_api):
- Recurso monitorado:consumed_api
- Propriedades:contém a identidade do usuário final (userIamPrincipal), os detalhes do rastreamento (trace e spanId) e o token de sessão (response.assistToken).
- Chave de correlação:jsonPayload.response.assistToken
Registro de auditoria do ModelArmor do Gemini Enterprise (Agent):
- Recurso monitorado:discoveryengine.googleapis.com/Agent, em que jsonPayload.logMetadata.methodName é ModelArmorAudit.
- Propriedades:ecoa o veredito de sanitização de alto nível e contém o contexto de rastreamento (trace e spanId), mas não contém descobertas detalhadas ou IDs de correlação.
- Chave de correlação:trace

Chave de junção de correlação

Os registros de sanitização do Model Armor incluem um rótulo client_correlation_id que tem uma estrutura delimitada por barras verticais. O terceiro segmento desse rótulo é um token de sessão codificado em base64url que corresponde ao assistToken campo registrado no consumed_api registro para StreamAssist.

O rótulo client_correlation_id tem o seguinte formato:

AS|ASSISTANT_RESOURCE|SESSION_TOKEN

O ID de correlação inclui os seguintes valores:

ASSISTANT_RESOURCE: o nome completo do recurso Gemini Enterprise Assistant no seguinte formato:

projects/PROJECT/locations/LOCATION/collections/COLLECTION/engines/ENGINE/assistants/ASSISTANT

SESSION_TOKEN: o token de sessão exclusivo que corresponde ao assistToken no registro consumed_api depois que o preenchimento base64url é normalizado.

Lógica correspondente

Para correlacionar uma entrada de registro de sanitização do Model Armor com registros StreamAssist do Gemini Enterprise, implemente a seguinte lógica correspondente no pipeline de processamento de registros:

Extraia o token de sessão da entrada do Model Armor:
1. Localize o objeto labels na entrada do Model Armor.
2. Recupere o valor do rótulo modelarmor.googleapis.com/client_correlation_id.
3. Divida o valor desse rótulo usando o caractere de barra vertical (|).
4. Extraia o terceiro segmento, que representa o token de sessão codificado em base64url.
Extraia o valor assistToken das entradas StreamAssist: para cada entrada de registro StreamAssist consumed_api candidata, siga estas etapas:
1. Localize o objeto jsonPayload.
2. Extraia o valor do token do campo response.assistToken.
Normalize e compare os tokens: para comparar os tokens, normalize as duas strings de token:
1. Substitua todos os hifens (-) por sinais de adição (+).
2. Substitua todos os sublinhados (_) por barras (/).
3. Remova todos os sinais de igual (=) à direita.
4. Se os tokens normalizados corresponderem, correlacione as entradas de registro.
Extraia os dados correlacionados: se você encontrar uma correspondência, extraia estes campos das entradas correspondentes:
- Identidade do IAM do usuário: o campo userIamPrincipal de a entrada StreamAssist
- ID do rastreamento: o campo trace da entrada StreamAssist
- ID do período: o campo spanId da entrada StreamAssist
- Veredito de sanitização: o campo sanitizationVerdict em jsonPayload.sanitizationResult na entrada do Model Armor

Exemplo de correlação do Python

O script Python a seguir demonstra como consultar o Cloud Logging para registros do Model Armor e do Gemini Enterprise, realizar a normalização e a correspondência de tokens e gerar os registros correlacionados:

#!/usr/bin/env python3
from datetime import datetime, timedelta, timezone
from google.cloud import logging

# Google Cloud project ID
PROJECT_ID = "YOUR_PROJECT_ID"


def correlate_logs(ma_entry, de_consumed_entries):
  """Correlates a Model Armor log entry with StreamAssist logs."""
  # 1. Extract client_correlation_id from Model Armor log labels
  labels = ma_entry.get("labels", {})
  client_corr_id = labels.get(
      "modelarmor.googleapis.com/client_correlation_id", ""
  )
  if not client_corr_id:
    return None

  # 2. Extract session token (3rd pipe-delimited segment)
  parts = client_corr_id.split("|")
  if len(parts) < 3:
    return None
  ma_token = parts[2]

  # 3. Normalize base64url padding for comparison
  ma_token_normalized = ma_token.replace("-", "+").replace("_", "/").rstrip("=")

  # 4. Search for matching assistToken in StreamAssist logs
  for de in de_consumed_entries:
    payload = de.get("jsonPayload", {})
    de_token = payload.get("response", {}).get("assistToken", "")
    de_token_normalized = (
        de_token.replace("-", "+").replace("_", "/").rstrip("=")
    )

    if ma_token_normalized == de_token_normalized:
      return {
          "user": payload.get("userIamPrincipal"),
          "trace": de.get("trace"),
          "span_id": de.get("spanId"),
          "verdict": (
              ma_entry.get("jsonPayload", {})
              .get("sanitizationResult", {})
              .get("sanitizationVerdict")
          ),
      }
  return None


def main():
  # Initialize Google Cloud Logging Client
  print(f"Connecting to Google Cloud Logging (Project: {PROJECT_ID})...")
  client = logging.Client(project=PROJECT_ID)

  # Calculate ISO timestamp for 1 hour ago
  one_hour_ago = (
      datetime.now(timezone.utc) - timedelta(hours=1)
  ).strftime("%Y-%m-%dT%H:%M:%SZ")
  print(f"Filtering logs starting from: {one_hour_ago}")

  # Build log query filters
  ma_filter = f"""
    resource.type="modelarmor.googleapis.com/SanitizeOperation"
    AND timestamp >= "{one_hour_ago}"
    """

  de_filter = f"""
    resource.type="consumed_api"
    AND jsonPayload.response.assistToken:*
    AND timestamp >= "{one_hour_ago}"
    """

  # Fetch Model Armor log entries
  print("Fetching Model Armor log entries...")
  ma_entries = [
      entry.to_api_repr()
      for entry in client.list_entries(filter_=ma_filter, max_results=100)
  ]
  print(f"Found {len(ma_entries)} Model Armor entries.")

  # Fetch Gemini Enterprise log entries
  print("Fetching Gemini Enterprise StreamAssist log entries...")
  de_entries = [
      entry.to_api_repr()
      for entry in client.list_entries(filter_=de_filter, max_results=500)
  ]
  print(f"Found {len(de_entries)} Gemini Enterprise entries.")

  # Perform Correlation
  print("\n================ Correlating Logs ================")
  correlated_results = []
  for ma in ma_entries:
    match = correlate_logs(ma, de_entries)
    if match:
      correlated_results.append(match)
      print(f"  User IAM Principal  : {match['user']}")
      print(f"  Sanitization Verdict: {match['verdict']}")
      print(f"  Trace ID            : {match['trace']}")
      print(f"  Span ID             : {match['span_id']}")
      print("-" * 50)

  print(f"\nDone. Total Correlated Records: {len(correlated_results)}")


if __name__ == "__main__":
  main()

Correlacionar registros e intervalos de rastreamento do agente para qualquer lugar (saída)

Quando um agente executa chamadas de ferramentas (como interagir com um servidor MCP ou APIs externas) protegidas pelo Gateway de Agente e pelo Model Armor, a solicitação faz parte do tráfego do agente para qualquer lugar.

Quando a instrumentação do OpenTelemetry está ativada no app, as entradas de registro SanitizeOperation resultantes incluem automaticamente os campos trace e spanId.

Filtrar registros de saída no Cloud Logging

Para encontrar todos os registros de sanitização do Model Armor associados a um rastreamento específico no Cloud Logging, use o seguinte filtro de consulta:

resource.type="modelarmor.googleapis.com/SanitizeOperation"
trace="TRACE_ID"

Substitua TRACE_ID pelo ID do rastreamento da interação do agente.

Para mais informações, consulte Visualizar e analisar entradas de registro.

Visualizar intervalos de rastreamento

No Trace ou no Agent Registry, é possível visualizar o gráfico de execução e as linhas do tempo da interação do agente. O Model Armor gera os seguintes intervalos:

Intervalo pai: apply_guardrail "Google Cloud Model Armor"
Intervalos filhos: Request Path e Response Path

Cada período inclui atributos como ID da política, decisões de segurança e violações de filtro correspondentes. Para mais informações, consulte Visualizar intervalos de rastreamento do Model Armor spans.

Correlacionar registros do Model Armor com registros do Gemini Enterprise Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.