Menginstrumentasi aplikasi ADK dengan OpenTelemetry

Dokumen ini menjelaskan cara melengkapi agen AI yang dibuat dengan framework Agent Development Kit (ADK). Framework ADK menyertakan instrumentasi OpenTelemetry yang mengumpulkan telemetri dari tindakan utama agen. Saat Anda mengaktifkan instrumentasi bawaan, instrumentasi tersebut akan mengirimkan informasi seperti perintah teks dan respons agen ke project Google Cloud Anda. Dokumen ini menguraikan perubahan yang diperlukan dan menyediakan link ke aplikasi contoh.

Aplikasi yang menggunakan ADK juga dapat mengumpulkan perintah dan respons multimodal. Dokumen ini menjelaskan cara mengumpulkan perintah dan respons teks. Jika Anda ingin mengumpulkan data multimodal, diperlukan konfigurasi tambahan. Untuk mengetahui informasi selengkapnya, lihat Mengumpulkan dan melihat perintah dan respons multimodal.

Kemampuan observasi default yang disediakan oleh ADK mungkin tidak cukup untuk kasus penggunaan aplikasi Anda. Anda dapat menambahkan library instrumentasi tambahan menggunakan OpenTelemetry untuk mengambil telemetri dari bagian lain aplikasi, atau instrumentasi kustom Anda sendiri untuk mengambil data khusus aplikasi guna mendapatkan visibilitas yang lebih mendetail. Misalnya, dalam aplikasi, Anda dapat menulis kode instrumentasi untuk:

• Melacak konsumsi resource alat yang dipanggil agen.
• Lacak kegagalan validasi khusus aplikasi, pelanggaran aturan bisnis, atau mekanisme pemulihan dari error kustom.
• Lacak skor kualitas untuk respons agen berdasarkan kriteria khusus domain Anda.

Catatan: Dokumen ini mengasumsikan bahwa Anda menggunakan framework ADK dengan versi 1.17.0 atau yang lebih tinggi.

Melengkapi aplikasi AI generatif Anda untuk mengumpulkan telemetri

Untuk melengkapi agen AI Anda agar dapat mengumpulkan data log, metrik, dan trace, lakukan hal berikut:

1. Instal paket OpenTelemetry.
2. Konfigurasikan lingkungan ADK Anda.

Bagian selanjutnya menjelaskan langkah-langkah sebelumnya.

Menginstal paket OpenTelemetry

Tambahkan paket instrumentasi dan pengekspor OpenTelemetry berikut:

uv add 'google-adk>=2.12.0' \
  'opentelemetry-instrumentation-google-genai>=0.7b1' \
  'opentelemetry-instrumentation-sqlite3>=0.63b1' \
  'opentelemetry-exporter-otlp-proto-grpc>=1.42.1' \
  'opentelemetry-exporter-otlp-proto-http>=1.42.1' \
  'opentelemetry-instrumentation-vertexai>=2.0b0'

Data log, metrik, dan trace dikirim ke Google Cloud menggunakan Telemetry (OTLP) API, yang mengimplementasikan OpenTelemetry Protocol. Library opentelemetry-exporter-otlp-proto-grpc memanggil endpoint API Telemetry (OTLP).

Data trace Anda disimpan dalam format yang umumnya konsisten dengan file proto yang ditentukan oleh OpenTelemetry Protocol. Namun, kolom dapat dikonversi dari jenis data khusus OpenTelemetry ke jenis data JSON sebelum penyimpanan. Untuk mempelajari format penyimpanan lebih lanjut, lihat Skema untuk data trace.

Mengonfigurasi lingkungan ADK Anda

Framework ADK versi 1.17.0 dan yang lebih baru menyertakan dukungan bawaan untuk OpenTelemetry dan mengirim data telemetri OpenTelemetry ke Google Cloud Observability. Untuk mengaktifkannya, konfigurasikan lingkungan ADK Anda:

• Jika Anda menjalankan aplikasi dengan perintah adk web, sertakan flag --otel_to_cloud.

• Di file opentelemetry.env, tetapkan variabel lingkungan berikut:

  OTEL_SERVICE_NAME='adk-sql-agent'
  OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED='true'
  

• Konfigurasikan OpenTelemetry agar menggunakan konvensi semantik terbaru untuk AI generatif.

  OTEL_SEMCONV_STABILITY_OPT_IN='gen_ai_latest_experimental'
  

• Konfigurasikan OpenTelemetry untuk melampirkan pesan sebagai peristiwa.

  OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT='EVENT_ONLY'
  

  Catatan: Jangan tetapkan nilai variabel ini ke true. Saat Anda menggunakan konvensi semantik terbaru, menetapkan nilai variabel ini ke true akan menghasilkan konfigurasi yang tidak valid. Oleh karena itu, data log dan trace tidak dikumpulkan.

  Untuk mengetahui informasi selengkapnya tentang nilai enumerasi yang diizinkan, lihat genai/types.py.

• Sebaiknya Anda juga menambahkan variabel lingkungan berikut ke file opentelemetry.env:

  ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS='false'
  

  Variabel lingkungan ini melakukan hal berikut:

  • Mencegah instrumentasi ADK melampirkan atribut span yang melebihi batas ukuran atribut.
  • Mencegah informasi identitas pribadi (PII) dilampirkan ke span sebagai atribut.

• Anda mungkin perlu menetapkan variabel lingkungan lainnya. Misalnya, jika Anda men-deploy ke Gemini Enterprise Agent Platform, Anda juga perlu menetapkan variabel lingkungan berikut:

  GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY='true'
  

Mendownload dan menjalankan aplikasi contoh

Kode contoh ini mengimplementasikan agen AI generatif yang dibuat menggunakan ADK. Agen ini dilengkapi dengan OpenTelemetry, yang dikonfigurasi untuk mengirim metrik, trace, dan log ke project Google Cloud Anda. Telemetri yang dikirim ke project Anda mencakup perintah dan respons AI generatif.

Persona agen ADK

Agen AI generatif didefinisikan sebagai pakar SQL yang memiliki akses penuh ke database SQLite sementara. Agen ini dibangun dengan Agent Development Kit dan mengakses database menggunakan SQLDatabaseToolkit. Database awalnya kosong.

Sebelum memulai

Login ke akun Google Cloud Anda. Jika Anda baru menggunakan Google Cloud, buat akun untuk mengevaluasi performa produk kami dalam skenario dunia nyata. Pelanggan baru juga mendapatkan kredit gratis senilai $300 untuk menjalankan, menguji, dan men-deploy workload.

Instal Google Cloud CLI.

Jika Anda menggunakan penyedia identitas (IdP) eksternal, Anda harus login ke gcloud CLI dengan identitas gabungan Anda terlebih dahulu.

Untuk melakukan inisialisasi gcloud CLI, jalankan perintah berikut:

gcloud init

Buat atau pilih project Google Cloud .

Peran yang diperlukan untuk memilih atau membuat project

• Memilih project: Memilih project tidak memerlukan peran IAM tertentu—Anda dapat memilih project apa pun yang perannya telah diberikan kepada Anda.
• Membuat project: Untuk membuat project, Anda memerlukan peran Project Creator (roles/resourcemanager.projectCreator), yang berisi izin resourcemanager.projects.create. Pelajari cara memberikan peran.

Catatan: Jika tidak berencana untuk menyimpan resource yang Anda buat dalam prosedur ini, buatlah project, bukan memilih project yang ada. Setelah menyelesaikan langkah ini, Anda dapat menghapus project, yang akan menghapus semua resource yang terkait dengan project ini.

• Buat project Google Cloud :

  gcloud projects create PROJECT_ID

  Ganti PROJECT_ID dengan nama untuk Google Cloud project yang Anda buat.

• Pilih project Google Cloud yang Anda buat:

  gcloud config set project PROJECT_ID

  Ganti PROJECT_ID dengan nama project Google Cloud Anda.

Pastikan penagihan diaktifkan untuk project Google Cloud Anda.

Aktifkan Vertex AI, Service Usage, Telemetry, Cloud Logging, Cloud Monitoring, dan Cloud Trace API, jika belum diaktifkan:

Peran yang diperlukan untuk mengaktifkan API

Untuk mengaktifkan API, Anda memerlukan izin serviceusage.services.enable. Jika Anda membuat project, kemungkinan Anda sudah memiliki izin ini melalui peran Pemilik (roles/owner). Jika tidak, Anda bisa mendapatkan izin ini melalui peran Service Usage Admin (roles/serviceusage.serviceUsageAdmin). Pelajari cara memberikan peran.

gcloud services enable aiplatform.googleapis.com serviceusage.googleapis.com telemetry.googleapis.com logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com

Instal Google Cloud CLI.

Jika Anda menggunakan penyedia identitas (IdP) eksternal, Anda harus login ke gcloud CLI dengan identitas gabungan Anda terlebih dahulu.

Untuk melakukan inisialisasi gcloud CLI, jalankan perintah berikut:

gcloud init

Buat atau pilih project Google Cloud .

Peran yang diperlukan untuk memilih atau membuat project

• Memilih project: Memilih project tidak memerlukan peran IAM tertentu—Anda dapat memilih project apa pun yang perannya telah diberikan kepada Anda.
• Membuat project: Untuk membuat project, Anda memerlukan peran Project Creator (roles/resourcemanager.projectCreator), yang berisi izin resourcemanager.projects.create. Pelajari cara memberikan peran.

Catatan: Jika tidak berencana untuk menyimpan resource yang Anda buat dalam prosedur ini, buatlah project, bukan memilih project yang ada. Setelah menyelesaikan langkah ini, Anda dapat menghapus project, yang akan menghapus semua resource yang terkait dengan project ini.

• Buat project Google Cloud :

  gcloud projects create PROJECT_ID

  Ganti PROJECT_ID dengan nama untuk Google Cloud project yang Anda buat.

• Pilih project Google Cloud yang Anda buat:

  gcloud config set project PROJECT_ID

  Ganti PROJECT_ID dengan nama project Google Cloud Anda.

Pastikan penagihan diaktifkan untuk project Google Cloud Anda.

Aktifkan Vertex AI, Service Usage, Telemetry, Cloud Logging, Cloud Monitoring, dan Cloud Trace API, jika belum diaktifkan:

Peran yang diperlukan untuk mengaktifkan API

Untuk mengaktifkan API, Anda memerlukan izin serviceusage.services.enable. Jika Anda membuat project, kemungkinan Anda sudah memiliki izin ini melalui peran Pemilik (roles/owner). Jika tidak, Anda bisa mendapatkan izin ini melalui peran Service Usage Admin (roles/serviceusage.serviceUsageAdmin). Pelajari cara memberikan peran.

gcloud services enable aiplatform.googleapis.com serviceusage.googleapis.com telemetry.googleapis.com logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com

1. Untuk mendapatkan izin yang Anda perlukan agar aplikasi contoh dapat menulis data log, metrik, dan trace, minta administrator untuk memberi Anda peran IAM berikut pada project Anda:

   • Cloud Telemetry Traces Writer (roles/telemetry.tracesWriter)
   • Logs Writer (roles/logging.logWriter)
   • Monitoring Metric Writer (roles/monitoring.metricWriter)
   • Vertex AI User (roles/aiplatform.user)

   Izin ini sudah cukup jika Anda menjalankan contoh di Cloud Shell, di resource Google Cloud , atau di lingkungan pengembangan lokal.

   Penting: Aplikasi produksi biasanya mengandalkan akun layanan untuk memberikan kredensial yang diperlukan untuk menulis data log, metrik, dan trace. Dalam skenario tersebut, berikan peran sebelumnya ke akun layanan.

2. Pastikan Anda menentukan project kuota. Vertex AI API (aiplatform.googleapis.com) mengharuskan project kuota ditentukan. Untuk mengetahui informasi selengkapnya, lihat Menetapkan project kuota. Misalnya, perintah berikut dapat menetapkan project kuota.

   gcloud config set billing/quota_project PROJECT_ID

Meluncurkan aplikasi

Untuk meluncurkan aplikasi contoh, lakukan hal berikut:

1. Di Cloud Shell, clone repositori:

   git clone https://github.com/GoogleCloudPlatform/opentelemetry-samples.git
   

2. Buka direktori contoh:

   cd opentelemetry-samples/python/adk-sql-agent
   

   Contoh ini berisi file .env yang menetapkan dua variabel lingkungan. Satu variabel mengontrol endpoint yang digunakan SDK. Variabel lainnya menetapkan lokasi.

   Jika Anda lebih suka menggunakan model lain, edit main.py. Pastikan model yang Anda pilih mendukung lokasi yang ditentukan dalam file .env. Untuk mengetahui informasi tentang model, lihat Model Google.

3. Buat lingkungan virtual dan jalankan contoh:

   uv run --env-file opentelemetry.env adk web --otel_to_cloud
   

   Aplikasi akan menampilkan pesan yang mirip dengan berikut ini:

   Application startup complete
   Uvicorn running on http://127.0.0.1:8080
   

4. Untuk berinteraksi dengan agen, pilih URL yang ditampilkan dalam output langkah sebelumnya.

5. Luaskan Select an app dan pilih sql_agent dari daftar agen.

   Catatan: Aplikasi ini memerlukan Berbagi Resource Lintas Origin (CORS). Jika Anda memasukkan perintah dan CORS diblokir, aplikasi akan menampilkan pesan Failed to create session dan command line akan menunjukkan bahwa perintah ditolak, POST /apps/sql_agent/users/user/sessions HTTP/1.1" 403 Forbidden.
   Anda dapat mengaktifkan CORS dengan menambahkan kode berikut ke perintah yang menjalankan contoh:
   

   --allow_origins="regex:.*"

Berinteraksi dengan agen

Untuk berinteraksi dengan agen, ajukan pertanyaan atau berikan perintah. Misalnya, Anda mungkin mengajukan pertanyaan:

What can you do for me ?

Demikian pula, karena sql_agent memiliki persona pakar SQL, Anda dapat memintanya untuk membuat tabel untuk aplikasi Anda dan menulis kueri untuk beroperasi pada tabel yang dibuat. Agen hanya dapat membuat database sementara yang didukung oleh file .db yang dibuat di komputer yang menjalankan aplikasi.

Berikut ini adalah contoh interaksi antara sql_agent dan pengguna:

Tindakan yang dilakukan oleh agen AI generatif tidak bersifat deterministik, sehingga Anda mungkin melihat respons yang berbeda untuk perintah yang sama.

Keluar dari aplikasi

Untuk keluar dari aplikasi, masukkan Ctrl-C pada shell yang digunakan untuk meluncurkan aplikasi.

Melihat trace, metrik, dan log

Bagian ini menjelaskan cara melihat peristiwa AI generatif.

Sebelum memulai

Untuk mendapatkan izin yang Anda perlukan untuk melihat data log, metrik, dan trace, minta administrator untuk memberi Anda peran IAM berikut di project Anda:

• Logs Viewer (roles/logging.viewer)
• Monitoring Viewer (roles/monitoring.viewer)
• Cloud Trace User (roles/cloudtrace.user)

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

Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

Melihat telemetri

Untuk melihat peristiwa AI generatif yang dibuat oleh aplikasi, gunakan halaman Trace Explorer:

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

   Buka Trace explorer

   Anda juga dapat menemukan halaman ini menggunakan kotak penelusuran.

2. Di toolbar, pilih Add filter, pilih Span name, lalu pilih call_llm.

   Berikut ini ilustrasi halaman Trace Explorer setelah memfilter data:

   

   Jika Anda belum pernah menggunakan Cloud Trace, Google Cloud Observability perlu membuat database untuk menyimpan data trace Anda. Pembuatan database dapat memerlukan waktu beberapa menit dan selama periode tersebut, tidak ada data trace yang tersedia untuk dilihat.

3. Untuk menjelajahi data span dan log, pilih span di tabel Spans.

   Halaman Detail akan terbuka. Halaman ini menampilkan trace terkait dan span-nya. Tabel di halaman menampilkan informasi mendetail untuk span yang Anda pilih. Informasi ini mencakup hal berikut:

   • Tab Inputs/Outputs menampilkan peristiwa untuk agen AI generatif. Untuk mempelajari peristiwa ini lebih lanjut, lihat Melihat peristiwa AI generatif.

     Screenshot berikut mengilustrasikan trace, dengan satu span memiliki nama call_llm. Span tersebut memanggil LLM (Model Bahasa Besar) yang mendukung agen ini. Untuk contoh ini, modelnya adalah Gemini. Span Gemini mencakup peristiwa AI generatif:

     

   • Tab Logs & Events mencantumkan entri log dan peristiwa yang terkait dengan span. Jika Anda ingin melihat data log di Logs Explorer, pilih View logs di toolbar tab ini.

     Data log mencakup respons sql_agent. Misalnya, untuk contoh operasi, payload JSON menyertakan konten berikut:

     {
       "logName": "projects/my-project/logs/otel_python_inprocess_log_name_temp",
       "jsonPayload": {
         "content": {
           "parts": [
             0: {
               "text": "Now I can create the table."
             }
             1: {1}
             ],
           "role": "model"
         }
       },
       ...
     }