Mengakses rekaman aktivitas dan rentang

Dokumen ini menjelaskan cara mengakses dan melihat trace dan 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 rekaman aktivitas 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 mewakili seluruh siklus proses permintaan. Hal ini mencakup pengguna yang mengajukan pertanyaan dari asisten Gemini Enterprise, asisten Gemini Enterprise yang merespons, 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 span	Log span adalah pesan atau peristiwa berstempel waktu dan berformat bebas yang terkait dengan span tertentu. Atribut ini 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 Gemini Enterprise User di 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 Pengguna Cloud Trace (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 Core Assistant) atau di dalam tab Configuration 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 span selama 30 hari; data yang lebih lama dari periode retensi akan otomatis dihapus. Untuk mengetahui nilai retensi yang otoritatif dan terbaru, lihat Periode retensi Cloud Trace dalam dokumentasi Kuota dan batas Cloud Trace.

Mengakses trace di Trace Explorer

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 project Google Cloud tempat aplikasi Gemini Enterprise Anda dibuat. Anda akan melihat semua span untuk project Anda.

3. Dalam tabel, klik Span ID untuk melihat detail trace, termasuk durasi span dan atribut lainnya.

   Catatan: Untuk mengetahui informasi selengkapnya tentang cara menggunakan Trace Explorer, lihat Menemukan dan menjelajahi trace.

   

Memfilter dan menelusuri trace

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

• Filter faset:
  • 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 mewakili lokasi penyajian 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 span.

Mengakses trace untuk agen

Anda juga dapat melihat span trace secara langsung untuk setiap agen di tab Traces agen, yang menampilkan ringkasan kronologis mendetail dari rekaman pelacakan span 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 span trace:

• Status: Status trace saat ini (saat ini menampilkan Unset).
• ID span trace: ID unik untuk span trace. Klik link ID span untuk melihat 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 dalam Agent Runtime (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 span RPC sisi layanan default.
• Jenis Span: Jenis span. 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 span trace (dalam menit).
• Input: Data input atau pesan yang dikirim ke span, jika ada.
• Output: Hasil output yang ditampilkan oleh span, jika ada.
• Waktu Mulai: Stempel waktu yang tepat saat span mulai dieksekusi.

Tampilan rekaman aktivitas mendetail

Mengklik Trace span ID akan membuka halaman detail yang menampilkan:

1. Ringkasan: Lihat metadata dasar pengukuran, termasuk Waktu mulai, Durasi, dan jumlah total 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 span, layanan target, jumlah total span dengan tindakan ini, dan total durasi (dalam detik).
   • Log: Melihat detail peristiwa yang relevan jika dikonfigurasi. Klik View logs untuk langsung membuka log standar.
   • Evaluasi: Menampilkan hasil evaluasi, jika dikonfigurasi.
   • Input & Output: Payload permintaan dan respons lengkap.
   • Logs & Events: Daftar peristiwa yang terjadi selama eksekusi span ini.
   • Stacktrace: Detail error jika eksekusi span 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, penyusunan bertingkat span induk-turunan dalam satu trace W3C membantu menentukan 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. Span ini mencakup atribut gen_ai.* yang mendeskripsikan 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.