Memantau traffic melalui Agent Gateway

Gunakan halaman ini untuk mempelajari cara melihat log, memantau permintaan, dan melacak trace terdistribusi untuk traffic yang dirutekan melalui deployment Agent Gateway Anda.

Cloud Logging

Log Agent Gateway dibuat menggunakan resource yang dimonitor networkservices.googleapis.com/Gateway.

Anda dapat menggunakan log ini untuk memantau permintaan akses ke gateway. Hal ini mencakup log yang dibuat saat Agent Gateway di-deploy dalam mode uji coba. Untuk mengkueri log pelanggaran uji coba di seluruh Unified Access Policies (UAP) Identity-Aware Proxy (IAP), kebijakan Tata Kelola Semantik, Model Armor, dan Kontrol Layanan VPC, serta membuat laporan gabungan "akan diblokir", lihat Mengaudit pelanggaran kebijakan uji coba di seluruh kontrol.

Melihat log untuk gateway tertentu

Untuk melihat log gateway tertentu, selesaikan langkah-langkah berikut.

Kueri konsol

  1. Di konsol Google Cloud , buka halaman Logs Explorer.

    Buka Logs Explorer

  2. Klik tombol Show query.

  3. Tempel perintah berikut ke dalam kolom kueri.

    resource.type="networkservices.googleapis.com/Gateway"
    resource.labels.location="REGION"
    resource.labels.gateway_name="AGENT_GATEWAY_NAME"
    

    Ganti kode berikut:

    • REGION: Region gateway Anda.
    • AGENT_GATEWAY_NAME: Nama gateway Anda.
  4. Klik Run query.

Nama log Agent Platform

Untuk mengkueri jenis entri log tertentu di Logs Explorer, Anda dapat memfilter kueri berdasarkan nama log menggunakan kolom logName. Tabel berikut menjelaskan nama log utama yang dihasilkan oleh Agent Gateway dan operasi sisi agen:

Nama log Deskripsi
projects/PROJECT_ID/logs/networkservices.googleapis.com%2Fgateway_requests Log untuk keputusan mengizinkan dan menolak gateway.
projects/PROJECT_ID/logs/cloudaudit.googleapis.com%2Fdata_access Cloud Audit Logs untuk keputusan AuthorizeUser IAP.
projects/PROJECT_ID/logs/aiplatform.googleapis.com%2Freasoning_engine_stderr Error saat sistem dimulai dan eksekusi di sisi agen (mesin penalaran stderr).
projects/PROJECT_ID/logs/aiplatform.googleapis.com%2Freasoning_engine_stdout Output standar sisi agen (mesin penalaran stdout).

Ganti PROJECT_ID dengan project ID Google Cloud Anda.

Jika Anda menggunakan Model Armor untuk sanitasi konten, log tersebut akan dikirim secara terpisah. Untuk mengetahui petunjuk cara membuat kueri log Model Armor, lihat Melihat log keamanan konten mentah di Logs Explorer.

Yang dicatat di log

Entri log Agent Gateway berisi informasi yang berguna untuk memantau dan men-debug traffic ke dan dari gateway Anda.

Kolom Format kolom Jenis kolom: Wajib atau Opsional Deskripsi
severity
insertID
timestamp
receiveTimestamp
trace
traceSampled
logName
LogEntry Wajib Kolom umum seperti yang dijelaskan dalam entri log.
httpRequest HttpRequest Wajib Protokol umum untuk me-log permintaan HTTP.
resource MonitoredResource Wajib

MonitoredResource adalah jenis resource yang terkait dengan entri log. Jenis resource untuk Gateway Agen adalah networkservices.googleapis.com/Gateway.

jsonPayload object (format Struct) Wajib

Payload entri log yang dinyatakan sebagai objek JSON. Objek JSON berisi kolom Agent Gateway berikut:

  • agentGatewayInfo: Menyertakan informasi tentang permintaan Gateway Agen.

    • mcpInfo: Menyertakan informasi tentang metode MCP permintaan (misalnya, "tools/list" atau "tools/call") dan parameter utama yang terkait dengan metode, jika ada. Misalnya, dalam kasus metode "tools/call", parameternya adalah nama alat.
    • agentRegistryResource: Nama resource Agent Registry dari server MCP, agen, atau endpoint yang cocok dengan permintaan.
  • Anda juga dapat memeriksa detail kolom serviceExtensionsInfo untuk mengetahui informasi tentang ekstensi otorisasi (IAP, Model Armor, atau lainnya) yang menangani permintaan tersebut.

Propagasi kebijakan dan latensi penyerapan log

Saat Anda memperbarui aturan akses gateway atau menyelidiki peristiwa keamanan, perhitungkan jendela propagasi dan penyerapan berikut:

  • Penyebaran Unified Access Policies (UAP): Pembaruan pada UAP yang diterapkan oleh Agent Gateway (seperti menambahkan aturan DENY atau mengalihkan iamEnforcementMode dari "DRY_RUN" ke "ENFORCE") pada akhirnya akan konsisten. Perubahan kebijakan langsung biasanya diterapkan dalam waktu 2 menit, tetapi dapat memerlukan waktu 7 menit atau lebih untuk diterapkan secara global (lihat Penerapan perubahan akses). Perubahan keanggotaan pada principalSet dapat memerlukan waktu beberapa menit hingga beberapa jam untuk disinkronkan.
  • Penghentian traffic darurat: Aturan UAP dievaluasi pada pemeriksaan otorisasi baru di Agent Gateway dan tidak menghentikan container agen atau menutup paksa koneksi streaming yang sudah ada. Untuk segera menghentikan agen yang disusupi atau berperilaku buruk selama insiden aktif, hapus runtime agen atau alihkan traffic revisinya selain menerapkan aturan penolakan gateway. Untuk mengetahui petunjuknya, lihat Penghentian darurat dan pencabutan akses.
  • Latensi log, trace, dan temuan: Agent Gateway mengevaluasi kebijakan IAP dan Model Armor secara sinkron pada jalur permintaan dan menulis entri log networkservices.googleapis.com/gateway_requests dan cloudaudit.googleapis.com/data_access (AuthorizeUser) dalam waktu hampir real-time (biasanya dapat ditelusuri di Logs Explorer dalam hitungan detik). Span trace terdistribusi yang diekspor ke Trace juga muncul dalam hitungan detik setelah penyelesaian span, sedangkan deteksi ancaman out-of-band dari Agent Anomaly Detection dievaluasi secara asinkron (lihat Telemetri dan latensi temuan keamanan).

Mempertahankan dan mengekspor log audit gateway ke SIEM

Untuk mempertahankan keputusan akses Gateway Agen sebagai bukti kepatuhan yang tahan modifikasi dan memusatkan pemantauan ancaman, Anda dapat mengunci bucket Logging dan mengalirkan log gateway ke platform Security Information and Event Management (SIEM):

  • Retensi yang terlihat jika diubah (bucket log terkunci): Rutekan log networkservices.googleapis.com/gateway_requests dan cloudaudit.googleapis.com/data_access ke bucket Logging kustom dengan periode retensi yang dikonfigurasi (--retention-days) dan kunci bucket secara permanen (gcloud logging buckets update BUCKET_ID --location=LOCATION --locked) untuk menerapkan penyimpanan kepatuhan write-once, read-many (WORM). Untuk mengetahui petunjuk langkah demi langkah, lihat Retensi yang tidak dapat diubah untuk log audit.
  • Ekspor SIEM: Buat sink Logging (atau sink gabungan tingkat organisasi) dengan filter penyertaan untuk logName:("networkservices.googleapis.com%2Fgateway_requests" OR "cloudaudit.googleapis.com%2Fdata_access") guna terus mengekspor keputusan izinkan dan tolak gateway ke Google Security Operations (Google SecOps), Pub/Sub (untuk penyerapan SIEM pihak ketiga), BigQuery, atau Cloud Storage. Untuk perintah pembuatan sink gcloud CLI dan contoh filter, lihat Mengekspor log audit ke SIEM.

Cloud Monitoring

Agent Gateway mengekspor beberapa metrik Service Extensions ke Monitoring. Jika Anda mendelegasikan otorisasi ke Service Extensions, Anda dapat menggunakan metrik ini untuk memantau traffic ke dan dari ekstensi Anda. Untuk mengetahui detailnya, lihat Logging dan pemantauan untuk pesan info Cloud Load Balancing.

Dasbor kemampuan observasi

Agent Gateway menyediakan dasbor kemampuan observasi yang memungkinkan Anda memantau, mengaudit, dan men-debug traffic yang dirutekan melalui gateway:

  • Kartu skor: Melacak jumlah total percobaan otorisasi, kegagalan otorisasi, dan permintaan per detik.
  • Diagram: Memvisualisasikan rasio kegagalan otorisasi (%) dan permintaan per detik dari waktu ke waktu.
  • Log traffic egress: Tinjau log mendetail untuk kueri egress, termasuk penolakan 403, traffic ke endpoint yang tidak terdaftar, dan tren traffic secara keseluruhan.

Gunakan langkah-langkah berikut untuk mengakses dasbor kemampuan observasi untuk gateway di konsol Google Cloud :

  1. Di konsol Google Cloud , buka halaman Agent Gateway.

    Buka Agent Gateway

  2. Klik nama gateway yang ingin Anda pantau.

  3. Klik tab Observability.

Persyaratan data dasbor

Dasbor kemampuan observasi Agent Gateway menggunakan Observability Analytics untuk menampilkan data. Jika dasbor tidak memuat data, pastikan Anda mengupgrade bucket log _Default untuk menggunakan Observability Analytics. Dasbor mengambil data dari tampilan _AllLogs bucket _Default.

Menggunakan Cloud Trace

Agent Gateway terintegrasi dengan Cloud Trace untuk memberikan observabilitas permintaan end-to-end untuk workload agen. Karena Agent Gateway berfungsi sebagai titik kontrol pusat untuk agen AI, mengaktifkan Trace akan memberi Anda visibilitas tentang cara permintaan berpindah dari agen Anda melalui gateway dan di berbagai layanan, Google Cloud alat, agen, dan server MCP. Dengan melacak alur permintaan di seluruh batas layanan ini, Trace memberikan pelacakan terdistribusi yang lengkap untuk arsitektur agen Anda.

Dengan menggunakan Trace, Anda dapat melakukan hal berikut:

  • Debug interaksi agen dengan presisi: Lacak seluruh perjalanan permintaan di seluruh batas layanan untuk mengisolasi bottleneck latensi dan panggilan backend yang gagal.
  • Hormati keputusan sampling upstream: Gunakan sampling berbasis induk untuk mempertahankan kontinuitas trace end-to-end saat agen atau klien upstream memulai pelacakan, sehingga memastikan permintaan prioritas tinggi sepenuhnya dicatat tanpa meningkatkan frekuensi sampling dasar untuk traffic rutin.
  • Menyatukan kemampuan observasi dengan standar terbuka: Dibangun berdasarkan standar OpenTelemetry dan W3C TraceContext, trace menyebarkan konteks dengan lancar di seluruh agen AI, Agent Gateway, server atau alat MCP target, dan platform pemantauan pihak ketiga.
  • Mempercepat analisis akar masalah: Korelasikan span trace secara langsung dengan log dan metrik permintaan gateway menggunakan trace_id untuk memecahkan masalah produksi lebih cepat.

Untuk mempelajari Trace lebih lanjut, lihat Ringkasan Cloud Trace.

Peran yang diperlukan

Anda harus memiliki peran Identity and Access Management (IAM) berikut di project Anda:

  • Untuk mengonfigurasi dan memperbarui kebijakan pelacakan: Compute Network Admin (roles/compute.networkAdmin) atau Compute Admin (roles/compute.admin)
  • Untuk melihat trace di konsol Google Cloud : Pengguna Cloud Trace (roles/cloudtrace.user)

Selain itu, agar Gateway Agen dapat menulis span trace ke Trace, Anda harus memberikan peran Agen Cloud Trace (roles/cloudtrace.agent) ke akun layanan berikut:

  • Agen layanan Compute Engine: service-PROJECT_NUMBER@compute-system.iam.gserviceaccount.com
  • Agen layanan keamanan jaringan: service-PROJECT_NUMBER@gcp-sa-networksecurity.iam.gserviceaccount.com
  • Agen layanan Agent Gateway: service-PROJECT_NUMBER@gcp-sa-agentgateway.iam.gserviceaccount.com
  • Akun layanan workload agen atau klien: Jika agen AI atau workload klien yang memanggil memulai trace dan mengekspor span induknya sendiri ke Trace, akun layanan workload atau akun layanan kustom yang dilampirkan ke agen juga harus diberi peran roles/cloudtrace.agent di project. Jika tidak, hanya span turunan Agent Gateway yang akan ditulis dan span induk akan hilang di Trace.

Ganti PROJECT_NUMBER dengan nomor project Google Cloud Anda.

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

Mengaktifkan pelacakan

Untuk mengaktifkan pelacakan untuk Gateway Agen, buat file YAML kebijakan kemampuan observasi dan impor menggunakan gcloud CLI.

  1. Buat file konfigurasi bernama tracing-policy.yaml:

    name: "projects/PROJECT_ID/locations/REGION/telemetryPolicies/POLICY_NAME"
    telemetryTarget:
      resources: # You can attach a policy to multiple gateways
      - "//networkservices.googleapis.com/projects/PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_NAME"
    displayName: "Tracing policy for Agent Gateway traffic"
    tracingConfiguration:
      samplingRate: SAMPLING_RATE
      parentBasedSampling:
        enabled: ENABLE_PARENT_BASED_SAMPLING
        samplingRate: PARENT_BASED_SAMPLING_RATE
    

    Ganti kode berikut:

    • PROJECT_ID: Project ID Google Cloud Anda.
    • REGION: Region gateway Anda (misalnya, europe-west1).
    • POLICY_NAME: Nama untuk kebijakan kemampuan observasi (misalnya, my-agw-tracing-policy).
    • AGENT_GATEWAY_NAME: Nama gateway Anda.
    • SAMPLING_RATE: Fraksi permintaan yang akan dilacak. Tetapkan ke nilai dari 0.0 hingga 1.0. Untuk lingkungan produksi dengan traffic tinggi, sebaiknya gunakan rasio 1% (0.01) atau 0,1% (0.001) untuk menyeimbangkan biaya kemampuan observasi dan penyerapan.
    • ENABLE_PARENT_BASED_SAMPLING: Mengontrol apakah akan mematuhi bit sampel di header traceparent yang masuk dari pemanggil upstream. Tetapkan ke true atau false.
    • PARENT_BASED_SAMPLING_RATE: Fraksi permintaan yang telah diambil sampelnya untuk dilacak. Tetapkan ke nilai dari 0.0 hingga 1.0. Misalnya, 1.0 melacak 100% permintaan yang telah diambil sampelnya.
  2. Impor kebijakan kemampuan observasi:

    gcloud beta network-services telemetry-policies import POLICY_NAME \
       --source=tracing-policy.yaml \
       --location=REGION
    

Lihat pelacakan

Setelah mengaktifkan pelacakan terdistribusi dan mengirim traffic melalui gateway, Anda dapat melihat detail trace di konsol Google Cloud :

  1. Di konsol Google Cloud , buka halaman Trace explorer:

    Buka Trace explorer

    Anda juga dapat menemukan halaman ini menggunakan kotak penelusuran.

  2. Di panel Filter, masukkan ekspresi filter trace (misalnya, untuk memfilter berdasarkan batas latensi, kode status HTTP, atau URI permintaan) atau telusuri berdasarkan ID trace tertentu.

    Untuk mempelajari lebih lanjut cara menggunakan UI Trace Explorer, lihat Menemukan dan menjelajahi trace.

    Trace Explorer

    Tampilan Trace Explorer di Trace
    Tampilan Trace Explorer di Trace

    Tampilan linimasa trace

    Tampilan linimasa di Trace
    Tampilan linimasa di Trace

    Tampilan grafik trace

    Tampilan grafik di Trace
    Tampilan grafik di Trace

Menghubungkan trace dengan log dan metrik

Agent Gateway menyediakan korelasi yang lancar antara trace, log, dan metrik:

  • Korelasi log-trace: setiap entri log permintaan gateway yang ditulis ke Logging berisi kolom trace dengan format: projects/PROJECT_ID/traces/TRACE_ID.

    • Di Logs Explorer, klik entri log, lalu pilih View trace details untuk langsung membuka span yang sesuai di Trace.
    • Di Trace, klik Show logs di panel Trace Details untuk melihat semua log permintaan gateway yang terkait dengan permintaan tersebut.
  • Korelasi metrik: bandingkan lonjakan latensi yang diamati dalam metrik Monitoring, seperti networkservices.googleapis.com/agentgateway/total_latencies, dengan perincian span trace untuk mengidentifikasi apakah lonjakan latensi terjadi dalam gateway atau di alat atau server tujuan.

Pemecahan masalah

Bagian ini menjelaskan masalah umum dan penyelesaiannya.

  • Trace tidak muncul di Cloud Trace:

    1. Pastikan Cloud Trace API (cloudtrace.googleapis.com) diaktifkan di project Anda:

      gcloud services enable cloudtrace.googleapis.com --project=PROJECT_ID
      
    2. Pastikan peran IAM Agen Cloud Trace (roles/cloudtrace.agent) yang diperlukan telah diberikan ke semua akun layanan yang diperlukan.

    3. Pastikan kebijakan kemampuan observasi ada di region yang benar dan merujuk ke gateway Agent Gateway yang sesuai:

      gcloud beta network-services telemetry-policies describe POLICY_NAME \
          --location=REGION
      
    4. Periksa samplingRate yang dikonfigurasi. Jika volume traffic rendah atau frekuensi sampling rendah, trace mungkin tidak langsung diambil. Untuk mengonfirmasi bahwa pelacakan berfungsi, Anda dapat memperbarui kebijakan untuk sementara agar menggunakan pengambilan sampel 100% (samplingRate: 1.00). Pulihkan rasio produksi setelah Anda selesai melakukan pengujian.

  • Span trace yang tidak lengkap:

    Jika span trace muncul sebagai trace root independen atau terputus, bukan span turunan dari permintaan aplikasi Anda, lakukan hal berikut:

    1. Pastikan parentBasedSampling diaktifkan (disetel ke true) dalam kebijakan kemampuan observasi Anda.
    2. Pastikan akun layanan agen AI atau workload yang memanggil telah diberi peran Cloud Trace Agent (roles/cloudtrace.agent) pada project agar span induk dapat diekspor ke Trace.
    3. Pastikan aplikasi Anda menggunakan SDK OpenTelemetry yang telah mengaktifkan propagasi konteks pelacakan terdistribusi sehingga header traceparent W3C disebarkan di seluruh batas layanan. Untuk mengetahui informasi selengkapnya, lihat dokumentasi propagator TraceContext OpenTelemetry.

Langkah berikutnya

Codelab

Pelajari cara mengelola workload agentic dengan Agent Gateway di Gemini Enterprise Agent Platform.

Pemecahan masalah

Pelajari cara memecahkan masalah konektivitas Agent Gateway.