Remarque : Cet ensemble de documentation concerne les éditions Standard, Plus et Frontline de Gemini Enterprise. Pour la documentation de l'édition Business, consultez le Centre d'aide Gemini Enterprise – Édition Business.

Google utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

Corréler les journaux Model Armor avec les journaux Gemini Enterprise

Ce document explique comment corréler les journaux de nettoyage Model Armor avec les journaux et les étendues de trace de la plate-forme Gemini Enterprise dans Cloud Logging. Il décrit les mécanismes de corrélation pour les flux de trafic client vers agent (entrée) et agent vers n'importe quelle destination (sortie), présente les prérequis pour la génération de traces et fournit des instructions détaillées ainsi que des exemples de code pour joindre ces entrées de journal dans votre pipeline de traitement des journaux.

Lorsque vous examinez une étendue de trace ou une entrée de journal Model Armor, vous devrez peut-être localiser les enregistrements correspondants dans Cloud Logging pour obtenir le contexte complet de la requête. Exemple :

Si vous commencez par un segment de trace, vous devrez peut-être déterminer l'identité de l'utilisateur final ou inspecter les résultats détaillés du nettoyage.
Si vous commencez par une entrée de journal de nettoyage Model Armor, vous devrez peut-être la corréler avec l'identité de l'utilisateur ou les informations de trace.

Fonctionnement de la corrélation des journaux

Model Armor peut filtrer les prompts et les réponses aux points de communication suivants dans Gemini Enterprise :

Trafic client vers agent (entrée) : lorsqu'un utilisateur envoie un prompt à l'assistant Gemini Enterprise, Gemini Enterprise appelle directement les API Model Armor. Les journaux de plate-forme Model Armor résultants (SanitizeOperation) ne contiennent pas directement les champs OpenTelemetry trace ou spanId. Pour corréler ces journaux avec les identités des utilisateurs et les étendues de trace, vous effectuez une jointure de journaux dans votre pipeline de gestion des informations et des événements de sécurité (SIEM) ou de traitement des journaux à l'aide du jeton de session.
Trafic agent vers n'importe quelle destination (sortie) : lorsqu'un agent appelle un outil externe, un serveur MCP (Model Context Protocol) ou un grand modèle de langage (LLM) externe, le trafic est acheminé via Agent Gateway et Secure Web Proxy. Pour les appels sortants, lorsque l'instrumentation OpenTelemetry est activée, les journaux SanitizeOperation de Model Armor contiennent directement les champs trace et spanId. Vous pouvez filtrer directement les journaux et afficher les étendues de trace dans Cloud Trace ou Agent Registry.

Résumé des mécanismes de corrélation

Flow	Chemin d'accès et routage	Trace dans le journal Model Armor	Méthode de corrélation
Client vers agent (entrée)	Appel d'API direct de Gemini Enterprise vers Model Armor	Les champs `trace` et `spanId` ne sont pas renseignés.	Jointure de journaux à l'aide du jeton de session de `client_correlation_id` et `assistToken`
Agent vers n'importe quelle destination (sortie)	Acheminement via Agent Gateway et Secure Web Proxy	Les champs `trace` et `spanId` sont renseignés.	Correspondance directe sur l'ID `trace` et inspection de l'étendue de trace

Avant de commencer

Avant de commencer à corréler les journaux Model Armor avec les journaux Gemini Enterprise, procédez comme suit :

Activez Model Armor dans Gemini Enterprise.
Pour générer un contexte de trace et afficher les détails de la trace dans les journaux Gemini Enterprise et Model Armor, activez Activer l'instrumentation des traces et des journaux OpenTelemetry et, éventuellement, Activer la journalisation des entrées de prompt et des sorties de réponse dans vos paramètres d'observabilité. Pour obtenir des instructions, consultez Activer les paramètres d'observabilité.
Pour le filtrage du trafic sortant, configurez Model Armor sur votre Agent Gateway.

Rôles requis

Pour obtenir les autorisations nécessaires pour afficher et corréler les journaux et les étendues de trace, demandez à votre administrateur de vous accorder les rôles IAM suivants sur votre projet :

Utilisateur Cloud Trace (roles/cloudtrace.user)
Lecteur de journaux (roles/logging.viewer)

Pour en savoir plus sur l'attribution de rôles, consultez la page Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises avec des rôles personnalisés ou d'autres rôles prédéfinis.

Pour en savoir plus sur les autres rôles dont vous pourriez avoir besoin, consultez Contrôle des accès aux traces et Contrôle des accès à Cloud Logging.

Corréler les journaux client vers agent (entrée)

Une seule interaction StreamAssist produit trois entrées de journal distinctes dans Cloud Logging :

Journal de nettoyage Model Armor (SanitizeOperation):
- Ressource surveillée : modelarmor.googleapis.com/SanitizeOperation
- Propriétés : contient le verdict de nettoyage détaillé et les résultats de sécurité (tels que la suppression des informations permettant d'identifier personnellement l'utilisateur, les correspondances de filtres d'IA responsable ou la détection d'injection de prompt), mais ne contient pas le contexte de trace ni l'identité de l'utilisateur final.
- Clé de corrélation labels."modelarmor.googleapis.com/client_correlation_id"
Journal StreamAssist Gemini Enterprise (consumed_api)
- Ressource surveillée : consumed_api
- Propriétés : contient l'identité de l'utilisateur final (userIamPrincipal), les détails de la trace (trace et spanId) et le jeton de session (response.assistToken).
- Clé de corrélation : jsonPayload.response.assistToken
Journal ModelArmorAudit Gemini Enterprise (Agent):
- Ressource surveillée : discoveryengine.googleapis.com/Agent où jsonPayload.logMetadata.methodName est ModelArmorAudit.
- Propriétés : reflète le verdict de nettoyage de haut niveau et contient le contexte de trace (trace et spanId), mais ne contient pas de résultats détaillés ni d'ID de corrélation.
- Clé de corrélation : trace

Clé de jointure de corrélation

Les journaux de nettoyage Model Armor incluent un libellé client_correlation_id dont la structure est délimitée par une barre verticale. Le troisième segment de ce libellé est un jeton de session encodé en base64url qui correspond au assistToken champ enregistré dans le journal consumed_api pour StreamAssist.

Le libellé client_correlation_id a le format suivant :

AS|ASSISTANT_RESOURCE|SESSION_TOKEN

L'ID de corrélation inclut les valeurs suivantes :

ASSISTANT_RESOURCE : nom de ressource complet de la ressource Assistant Gemini Enterprise au format suivant :
```
projects/PROJECT/locations/LOCATION/collections/COLLECTION/engines/ENGINE/assistants/ASSISTANT
```
SESSION_TOKEN: jeton de session unique qui correspond à assistToken dans le journal consumed_api une fois le remplissage base64url normalisé.

Logique de correspondance

Pour corréler une entrée de journal de nettoyage Model Armor avec les journaux StreamAssist Gemini Enterprise, implémentez la logique de correspondance suivante dans votre pipeline de traitement des journaux :

Extrayez le jeton de session de l'entrée Model Armor :
1. Recherchez l'objet labels dans l'entrée Model Armor.
2. Récupérez la valeur du libellé modelarmor.googleapis.com/client_correlation_id.
3. Divisez la valeur de ce libellé à l'aide de la barre verticale (|).
4. Extrayez le troisième segment, qui représente le jeton de session encodé en base64url.
Extrayez la valeur assistToken des entrées StreamAssist : pour chaque entrée de journal StreamAssist consumed_api candidate, procédez comme suit :
1. Recherchez l'objet jsonPayload.
2. Extrayez la valeur du jeton du champ response.assistToken.
Normalisez et comparez les jetons : pour comparer les jetons, normalisez les deux chaînes de jetons :
1. Remplacez tous les traits d'union (-) par des signes plus (+).
2. Remplacez tous les traits de soulignement (_) par des barres obliques (/).
3. Supprimez tous les signes égal (=) à la fin.
4. Si les jetons normalisés correspondent, corrélez les entrées de journal.
Extrayez les données corrélées : si vous trouvez une correspondance, extrayez les champs suivants des entrées correspondantes :
- Identité IAM de l'utilisateur : champ userIamPrincipal de l'entrée StreamAssist
- ID de trace : champ trace de l'entrée StreamAssist
- ID de segment : champ spanId de l'entrée StreamAssist
- Verdict de nettoyage : champ sanitizationVerdict sous jsonPayload.sanitizationResult dans l'entrée Model Armor

Exemple de corrélation Python

Le script Python suivant montre comment interroger Cloud Logging pour les journaux Model Armor et Gemini Enterprise, effectuer la normalisation et la correspondance des jetons, et générer les enregistrements corrélés :

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

Corréler les journaux et les étendues de trace agent vers n'importe quelle destination (sortie)

Lorsqu'un agent exécute des appels d'outils (par exemple, lorsqu'il interagit avec un serveur MCP ou des API externes) protégés par Agent Gateway et Model Armor, la requête fait partie du trafic agent vers n'importe quelle destination.

Lorsque l'instrumentation OpenTelemetry est activée sur l'application, les entrées de journal SanitizeOperation résultantes incluent automatiquement les champs trace et spanId.

Filtrer les journaux de sortie dans Cloud Logging

Pour trouver tous les journaux de nettoyage Model Armor associés à une trace spécifique dans Cloud Logging, utilisez le filtre de requête suivant :

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

Remplacez TRACE_ID par l'ID de trace de l'interaction de l'agent.

Pour en savoir plus, consultez Afficher et analyser les entrées de journal.

Afficher les étendues de trace

Dans Trace ou Agent Registry, vous pouvez afficher le graphique d'exécution et les chronologies de l'interaction de l'agent. Model Armor génère les étendues suivantes :

Segment parent : apply_guardrail "Google Cloud Model Armor"
Étendues enfants : Request Path et Response Path

Chaque étendue inclut des attributs tels que l'ID de la stratégie, les décisions de sécurité et les violations de filtre correspondantes. Pour en savoir plus, consultez Afficher les étendues de trace Model Armor spans.

Corréler les journaux Model Armor avec les journaux Gemini Enterprise Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.