Menghubungkan log Model Armor dengan log Gemini Enterprise

Dokumen ini menjelaskan cara mengorelasikan log pembersihan Model Armor dengan log platform Gemini Enterprise dan rentang aktivitas dalam Cloud Logging. Dokumen ini menjelaskan mekanisme korelasi untuk alur traffic Client-to-Agent (ingress) dan Agent-to-Anywhere (egres), menguraikan prasyarat untuk pembuatan rekaman aktivitas, serta memberikan petunjuk langkah demi langkah dan contoh kode untuk menggabungkan entri log ini dalam pipeline pemrosesan log Anda.

Saat menyelidiki rentang rekaman aktivitas atau entri log Model Armor, Anda mungkin perlu menemukan catatan yang sesuai di Cloud Logging untuk mendapatkan konteks lengkap permintaan. Contoh:

  • Jika Anda memulai dari rentang rekaman aktivitas, Anda mungkin perlu menentukan identitas pengguna akhir atau memeriksa temuan sanitasi mendetail.
  • Jika Anda memulai dari entri log pembersihan Model Armor, Anda mungkin perlu mengorelasikannya dengan informasi identitas pengguna atau informasi pelacakan.

Cara kerja korelasi log

Model Armor dapat menyaring perintah dan respons di titik komunikasi berikut di Gemini Enterprise:

  • Traffic Client-to-Agent (ingress): Saat pengguna mengirimkan perintah ke asisten Gemini Enterprise, Gemini Enterprise akan langsung memanggil API Model Armor. Log platform Model Armor yang dihasilkan (SanitizeOperation) tidak secara langsung berisi kolom trace atau spanId OpenTelemetry. Untuk mengorelasikan log ini dengan identitas pengguna dan rentang aktivitas, Anda melakukan penggabungan log di pipeline pemrosesan log atau informasi keamanan dan pengelolaan peristiwa (SIEM) dengan menggunakan token sesi.

  • Traffic Agent-to-Anywhere (keluar): Saat agen memanggil alat eksternal, server Model Context Protocol (MCP), atau model bahasa besar (LLM) eksternal, traffic akan dirutekan melalui Agent Gateway dan Secure Web Proxy. Untuk panggilan keluar (egress), saat instrumentasi OpenTelemetry diaktifkan, log SanitizeOperation Model Armor berisi kolom trace dan spanId secara langsung. Anda dapat langsung memfilter log dan melihat rentang trace di Cloud Trace atau Agent Registry.

Ringkasan mekanisme korelasi

Flow Jalur dan perutean Rekaman aktivitas di log Model Armor Metode korelasi
Klien ke Agen (ingress) Panggilan API langsung dari Gemini Enterprise ke Model Armor trace dan spanId tidak diisi. Gabung log menggunakan token sesi dari client_correlation_id dan assistToken
Agent-to-Anywhere (egres) Dirutekan melalui Agent Gateway dan Secure Web Proxy trace dan spanId diisi. Pencocokan langsung pada ID trace dan pemeriksaan rentang Trace

Sebelum memulai

Sebelum Anda mulai mengorelasikan log Model Armor dengan log Gemini Enterprise, ikuti langkah-langkah berikut:

  1. Aktifkan Model Armor di Gemini Enterprise.
  2. Untuk membuat konteks rekaman aktivitas dan melihat detail rekaman aktivitas di log Gemini Enterprise dan Model Armor, aktifkan Aktifkan instrumentasi rekaman aktivitas dan log OpenTelemetry dan, secara opsional, Aktifkan logging input perintah dan output respons di setelan kemampuan pengamatan Anda. Untuk mengetahui petunjuknya, lihat Mengaktifkan setelan kemampuan observasi
  3. Untuk penyaringan traffic keluar, konfigurasi Model Armor di Agent Gateway Anda.

Peran yang diperlukan

Untuk mendapatkan izin yang diperlukan untuk melihat dan mengorelasikan log dan rentang aktivitas, minta administrator untuk memberi Anda peran IAM berikut di project Anda:

Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.

Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

Untuk mengetahui informasi tentang peran lain yang mungkin Anda perlukan, lihat Kontrol akses Trace dan Kontrol akses Cloud Logging.

Mengorelasikan log Client-to-Agent (ingress)

Satu interaksi StreamAssist menghasilkan tiga entri log berbeda di Cloud Logging:

  • Log pembersihan Model Armor (SanitizeOperation):
    • Resource yang dimonitor: modelarmor.googleapis.com/SanitizeOperation
    • Properti: Berisi putusan pembersihan dan temuan keamanan yang mendetail (seperti penyamaran PII, kecocokan filter AI yang bertanggung jawab, atau deteksi injeksi perintah), tetapi tidak berisi konteks pelacakan atau identitas pengguna akhir.
    • Kunci korelasi: labels."modelarmor.googleapis.com/client_correlation_id"
  • Log Gemini Enterprise StreamAssist (consumed_api):
    • Resource yang dimonitor: consumed_api
    • Properti: Berisi identitas pengguna akhir (userIamPrincipal), detail rekaman aktivitas (trace dan spanId), dan token sesi (response.assistToken).
    • Kunci korelasi: jsonPayload.response.assistToken
  • Log Audit ModelArmor Gemini Enterprise (Agent):
    • Resource yang Dimonitor: discoveryengine.googleapis.com/Agent dengan jsonPayload.logMetadata.methodName adalah ModelArmorAudit.
    • Properti: Menggambarkan hasil sanitasi tingkat tinggi dan berisi konteks rekaman aktivitas (trace dan spanId), tetapi tidak berisi temuan mendetail atau ID korelasi.
    • Kunci Korelasi: trace

Kunci gabungan korelasi

Log pembersihan Model Armor mencakup label client_correlation_id yang memiliki struktur yang dibatasi dengan karakter pipa. Segmen ketiga label ini adalah token sesi berenkode base64url yang cocok dengan kolom assistToken yang dicatat dalam log consumed_api untuk StreamAssist.

Label client_correlation_id memiliki format berikut:

AS|ASSISTANT_RESOURCE|SESSION_TOKEN

ID korelasi mencakup nilai berikut:

  • ASSISTANT_RESOURCE: nama lengkap resource Gemini Enterprise Assistant dalam format berikut: 
    projects/PROJECT/locations/LOCATION/collections/COLLECTION/engines/ENGINE/assistants/ASSISTANT
  • SESSION_TOKEN: token sesi unik yang cocok dengan assistToken dalam log consumed_api setelah padding base64url dinormalisasi.

Logika pencocokan

Untuk mengorelasikan entri log pembersihan Model Armor dengan log Gemini Enterprise StreamAssist, terapkan logika pencocokan berikut di pipeline pemrosesan log Anda:

  1. Ekstrak token sesi dari entri Model Armor:

    1. Temukan objek labels dalam entri Model Armor.
    2. Ambil nilai label modelarmor.googleapis.com/client_correlation_id.
    3. Pisahkan nilai label ini menggunakan karakter pipa (|).
    4. Ekstrak segmen ketiga, yang merepresentasikan token sesi berenkode base64url.

  2. Ekstrak nilai assistToken dari entri StreamAssist: Untuk setiap entri log StreamAssist consumed_api kandidat, ikuti langkah-langkah berikut:

    1. Temukan objek jsonPayload.
    2. Ekstrak nilai token dari kolom response.assistToken.

  3. Menormalisasi dan membandingkan token: Untuk membandingkan token, normalisasi kedua string token:

    1. Ganti semua tanda hubung (-) dengan tanda plus (+).
    2. Ganti semua garis bawah (_) dengan garis miring (/).
    3. Hapus semua tanda sama dengan di bagian akhir (=).
    4. Jika token yang dinormalisasi cocok, korelasikan entri log.

  4. Ekstrak data yang berkorelasi: Jika Anda menemukan kecocokan, ekstrak kolom ini dari entri yang cocok:

    • Identitas IAM pengguna: kolom userIamPrincipal dari entri StreamAssist
    • ID Trace: kolom trace dari entri StreamAssist
    • Span ID: kolom spanId dari entri StreamAssist
    • Keputusan sanitasi: kolom sanitizationVerdict di bagian jsonPayload.sanitizationResult dalam entri Model Armor

Contoh korelasi Python

Skrip Python berikut menunjukkan cara membuat kueri Cloud Logging untuk log Model Armor dan Gemini Enterprise, melakukan normalisasi dan pencocokan token, serta menampilkan output catatan yang dikorelasikan:

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

Mengorelasikan log Agent-to-Anywhere (keluar) dan rentang rekaman aktivitas

Saat agen menjalankan panggilan alat (seperti berinteraksi dengan server MCP atau API eksternal) yang dilindungi oleh Agent Gateway dan Model Armor, permintaan tersebut merupakan bagian dari traffic Agent-to-Anywhere.

Jika instrumentasi OpenTelemetry diaktifkan di aplikasi, entri log SanitizeOperation yang dihasilkan akan otomatis menyertakan kolom trace dan spanId.

Memfilter log keluar di Cloud Logging

Untuk menemukan semua log sanitasi Model Armor yang terkait dengan trace tertentu di Cloud Logging, gunakan filter kueri berikut:

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

Ganti TRACE_ID dengan ID rekaman aktivitas dari interaksi agen.

Untuk mengetahui informasi selengkapnya, lihat Melihat dan menganalisis entri log.

Melihat rentang rekaman aktivitas

Di Trace atau Agent Registry, Anda dapat melihat grafik eksekusi dan linimasa interaksi agen. Model Armor menghasilkan rentang berikut:

  • Rentang induk: apply_guardrail "Google Cloud Model Armor"
  • Rentang anak: Request Path dan Response Path

Setiap rentang mencakup atribut seperti ID kebijakan, keputusan keamanan, dan pelanggaran filter yang cocok. Untuk mengetahui informasi selengkapnya, lihat Melihat rentang rekaman aktivitas Model Armor.

Langkah berikutnya