Memantau traffic melalui Agent Gateway

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

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.

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 membuat kueri jenis entri log tertentu di Logs Explorer, Anda dapat memfilter kueri menurut 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 Identity-Aware Proxy (IAP).
projects/PROJECT_ID/logs/aiplatform.googleapis.com%2Freasoning_engine_stderr Error startup dan eksekusi 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 pembersihan konten, log tersebut akan dikeluarkan secara terpisah. Untuk mengetahui petunjuk tentang 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 Agent Gateway 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: Mencakup informasi tentang permintaan Agent Gateway.

    • mcpInfo: Mencakup 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 server, agen, atau endpoint MCP 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.

Pemantauan

Agent Gateway mengekspor beberapa metrik Service Extensions ke Cloud 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 anotasi Cloud Load Balancing.

Dasbor kemampuan observasi

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

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

Gunakan langkah-langkah berikut untuk mengakses dasbor pengamatan 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 kebolehpantauan 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 _AllLogs tampilan bucket _Default.

Menggunakan Cloud Trace

Agent Gateway terintegrasi dengan Cloud Trace untuk memberikan kemampuan observasi permintaan menyeluruh untuk workload agen. Karena Agent Gateway berfungsi sebagai titik kontrol pusat untuk agen AI, mengaktifkan Trace memberi Anda visibilitas tentang cara permintaan berjalan dari agen Anda melalui gateway dan di beberapa Google Cloud layanan, 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 Trace, Anda dapat melakukan hal berikut:

  • Men-debug interaksi agen dengan presisi: Lacak seluruh perjalanan permintaan di seluruh batas layanan untuk mengisolasi bottleneck latensi dan panggilan backend yang gagal.
  • Mematuhi keputusan pengambilan sampel upstream: Gunakan pengambilan sampel berbasis induk untuk mempertahankan kontinuitas rekaman aktivitas end-to-end saat agen atau klien upstream memulai pelacakan, memastikan permintaan prioritas tinggi sepenuhnya direkam tanpa meningkatkan rasio pengambilan sampel dasar untuk traffic rutin.
  • Menyatukan kemampuan pengamatan dengan standar terbuka: Dibangun berdasarkan standar OpenTelemetry dan W3C TraceContext, rekaman aktivitas menyebarkan konteks secara lancar di seluruh agen AI, Agent Gateway, server atau alat MCP target, dan platform pemantauan pihak ketiga.
  • Mempercepat analisis akar masalah: Korelasikan rentang rekaman aktivitas secara langsung dengan log dan metrik permintaan gateway menggunakan trace_id untuk memecahkan masalah produksi dengan 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: Admin Jaringan Compute (roles/compute.networkAdmin) atau Admin Compute (roles/compute.admin)
  • Untuk melihat rekaman aktivitas di konsol Google Cloud : Pengguna Cloud Trace (roles/cloudtrace.user)

Selain itu, untuk mengizinkan Agent Gateway menulis rentang rekaman aktivitas ke Trace, Anda harus memberikan peran Cloud Trace Agent (roles/cloudtrace.agent)kepada 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 rekaman aktivitas dan mengekspor rentang induknya sendiri ke Trace, maka akun layanan workload atau akun layanan kustom yang terpasang ke agen juga harus diberi peran roles/cloudtrace.agent di project. Jika tidak, hanya rentang turunan Agent Gateway yang ditulis dan rentang induk tidak akan ada 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 Agent Gateway, buat file YAML kebijakan observabilitas 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 pengamatan (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 pengamatan dan penyerapan.
    • ENABLE_PARENT_BASED_SAMPLING: Mengontrol apakah akan menggunakan bit yang diambil sampelnya di header traceparent masuk dari pemanggil upstream. Tetapkan ke true atau false.
    • PARENT_BASED_SAMPLING_RATE: Bagian 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 pengamatan:

    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 rekaman aktivitas di konsol Google Cloud :

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

    Buka Trace Explorer

    Anda juga dapat menemukan halaman ini dengan menggunakan kotak penelusuran.

  2. Di kolom Filter, masukkan ekspresi filter rekaman aktivitas (misalnya, untuk memfilter menurut nilai minimum latensi, kode status HTTP, atau URI permintaan) atau telusuri menurut ID rekaman aktivitas tertentu.

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

    Penjelajah rekaman aktivitas

    Tampilan Trace Explorer di Cloud Trace
    Tampilan Trace Explorer di Trace

    Tampilan linimasa rekaman aktivitas

    Tampilan linimasa di Cloud Trace
    Tampilan linimasa di Trace

    Tampilan grafik rekaman aktivitas

    Tampilan grafik di Cloud Trace
    Tampilan grafik di Trace

Menghubungkan rekaman aktivitas dengan log dan metrik

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

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

    • Di Logs Explorer, klik entri log, lalu pilih Lihat detail rekaman aktivitas untuk langsung membuka rentang 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 Cloud Monitoring, seperti networkservices.googleapis.com/agentgateway/total_latencies, dengan perincian rentang rekaman aktivitas untuk mengidentifikasi apakah lonjakan latensi terjadi dalam gateway atau di alat atau server tujuan.

Pemecahan masalah

Bagian ini menjelaskan masalah umum dan solusinya.

  • Rekaman aktivitas 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 kepada semua akun layanan yang diperlukan.

    3. Pastikan kebijakan observabilitas 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 pengambilan sampel rendah, rekaman aktivitas mungkin tidak langsung diambil. Untuk mengonfirmasi bahwa pelacakan berfungsi, Anda dapat memperbarui kebijakan untuk sementara waktu agar menggunakan pengambilan sampel 100% (samplingRate: 1.00). Pulihkan rasio produksi Anda setelah selesai melakukan pengujian.

  • Rentang rekaman aktivitas yang tidak lengkap:

    Jika rentang rekaman aktivitas muncul sebagai rekaman aktivitas root yang independen atau terputus, bukan sebagai rentang turunan dari permintaan aplikasi Anda, lakukan hal berikut:

    1. Pastikan parentBasedSampling diaktifkan (ditetapkan ke true) di kebijakan pemantauan Anda.
    2. Pastikan akun layanan agen atau beban kerja AI yang memanggil telah diberi peran Agen Cloud Trace (roles/cloudtrace.agent) di project sehingga rentang induk dapat diekspor ke Trace.
    3. Pastikan aplikasi Anda menggunakan OpenTelemetry SDK yang telah mengaktifkan propagasi konteks pelacakan terdistribusi sehingga header traceparent W3C dipropagasi di seluruh batas layanan. Untuk mengetahui informasi selengkapnya, lihat dokumentasi propagator TraceContext OpenTelemetry.

Langkah berikutnya

Codelab

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

Pemecahan masalah

Pelajari cara memecahkan masalah konektivitas Agent Gateway.