Correlare i log di Model Armor con i log di Gemini Enterprise

Questo documento descrive come correlare i log di sanitizzazione di Model Armor con i log della piattaforma Gemini Enterprise e gli intervalli di traccia in Cloud Logging. Spiega i meccanismi di correlazione per i flussi di traffico da client ad agente (in entrata) e da agente a ovunque (in uscita), descrive i prerequisiti per la generazione delle tracce e fornisce istruzioni passo passo ed esempi di codice per unire queste voci di log nella pipeline di elaborazione dei log.

Quando esamini un intervallo di traccia o una voce di log di Model Armor, potresti dover individuare i record corrispondenti in Cloud Logging per ottenere il contesto completo della richiesta. Ad esempio:

  • Se inizi da un intervallo di traccia, potresti dover determinare l'identità dell'utente finale o esaminare i risultati dettagliati della sanitizzazione.
  • Se inizi da una voce di log di sanitizzazione di Model Armor, potresti doverla correlare con l'identità dell'utente o le informazioni di traccia.

Come funziona la correlazione dei log

Model Armor può filtrare prompt e risposte nei seguenti punti di comunicazione in Gemini Enterprise:

  • Traffico da client ad agente (in entrata): quando un utente invia un prompt all' assistente Gemini Enterprise, Gemini Enterprise chiama direttamente le API Model Armor. I log della piattaforma Model Armor risultanti (SanitizeOperation) non contengono direttamente i campi trace o spanId di OpenTelemetry. Per correlare questi log con le identità utente e gli intervalli di traccia, esegui un join dei log nella pipeline di gestione degli eventi e delle informazioni di sicurezza (SIEM) o di elaborazione dei log utilizzando il token di sessione.

  • Traffico da agente a ovunque (in uscita): quando un agente chiama uno strumento esterno, un server Model Context Protocol (MCP) o un modello linguistico di grandi dimensioni (LLM) esterno, il traffico viene instradato tramite Agent Gateway e Secure Web Proxy. Per le chiamate in uscita, quando l'instrumentazione OpenTelemetry è abilitata, i log SanitizeOperation di Model Armor contengono direttamente i campi trace e spanId. Puoi filtrare direttamente i log e visualizzare gli intervalli di traccia in Cloud Trace o Agent Registry.

Riepilogo dei meccanismi di correlazione

Flow Percorso e routing Trace nel log di Model Armor Metodo di correlazione
Da client ad agente (in entrata) Chiamata API diretta da Gemini Enterprise a Model Armor I campi trace e spanId non vengono compilati. Join dei log utilizzando il token di sessione da client_correlation_id e assistToken
Da agente a ovunque (in uscita) Instradato tramite Agent Gateway e Secure Web Proxy I campi trace e spanId vengono compilati. Corrispondenza diretta sull'ID trace e ispezione dell'intervallo di Trace

Prima di iniziare

Prima di iniziare a correlare i log di Model Armor con i log di Gemini Enterprise, segui questi passaggi:

  1. Abilita Model Armor in Gemini Enterprise.
  2. Per generare il contesto di traccia e visualizzare i dettagli della traccia nei log di Gemini Enterprise e Model Armor, attiva Abilita l'instrumentazione di tracce e log OpenTelemetry e, facoltativamente, Abilita il logging degli input dei prompt e degli output delle risposte nelle impostazioni di osservabilità. Per istruzioni, vedi Attivare le impostazioni di osservabilità settings
  3. Per il filtraggio del traffico in uscita, configura Model Armor su Agent Gateway.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per visualizzare e correlare i log e gli intervalli di traccia, chiedi all'amministratore di concederti i seguenti ruoli IAM sul progetto:

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Per informazioni su altri ruoli di cui potresti aver bisogno, consulta Controllo dell'accesso alle tracce e Controllo dell'accesso a Cloud Logging.

Correlare i log da client ad agente (in entrata)

Una singola interazione StreamAssist produce tre voci di log distinte in Cloud Logging:

  • Log di sanitizzazione di Model Armor (SanitizeOperation):
    • Risorsa monitorata: modelarmor.googleapis.com/SanitizeOperation
    • Proprietà: contiene il verdetto dettagliato di sanitizzazione e i risultati di sicurezza (ad esempio, la redazione delle PII, le corrispondenze dei filtri di AI responsabile o il rilevamento di prompt injection), ma non contiene il contesto di traccia o l'identità dell'utente finale.
    • Chiave di correlazione: labels."modelarmor.googleapis.com/client_correlation_id"
  • Log di StreamAssist di Gemini Enterprise (consumed_api):
    • Risorsa monitorata: consumed_api
    • Proprietà: contiene l'identità dell'utente finale (userIamPrincipal), i dettagli della traccia (trace e spanId) e il token di sessione (response.assistToken).
    • Chiave di correlazione: jsonPayload.response.assistToken
  • Log di audit ModelArmor di Gemini Enterprise (Agent):
    • Risorsa monitorata: discoveryengine.googleapis.com/Agent dove jsonPayload.logMetadata.methodName è ModelArmorAudit.
    • Proprietà: riproduce il verdetto di sanitizzazione di alto livello e contiene il contesto di traccia (trace e spanId), ma non contiene risultati dettagliati o ID di correlazione.
    • Chiave di correlazione: trace

Chiave di join di correlazione

I log di sanitizzazione di Model Armor includono un'etichetta client_correlation_id con una struttura delimitata da barre verticali. Il terzo segmento di questa etichetta è un token di sessione con codifica base64url che corrisponde al assistToken campo registrato nel log consumed_api per StreamAssist.

L'etichetta client_correlation_id ha il seguente formato:

AS|ASSISTANT_RESOURCE|SESSION_TOKEN

L'ID di correlazione include i seguenti valori:

  • ASSISTANT_RESOURCE: il nome completo della risorsa Gemini Enterprise Assistant nel seguente formato: 
    projects/PROJECT/locations/LOCATION/collections/COLLECTION/engines/ENGINE/assistants/ASSISTANT
  • SESSION_TOKEN: il token di sessione univoco che corrisponde a assistToken nel log consumed_api dopo la normalizzazione del padding base64url.

Logica di corrispondenza

Per correlare una voce di log di sanitizzazione di Model Armor con i log StreamAssist di Gemini Enterprise, implementa la seguente logica di corrispondenza nella pipeline di elaborazione dei log:

  1. Estrai il token di sessione dalla voce di Model Armor:

    1. Individua l'oggetto labels nella voce di Model Armor.
    2. Recupera il valore dell'etichetta modelarmor.googleapis.com/client_correlation_id.
    3. Dividi il valore di questa etichetta utilizzando il carattere barra verticale (|).
    4. Estrai il terzo segmento, che rappresenta il token di sessione con codifica base64url.

  2. Estrai il valore assistToken dalle voci StreamAssist: per ogni voce di log StreamAssist consumed_api candidata, segui questi passaggi:

    1. Individua l'oggetto jsonPayload.
    2. Estrai il valore del token dal campo response.assistToken.

  3. Normalizza e confronta i token: per confrontare i token, normalizza entrambe le stringhe di token:

    1. Sostituisci tutti i trattini (-) con segni più (+).
    2. Sostituisci tutti i trattini bassi (_) con barre (/).
    3. Rimuovi eventuali segni di uguale (=) finali.
    4. Se i token normalizzati corrispondono, correla le voci di log.

  4. Estrai i dati correlati: se trovi una corrispondenza, estrai questi campi dalle voci corrispondenti:

    • Identità IAM utente: il campo userIamPrincipal da la voce StreamAssist
    • ID traccia: il campo trace della voce StreamAssist
    • ID intervallo: il campo spanId della voce StreamAssist
    • Verdetto di sanitizzazione: il campo sanitizationVerdict in jsonPayload.sanitizationResult nella voce di Model Armor

Esempio di correlazione Python

Il seguente script Python mostra come eseguire query su Cloud Logging per i log di Model Armor e Gemini Enterprise, eseguire la normalizzazione e la corrispondenza dei token e restituire i record correlati:

#!/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()

Correlare i log e gli intervalli di traccia da agente a ovunque (in uscita)

Quando un agente esegue chiamate di strumenti (ad esempio interagendo con un server MCP o API esterne) protette da Agent Gateway e Model Armor, la richiesta fa parte del traffico da agente a ovunque.

Quando l'instrumentazione OpenTelemetry è abilitata nell'app, le voci di log SanitizeOperation risultanti includono automaticamente i campi trace e spanId.

Filtrare i log in uscita in Cloud Logging

Per trovare tutti i log di sanitizzazione di Model Armor associati a una traccia specifica in Cloud Logging, utilizza il seguente filtro di query:

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

Sostituisci TRACE_ID con l'ID traccia dell'interazione dell'agente.

Per saperne di più, consulta Visualizzare e analizzare le voci di log.

Visualizzare gli intervalli di traccia

In Trace o Agent Registry, puoi visualizzare il grafico di esecuzione e le sequenze temporali dell'interazione dell'agente. Model Armor genera i seguenti intervalli:

  • Intervallo principale: apply_guardrail "Google Cloud Model Armor"
  • Intervalli secondari: Request Path e Response Path

Ogni intervallo include attributi come ID policy, decisioni di sicurezza e violazioni dei filtri corrispondenti. Per saperne di più, consulta Visualizzare gli intervalli di traccia di Model Armor spans.

Passaggi successivi