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
Di konsol Google Cloud , buka halaman Logs Explorer.
Klik tombol Show query.
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.
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 |
|
| jsonPayload | object (format Struct) | Wajib | Payload entri log yang dinyatakan sebagai objek JSON. Objek JSON berisi kolom Agent Gateway berikut:
|
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
DENYatau mengalihkaniamEnforcementModedari"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 padaprincipalSetdapat 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_requestsdancloudaudit.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_requestsdancloudaudit.googleapis.com/data_accesske 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 :
Di konsol Google Cloud , buka halaman Agent Gateway.
Klik nama gateway yang ingin Anda pantau.
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_iduntuk 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.agentdi 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.
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_RATEGanti 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 dari0.0hingga1.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 headertraceparentyang masuk dari pemanggil upstream. Tetapkan ketrueataufalse.PARENT_BASED_SAMPLING_RATE: Fraksi permintaan yang telah diambil sampelnya untuk dilacak. Tetapkan ke nilai dari0.0hingga1.0. Misalnya,1.0melacak 100% permintaan yang telah diambil sampelnya.
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 :
-
Di konsol Google Cloud , buka halaman
Trace explorer:
Anda juga dapat menemukan halaman ini menggunakan kotak penelusuran.
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 linimasa trace
Tampilan linimasa di Trace Tampilan grafik 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
tracedengan 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:
Pastikan Cloud Trace API (
cloudtrace.googleapis.com) diaktifkan di project Anda:gcloud services enable cloudtrace.googleapis.com --project=PROJECT_ID
Pastikan peran IAM Agen Cloud Trace (
roles/cloudtrace.agent) yang diperlukan telah diberikan ke semua akun layanan yang diperlukan.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=REGIONPeriksa
samplingRateyang 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:
- Pastikan
parentBasedSamplingdiaktifkan (disetel ketrue) dalam kebijakan kemampuan observasi Anda. - 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. - Pastikan aplikasi Anda menggunakan SDK OpenTelemetry yang telah mengaktifkan propagasi konteks pelacakan terdistribusi sehingga header
traceparentW3C disebarkan di seluruh batas layanan. Untuk mengetahui informasi selengkapnya, lihat dokumentasi propagator TraceContext OpenTelemetry.
- Pastikan
Langkah berikutnya
Codelab: Mengelola workload agentic dengan Agent Platform
Pelajari cara mengelola workload agentic dengan Agent Gateway di Gemini Enterprise Agent Platform.
Memecahkan masalah Agent Gateway
Pelajari cara memecahkan masalah konektivitas Agent Gateway.