Nota: Este conjunto de documentación es para las ediciones Standard, Plus, de pago por uso y Frontline de Gemini Enterprise. Para obtener la documentación de la edición Business, consulta el Centro de ayuda de Gemini Enterprise Business.

Google utiliza tecnología de IA para traducir contenido a tu idioma preferido. Las traducciones realizadas con IA pueden contener errores.

Correlaciona los registros de Model Armor con los registros de Gemini Enterprise

En este documento, se describe cómo correlacionar los registros de limpieza de Model Armor con los registros de la plataforma de Gemini Enterprise y los intervalos de seguimiento en Cloud Logging. Se explican los mecanismos de correlación para los flujos de tráfico de cliente a agente (entrada) y de agente a cualquier lugar (salida), se describen los requisitos previos para la generación de seguimientos y se proporcionan instrucciones paso a paso y muestras de código para unir estas entradas de registro en tu canalización de procesamiento de registros.

Cuando investigues un intervalo de seguimiento o una entrada de registro de Model Armor, es posible que debas ubicar los registros correspondientes en Cloud Logging para obtener el contexto completo de la solicitud. Por ejemplo:

Si comienzas con un intervalo de seguimiento, es posible que debas determinar la identidad del usuario final o inspeccionar los resultados detallados de la limpieza.
Si comienzas con una entrada de registro de limpieza de Model Armor, es posible que debas correlacionarla con la identidad del usuario o la información de seguimiento.

Cómo funciona la correlación de registros

Model Armor puede examinar las instrucciones y las respuestas en los siguientes puntos de comunicación en Gemini Enterprise:

Tráfico de cliente a agente (entrada): Cuando un usuario envía una instrucción al asistente de Gemini Enterprise, Gemini Enterprise llama directamente a las APIs de Model Armor. Los registros de la plataforma de Model Armor resultantes (SanitizeOperation) no contienen directamente los campos trace ni spanId de OpenTelemetry. Para correlacionar estos registros con las identidades de los usuarios y los intervalos de seguimiento, debes realizar una unión de registros en tu canalización de administración de información y eventos de seguridad (SIEM) o de procesamiento de registros mediante el token de sesión.
Tráfico de agente a cualquier lugar (salida): Cuando un agente llama a una herramienta externa, a un servidor del Protocolo de contexto del modelo (MCP) o a un modelo de lenguaje grande (LLM) externo, el tráfico se enruta a través de Agent Gateway y Secure Web Proxy. Para las llamadas de salida, cuando la instrumentación de OpenTelemetry está habilitada, los registros SanitizeOperation de Model Armor contienen los campos trace y spanId directamente. Puedes filtrar registros directamente y ver intervalos de seguimiento en Cloud Trace o Agent Registry.

Resumen de los mecanismos de correlación

Flujo	Ruta de acceso y enrutamiento	Seguimiento en el registro de Model Armor	Método de correlación
De cliente a agente (entrada)	Llamada directa a la API de Gemini Enterprise a Model Armor	`trace` y `spanId` no se propagan.	Unión de registros con el token de sesión de `client_correlation_id` y `assistToken`
Del agente a cualquier lugar (salida)	Enrutado a través de Agent Gateway y Secure Web Proxy	`trace` y `spanId` se propagan.	Coincidencia directa en el ID de `trace` y la inspección del intervalo de seguimiento

Antes de comenzar

Antes de comenzar a correlacionar los registros de Model Armor con los registros de Gemini Enterprise, sigue estos pasos:

Habilita Model Armor en Gemini Enterprise.
Para generar el contexto de seguimiento y ver los detalles del seguimiento en los registros de Gemini Enterprise y Model Armor, activa Habilitar la instrumentación de seguimientos y registros de OpenTelemetry y, de manera opcional, Habilitar el registro de las entradas de instrucciones y las salidas de respuestas en la configuración de observabilidad. Para obtener instrucciones, consulta Activa la configuración de observabilidad settings
Para el examen de tráfico de salida, configura Model Armor en tu Agent Gateway.

Roles obligatorios

Para obtener los permisos que necesitas para ver y correlacionar registros e intervalos de seguimiento, pídele a tu administrador que te otorgue los siguientes roles de IAM en tu proyecto:

Usuario de Cloud Trace (roles/cloudtrace.user)
Visor de registros (roles/logging.viewer)

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios mediante roles personalizados o cualquier otro rol predefinido.

Para obtener información sobre otros roles que podrías necesitar, consulta Control de acceso de Trace y Control de acceso de Cloud Logging.

Correlaciona registros de cliente a agente (entrada)

Una sola interacción StreamAssist produce tres entradas de registro distintas en Cloud Logging:

Registro de limpieza de Model Armor (SanitizeOperation):
- Recurso supervisado: modelarmor.googleapis.com/SanitizeOperation
- Propiedades: Contiene el veredicto detallado de la limpieza y los resultados de seguridad (como la redacción de PII, las coincidencias de filtros de IA responsable o la detección de inyección de instrucciones), pero no contiene el contexto de seguimiento ni la identidad del usuario final.
- Clave de correlación: labels."modelarmor.googleapis.com/client_correlation_id"
Registro de StreamAssist de Gemini Enterprise (consumed_api):
- Recurso supervisado: consumed_api
- Propiedades: Contiene la identidad del usuario final (userIamPrincipal), los detalles del seguimiento (trace y spanId) y el token de sesión (response.assistToken).
- Clave de correlación: jsonPayload.response.assistToken
Registro de ModelArmorAudit de Gemini Enterprise (Agent):
- Recurso supervisado: discoveryengine.googleapis.com/Agent, en el que jsonPayload.logMetadata.methodName es ModelArmorAudit.
- Propiedades: Refleja el veredicto de limpieza de alto nivel y contiene el contexto de seguimiento (trace y spanId), pero no contiene resultados detallados ni IDs de correlación.
- Clave de correlación: trace

Clave de unión de correlación

Los registros de limpieza de Model Armor incluyen una etiqueta client_correlation_id que tiene una estructura delimitada por barras verticales. El tercer segmento de esta etiqueta es un token de sesión codificado en base64url que coincide con el assistToken campo registrado en el consumed_api registro para StreamAssist.

La etiqueta client_correlation_id tiene el siguiente formato:

AS|ASSISTANT_RESOURCE|SESSION_TOKEN

El ID de correlación incluye los siguientes valores:

ASSISTANT_RESOURCE: Es el nombre completo del recurso Gemini Enterprise Assistant en el siguiente formato:
```
projects/PROJECT/locations/LOCATION/collections/COLLECTION/engines/ENGINE/assistants/ASSISTANT
```
SESSION_TOKEN: Es el token de sesión único que coincide con assistToken en el registro consumed_api después de que se normaliza el relleno de base64url.

Lógica de coincidencia

Para correlacionar una entrada de registro de limpieza de Model Armor con los registros StreamAssist de Gemini Enterprise, implementa la siguiente lógica de coincidencia en tu canalización de procesamiento de registros:

Extrae el token de sesión de la entrada de Model Armor:
1. Ubica el objeto labels en la entrada de Model Armor.
2. Recupera el valor de la etiqueta modelarmor.googleapis.com/client_correlation_id.
3. Divide el valor de esta etiqueta con el carácter de barra vertical (|).
4. Extrae el tercer segmento, que representa el token de sesión codificado en base64url.
Extrae el valor de assistToken de las entradas StreamAssist: Para cada entrada de registro StreamAssist consumed_api candidata, sigue estos pasos:
1. Ubica el objeto jsonPayload.
2. Extrae el valor del token del campo response.assistToken.
Normaliza y compara los tokens: Para comparar los tokens, normaliza ambas cadenas de tokens:
1. Reemplaza todos los guiones (-) por signos más (+).
2. Reemplaza todos los guiones bajos (_) por barras diagonales (/).
3. Quita todos los signos igual (=) finales.
4. Si los tokens normalizados coinciden, correlaciona las entradas de registro.
Extrae los datos correlacionados: Si encuentras una coincidencia, extrae estos campos de las entradas coincidentes:
- Identidad de IAM del usuario: el campo userIamPrincipal de la entrada StreamAssist
- ID de seguimiento: el campo trace de la entrada StreamAssist
- ID de intervalo: el campo spanId de la entrada StreamAssist
- Veredicto de limpieza: el campo sanitizationVerdict en jsonPayload.sanitizationResult en la entrada de Model Armor

Ejemplo de correlación de Python

En la siguiente secuencia de comandos de Python, se muestra cómo consultar Cloud Logging para obtener registros de Model Armor y Gemini Enterprise, realizar la normalización y la coincidencia de tokens, y generar los 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()

Correlaciona registros e intervalos de seguimiento de agente a cualquier lugar (salida)

Cuando un agente ejecuta llamadas a herramientas (como interactuar con un servidor de MCP o APIs externas) protegidas por Agent Gateway y Model Armor, la solicitud forma parte del tráfico de agente a cualquier lugar.

Cuando la instrumentación de OpenTelemetry está habilitada en la app, las entradas de registro SanitizeOperation resultantes incluyen automáticamente los campos trace y spanId.

Filtra los registros de salida en Cloud Logging

Para encontrar todos los registros de limpieza de Model Armor asociados con un seguimiento específico en Cloud Logging, usa el siguiente filtro de consulta:

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

Reemplaza TRACE_ID por el ID de seguimiento de la interacción del agente.

Para obtener más información, consulta Visualiza y analiza entradas de registro.

Visualiza intervalos de seguimiento

En Trace o en Agent Registry, puedes ver el gráfico de ejecución y las líneas de tiempo de la interacción del agente. Model Armor genera los siguientes intervalos:

Intervalo superior: apply_guardrail "Google Cloud Model Armor"
Intervalos secundarios: Request Path y Response Path

Cada intervalo incluye atributos como el ID de la política, las decisiones de seguridad y las violaciones de filtros coincidentes. Para obtener más información, consulta Visualiza intervalos de seguimiento de Model Armor spans.

Correlaciona los registros de Model Armor con los registros de Gemini Enterprise Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.