Menginstrumentasi aplikasi ADK dengan OpenTelemetry

Pratinjau

Fitur ini tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum dari Persyaratan Khusus Layanan. Fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

Dokumen ini menjelaskan cara menginstrumentasi agen AI yang dibuat dengan the Agent Development Kit (ADK) framework. Framework ADK mencakup 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 Anda Google Cloud . 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, konfigurasi tambahan diperlukan. Untuk mengetahui informasi selengkapnya, lihat Mengumpulkan dan melihat perintah dan respons multimodal.

Observabilitas 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 Anda, atau instrumentasi kustom Anda sendiri untuk mengambil data khusus aplikasi guna mendapatkan observabilitas yang lebih mendetail. Misalnya, di aplikasi Anda, Anda dapat menulis kode instrumentasi untuk:

• Melacak konsumsi resource alat yang dipanggil agen.
• Melacak kegagalan validasi khusus aplikasi, pelanggaran aturan bisnis, atau mekanisme pemulihan error kustom.
• Melacak 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.

Menginstrumentasi aplikasi AI generatif untuk mengumpulkan telemetri

Untuk menginstrumentasi agen AI Anda guna mengumpulkan data log, metrik, dan rekaman aktivitas, lakukan hal berikut:

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

Bagian ini menjelaskan langkah-langkah sebelumnya.

Menginstal paket OpenTelemetry

Tambahkan paket instrumentasi dan eksportir OpenTelemetry berikut:

pip install 'google-adk>=1.17.0' \
  'opentelemetry-instrumentation-google-genai>=0.4b0' \
  'opentelemetry-instrumentation-sqlite3' \
  'opentelemetry-exporter-gcp-logging' \
  'opentelemetry-exporter-gcp-monitoring' \
  'opentelemetry-exporter-otlp-proto-grpc' \
  'opentelemetry-instrumentation-vertexai>=2.0b0'

Data log dan metrik dikirim ke project Anda menggunakan Cloud Logging API atau Cloud Monitoring API. Google Cloud Library opentelemetry-exporter-gcp-logging dan opentelemetry-exporter-gcp-monitoring memanggil endpoint di API tersebut.

Data rekaman aktivitas dikirim ke Google Cloud dengan menggunakan Telemetry (OTLP) API, yang mengimplementasikan OpenTelemetry Line Protocol. Library opentelemetry-exporter-otlp-proto-grpc memanggil endpoint Telemetry (OTLP) API.

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

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 mengaktifkan fitur ini, konfigurasi 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'
  

• Konfigurasi OpenTelemetry untuk menggunakan konvensi semantik terbaru untuk AI generatif.

  OTEL_SEMCONV_STABILITY_OPT_IN='gen_ai_latest_experimental'
  

• Konfigurasi OpenTelemetry untuk melampirkan pesan sebagai peristiwa.

  OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT='EVENT_ONLY'
  

  Catatan: Jangan menetapkan 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 rekaman aktivitas tidak dikumpulkan.

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

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

  ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS='false'
  

  Variabel lingkungan ini melakukan hal berikut:

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

• Anda mungkin perlu menetapkan variabel lingkungan lainnya. Misalnya, jika Anda men-deploy ke Platform Agen Gemini Enterprise, Anda juga ingin 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 diinstrumentasi dengan OpenTelemetry, yang dikonfigurasi untuk mengirim metrik, rekaman aktivitas, dan log ke project Anda. Google Cloud Telemetri yang dikirim ke project Anda mencakup perintah dan respons AI generatif.

Persona agen ADK

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

Sebelum memulai

Login ke akun Anda. Google Cloud 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 Google Cloud project.

Peran yang diperlukan untuk memilih atau membuat project

• Memilih project: Memilih project tidak memerlukan peran IAM tertentu Anda dapat memilih project mana pun yang telah diberi peran.
• Membuat project: Untuk membuat project, Anda memerlukan peran Pembuat Project (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 menghapus semua resource yang terkait dengan project ini.

• Buat Google Cloud project:

  gcloud projects create PROJECT_ID

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

• Pilih Google Cloud project yang Anda buat:

  gcloud config set project PROJECT_ID

  Ganti PROJECT_ID dengan nama Google Cloud project Anda.

Pastikan penagihan diaktifkan untuk Google Cloud project Anda.

Aktifkan Vertex AI, Telemetry, Cloud Logging, Cloud Monitoring, dan Cloud Trace API:

Peran yang diperlukan untuk mengaktifkan API

Untuk mengaktifkan API, Anda memerlukan peran IAM Service Usage Admin (roles/serviceusage.serviceUsageAdmin), yang berisi izin serviceusage.services.enable. Pelajari cara memberikan peran.

gcloud services enable aiplatform.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 Google Cloud project.

Peran yang diperlukan untuk memilih atau membuat project

• Memilih project: Memilih project tidak memerlukan peran IAM tertentu Anda dapat memilih project mana pun yang telah diberi peran.
• Membuat project: Untuk membuat project, Anda memerlukan peran Pembuat Project (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 menghapus semua resource yang terkait dengan project ini.

• Buat Google Cloud project:

  gcloud projects create PROJECT_ID

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

• Pilih Google Cloud project yang Anda buat:

  gcloud config set project PROJECT_ID

  Ganti PROJECT_ID dengan nama Google Cloud project Anda.

Pastikan penagihan diaktifkan untuk Google Cloud project Anda.

Aktifkan Vertex AI, Telemetry, Cloud Logging, Cloud Monitoring, dan Cloud Trace API:

Peran yang diperlukan untuk mengaktifkan API

Untuk mengaktifkan API, Anda memerlukan peran IAM Service Usage Admin (roles/serviceusage.serviceUsageAdmin), yang berisi izin serviceusage.services.enable. Pelajari cara memberikan peran.

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

1. Jika Anda menjalankan contoh di Cloud Shell, di Google Cloud resource, atau di lingkungan pengembangan lokal, izin yang tercantum di bagian ini sudah cukup. Untuk aplikasi produksi, biasanya akun layanan memberikan kredensial untuk menulis data log, metrik, dan rekaman aktivitas.

   Untuk mendapatkan izin yang Anda perlukan agar aplikasi contoh dapat menulis data log, metrik, dan rekaman aktivitas, minta administrator Anda untuk memberi Anda peran IAM berikut di project Anda:

   • Penulis Rekaman Aktivitas Telemetri Cloud (roles/telemetry.tracesWriter)
   • Penulis Log (roles/logging.logWriter)
   • Penulis Metrik Monitoring (roles/monitoring.metricWriter)
   • Pengguna Vertex AI (roles/aiplatform.user)

Meluncurkan aplikasi

Untuk meluncurkan aplikasi contoh, lakukan hal berikut:

1. Di Cloud Shell, jalankan perintah berikut:

   git clone https://github.com/GoogleCloudPlatform/opentelemetry-operations-python.git
   

2. Buka direktori contoh:

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

3. Buat lingkungan virtual dan jalankan contoh:

   python -m venv venv/
   source venv/bin/activate
   pip install -r requirements.txt
   env $(cat opentelemetry.env | xargs) adk web --otel_to_cloud
   

   Aplikasi akan menampilkan pesan yang mirip dengan pesan berikut:

   Appplication startup complete
   Uvicorn running on http://0.0.0.0:8080
   

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

5. Luaskan Select an agent , lalu pilih sql_agent dari daftar agen.

Berinteraksi dengan agen

Untuk berinteraksi dengan agen, ajukan pertanyaan atau berikan perintah. Misalnya, Anda dapat 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 mesin yang menjalankan aplikasi.

Berikut ini adalah contoh interaksi antara sql_agent dan pengguna:

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

Keluar dari aplikasi

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

Melihat rekaman aktivitas, metrik, dan log

Bagian ini menjelaskan cara melihat peristiwa AI generatif.

Sebelum memulai

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

• Logs Viewer (roles/logging.viewer)
• Monitoring Viewer (roles/monitoring.viewer)
• Pengguna Cloud Trace (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 Google Cloud konsol, 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 adalah ilustrasi halaman Trace Explorer setelah memfilter data:

   

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

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

   Halaman Details akan terbuka. Halaman ini menampilkan rekaman aktivitas terkait dan rentangnya. Tabel di halaman ini menampilkan informasi mendetail untuk rentang 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 rekaman aktivitas, dengan satu rentang memiliki nama call_llm. Rentang tersebut memanggil LLM (Model Bahasa Besar) yang mendukung agen ini. Untuk contoh ini, LLM-nya adalah Gemini. Rentang Gemini mencakup peristiwa AI generatif:

     

   • Tab Logs &Events mencantumkan entri log dan peristiwa yang terkait dengan rentang tersebut. 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 yang dijalankan, payload JSON mencakup 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"
         }
       },
       ...
     }
     

Contoh diinstrumentasi untuk mengirim data metrik ke project Anda Google Cloud , tetapi tidak menghasilkan metrik apa pun.