Mengakses rekaman aktivitas dan rentang

Dokumen ini menjelaskan cara mengakses dan melihat trace serta span yang dihasilkan oleh aplikasi Gemini Enterprise Anda. Trace dan span memberikan insight mendetail tentang performa dan alur eksekusi permintaan dalam aplikasi Anda, seperti saat menggunakan asisten atau agen.

Anda dapat melihat data trace menggunakan Trace Explorer atau langsung dalam setiap agen menggunakan tab Traces agen.

Konsep utama

Bagian ini memperkenalkan konsep utama terkait kemampuan observasi di Gemini Enterprise.

Konsep	Deskripsi
Trace	Trace adalah kumpulan span yang mewakili satu permintaan atau transaksi saat mengalir melalui berbagai layanan dan komponen. Misalnya, trace merepresentasikan seluruh siklus proses permintaan. Hal ini mencakup pengguna yang mengajukan pertanyaan dari asisten Gemini Enterprise, respons asisten Gemini Enterprise, dan tindakan berikutnya yang dipicu oleh jawaban, seperti mengirim email.
Span	Span adalah satu unit kerja berjangka waktu dalam trace. Span mewakili operasi tertentu, seperti panggilan fungsi, permintaan API, atau kueri database. Setiap span mencakup detail seperti waktu mulai dan berakhirnya, ID unik, dan hubungannya dengan span lain. Hubungan ini bersama-sama membentuk trace.
Log rentang	Log rentang adalah pesan atau peristiwa bentuk bebas yang diberi stempel waktu dan terkait dengan rentang tertentu. Atribut memberikan informasi kontekstual yang mendetail tentang eksekusi span, sehingga membantu pengguna men-debug masalah dan memahami alur permintaan.

Sebelum memulai

Pastikan Anda memiliki:

• Peran Gemini Enterprise Admin atau peran Pengguna Gemini Enterprise konsol Google Cloud .

• Aplikasi web Gemini Enterprise yang sudah ada. Untuk mengetahui informasi tentang cara membuat aplikasi baru, lihat Membuat aplikasi.

• Untuk mengakses trace, Anda harus memiliki peran Cloud Trace User (roles/cloudtrace.user).

• Aktifkan setelan kemampuan observasi Enable instrumentation of OpenTelemetry traces and logs. Bergantung pada jenis agen, Anda dapat mengaktifkan fitur ini di konfigurasi tingkat aplikasi (untuk agen Asisten Inti) atau di dalam tab Konfigurasi agen (untuk agen buatan karyawan Workflow Builder dan agen Deep Research). Untuk mengetahui informasi selengkapnya, lihat Mengelola setelan kemampuan observasi.

Retensi data

Trace dan span yang dihasilkan oleh aplikasi Gemini Enterprise Anda disimpan di Cloud Trace dalam project Google Cloud Anda, dan retensinya diatur oleh Cloud Trace. Secara default, Cloud Trace menyimpan data rentang selama 30 hari; data yang lebih lama dari periode retensi akan dihapus secara otomatis. Untuk mengetahui nilai retensi yang kredibel dan terbaru, lihat Periode retensi Cloud Trace dalam dokumentasi Kuota dan batas Cloud Trace.

Mengakses rekaman aktivitas di Penjelajah Trace

Untuk mengakses trace dan span menggunakan Trace Explorer, ikuti langkah-langkah berikut:

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

   Buka Trace Explorer

2. Pilih Google Cloud project tempat aplikasi Gemini Enterprise Anda dibuat. Anda akan melihat semua span untuk project Anda.

3. Di tabel, klik Span ID untuk melihat detail rekaman aktivitas, termasuk durasi rentang dan atribut lainnya.

   Catatan: Untuk mengetahui informasi selengkapnya tentang penggunaan Trace Explorer, lihat Menemukan dan menjelajahi rekaman aktivitas.

   

Memfilter dan menelusuri rekaman aktivitas

Dalam Penjelajah Trace untuk project Anda, Anda dapat mengisolasi dan menganalisis eksekusi agen Gemini Enterprise dan konektor data menggunakan filter, parameter kueri, dan atribut berikut:

• Filter berfaset:
  • Service: Filter menurut AssistantService atau connectorsexecution untuk mengisolasi jalur permintaan agen platform dan konektor data.
  • Span: Filter menurut /AssistantService.StreamAssist untuk menemukan span giliran pengguna root, atau telusuri span turunan seperti execute_tool <tool_name> dan invoke_connector <connector>.
• Pencarian ID Trace Langsung: Temukan trace secara langsung menggunakan ID trace W3C 32 karakter standar, yang dapat diekstrak dari header respons x-cloud-trace-context dari StreamAssist.
• Atribut kustom: Buat kueri berdasarkan atribut gemini_enterprise.assist_token pada span execute_tool atau invoke_connector untuk memetakan token bantuan lama tingkat giliran ke waterfall trace W3C.
• Atribut resource: Setiap span yang diekspor membawa cloud.region,
• Atribut resource: Setiap span yang diekspor membawa atribut cloud.region. Atribut ini merepresentasikan lokasi penayangan Gemini Enterprise yang menangani permintaan, seperti global, us, atau eu. Anda dapat memfilter menurut atribut ini untuk membandingkan performa di berbagai wilayah. Perbandingan ini berguna jika konektor data berhasil di satu lokasi, tetapi gagal di lokasi lain. Nilai ini mewakili lokasi yang menyajikan aplikasi Anda, bukan region yang menghosting sumber data pihak ketiga. Untuk menerapkan filter ini, lihat Menerapkan filter rentang.

Mengakses trace untuk agen

Anda juga dapat melihat rentang rekaman aktivitas secara langsung untuk setiap agen di tab Traces agen, yang menampilkan ringkasan kronologis mendetail tentang rekaman pelacakan rentang dan struktur eksekusi induk-turunan.

Catatan: Tab Traces tersedia untuk agen Core Assistant, agen buatan karyawan Workflow Builder, dan agen Deep Research.

Untuk mengakses trace agen:

1. Di konsol Google Cloud , buka aplikasi Anda, lalu klik Agents.
2. Pilih agen yang ingin Anda periksa, lalu klik tab Traces.

Tabel ringkasan rekaman aktivitas

Tabel utama di tab Traces menampilkan informasi berikut untuk setiap rentang rekaman aktivitas:

• Status: Status trace saat ini (saat ini menampilkan Unset).
• ID span trace: ID unik untuk span trace. Klik link ID rentang untuk melihat perincian detailnya.
• Nama Span: Deskripsi singkat tentang pekerjaan yang dilakukan span. Contoh rentang untuk konektor data Gemini Enterprise meliputi:
  • execute_tool <tool_name>: Dipancarkan selama lapisan pengiriman alat di runtime agen (misalnya, execute_tool federated_search).
  • invoke_connector <connector>: Dibuat oleh lapisan eksekusi konektor untuk merepresentasikan logika permintaan ke konektor tertentu (misalnya, invoke_connector jira atau invoke_connector servicenow), yang menggantikan rentang RPC sisi layanan default.
• Jenis Rentang: Jenis rentang. Opsinya mencakup:
  • Agent to Tool: Pemanggilan dari agen ke alat eksternal (digunakan kembali untuk operasi execute_tool dan invoke_connector).
  • Invoke Agent: Pemanggilan agen.
  • Agent to Model: Permintaan dari agen ke model bahasa besar.
• Durasi: Waktu yang diperlukan untuk menyelesaikan rentang rekaman aktivitas (dalam menit).
• Input: Data input atau pesan yang dikirim ke span, jika ada.
• Output: Hasil output yang ditampilkan oleh rentang, jika ada.
• Waktu Mulai: Stempel waktu yang tepat saat span mulai dieksekusi.

Tampilan rekaman aktivitas mendetail

Mengklik Trace span ID akan membuka halaman mendetail yang menampilkan:

1. Ringkasan: Lihat metadata dasar pengukuran, termasuk Waktu mulai, Durasi, dan total jumlah Span. Anda dapat mengklik View in Cloud Trace atau beralih antara tombol tampilan Graph dan Timeline.
2. Visualisasi: Beralih antara hierarki grafis atau tampilan linimasa yang menunjukkan hubungan induk-turunan dari semua span trace.
3. Detail span yang dipilih: Pilih satu span untuk menampilkan bagian mendetail, yang dapat mencakup:
   • Ringkasan: Menampilkan nama rentang, layanan target, jumlah total rentang dengan tindakan ini, dan total durasi (dalam detik).
   • Log: Melihat detail peristiwa yang relevan jika dikonfigurasi. Klik Lihat log untuk langsung membuka log standar.
   • Evaluasi: Menampilkan hasil evaluasi, jika dikonfigurasi.
   • Input & Output: Lengkapi payload permintaan dan respons.
   • Logs & Events: Daftar peristiwa yang terjadi selama eksekusi span ini.
   • Stacktrace: Detail error jika eksekusi rentang gagal.
   • Metadata & Links: Link yang merujuk ke entity cloud explorer terkait.
   • Atribut: Tag resource dan parameter kemampuan observasi nilai kunci tambahan.

Hierarki span induk-turunan

Untuk eksekusi konektor data, penyesuaian rentang induk-turunan dalam satu rekaman aktivitas W3C membantu menunjukkan dengan tepat tempat terjadinya latensi atau error:

1. /AssistantService.StreamAssist: Span platform C++ root yang memulai permintaan.
2. invoke_agent core_assistant: Rentang eksekusi agen.
3. execute_tool <tool_name>: Span eksekusi alat yang aktif (misalnya, execute_tool federated_search).
4. invoke_connector <connector_name> (misalnya, invoke_connector jira atau invoke_connector servicenow): Rentang eksekusi konektor, yang mewakili siklus proses permintaan ke endpoint pihak ketiga.

Telemetri konvensi semantik AI generatif eksperimental

Peringatan: Telemetri konvensi semantik AI generatif yang dijelaskan di bagian ini bersifat eksperimental. Atribut, skema, dan format dapat berubah dalam rilis mendatang.

Selain telemetri yang stabil, span trace Gemini Enterprise menyertakan metadata yang lebih lengkap berdasarkan konvensi semantik AI generatif OpenTelemetry. OpenTelemetry mengklasifikasikan konvensi ini sebagai Status pengembangan. Status tersebut berlaku untuk spesifikasi tahap awal yang dapat berubah atau dihapus dan tidak boleh diandalkan dalam produksi. Karena konvensi ini belum stabil, telemetri Gemini Enterprise ini bersifat eksperimental. Rentang ini mencakup gen_ai.* atribut yang menjelaskan aktivitas agen, model, dan alat, seperti eksekusi agen dan alat serta langkah-langkah perintah dan respons.

Konten perintah dan respons dalam span rekaman aktivitas (seperti teks perintah dan jawaban yang dihasilkan) hanya muncul jika setelan visibilitas Anda mengizinkan logging input perintah dan output respons. Jika tidak, konten akan disamarkan atau dihilangkan. Untuk mengubah setelan ini, lihat Mengelola setelan kemampuan observasi.