Menginstrumentasi aplikasi ADK dengan OpenTelemetry

Pratinjau

Fitur ini tunduk kepada "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 menginstrumentasikan agen AI yang dibangun dengan framework Agent Development Kit (ADK). Pengukuran ini, yang memanfaatkan OpenTelemetry, memungkinkan Anda mengumpulkan perintah pengguna, respons agen, dan pilihan agen.

Framework ADK itu sendiri diinstrumentasikan dengan OpenTelemetry yang merekam telemetri dari langkah-langkah utama dalam eksekusi agen Anda. Hal ini memberikan kemampuan observasi aplikasi yang berharga dan siap digunakan. Namun, observabilitas ini mungkin tidak memadai untuk kasus penggunaan aplikasi Anda. Anda dapat menambahkan library instrumentasi tambahan menggunakan OpenTelemetry untuk merekam telemetri dari bagian lain aplikasi Anda, atau instrumentasi kustom Anda sendiri untuk merekam data khusus aplikasi guna mendapatkan kemampuan observasi yang lebih terperinci.

Misalnya, di aplikasi, Anda dapat menulis kode instrumentasi untuk:

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

Melengkapi aplikasi AI generatif Anda untuk mengumpulkan telemetri

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

1. Instal paket OpenTelemetry
2. Mengonfigurasi OpenTelemetry untuk mengumpulkan dan mengirim telemetri
3. Menulis titik entri kustom untuk menyuntikkan OpenTelemetry yang dikonfigurasi

Bagian selanjutnya dalam bagian ini menjelaskan langkah-langkah sebelumnya.

Menginstal paket OpenTelemetry

Tambahkan paket instrumentasi dan pengekspor OpenTelemetry berikut:

pip install 'opentelemetry-instrumentation-google-genai' \
  '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 Google Cloud Anda menggunakan Cloud Logging API atau Cloud Monitoring API. Library opentelemetry-exporter-gcp-logging dan opentelemetry-exporter-gcp-monitoring memanggil endpoint di API tersebut.

Data trace dikirim ke Google Cloud menggunakan Telemetry (OTLP) API, yang mendukung format OTLP. Data yang diterima melalui endpoint ini juga disimpan dalam format OTLP. Library opentelemetry-exporter-otlp-proto-grpc memanggil endpoint Telemetry (OTLP) API.

Mengonfigurasi OpenTelemetry untuk mengumpulkan dan mengirim telemetri

Dalam kode inisialisasi agen ADK, tambahkan kode untuk mengonfigurasi OpenTelemetry agar mengambil dan mengirim telemetri ke project Google Cloud Anda:

Untuk melihat contoh lengkap, klik Lainnya, lalu pilih Lihat di GitHub.

def setup_opentelemetry() -> None:
    credentials, project_id = google.auth.default()
    resource = Resource.create(
        attributes={
            SERVICE_NAME: "adk-sql-agent",
            # The project to send spans to
            "gcp.project_id": project_id,
        }
    )

    # Set up OTLP auth
    request = google.auth.transport.requests.Request()
    auth_metadata_plugin = AuthMetadataPlugin(credentials=credentials, request=request)
    channel_creds = grpc.composite_channel_credentials(
        grpc.ssl_channel_credentials(),
        grpc.metadata_call_credentials(auth_metadata_plugin),
    )

    # Set up OpenTelemetry Python SDK
    tracer_provider = TracerProvider(resource=resource)
    tracer_provider.add_span_processor(
        BatchSpanProcessor(
            OTLPSpanExporter(
                credentials=channel_creds,
                endpoint="https://telemetry.googleapis.com:443/v1/traces",
            )
        )
    )
    trace.set_tracer_provider(tracer_provider)

    logger_provider = LoggerProvider(resource=resource)
    logger_provider.add_log_record_processor(
        BatchLogRecordProcessor(CloudLoggingExporter())
    )
    logs.set_logger_provider(logger_provider)

    event_logger_provider = EventLoggerProvider(logger_provider)
    events.set_event_logger_provider(event_logger_provider)

    reader = PeriodicExportingMetricReader(CloudMonitoringMetricsExporter())
    meter_provider = MeterProvider(metric_readers=[reader], resource=resource)
    metrics.set_meter_provider(meter_provider)

    # Load instrumentors
    SQLite3Instrumentor().instrument()
    # ADK uses Vertex AI and Google Gen AI SDKs.
    VertexAIInstrumentor().instrument()
    GoogleGenAiSdkInstrumentor().instrument()

Menulis titik entri kustom untuk menggunakan OpenTelemetry yang dikonfigurasi

Untuk menggunakan OpenTelemetry bagi instrumentasi, buat titik entri kustom untuk aplikasi ADK Anda. Titik entri kustom harus mengonfigurasi OpenTelemetry sebelum meluncurkan agen ADK.

Dalam aplikasi contoh, metode main bertindak sebagai titik entri kustom yang menginisialisasi OpenTelemetry, lalu meluncurkan server FastAPI yang memungkinkan Anda berinteraksi dengan agen.

Untuk melihat contoh lengkap, klik Lainnya, lalu pilih Lihat di GitHub.

def main() -> None:
    # Make sure to set:
    # OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true
    # OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
    # in order to full prompts and responses and logs messages.
    # For this sample, these can be set by loading the `opentelemetry.env` file.
    setup_opentelemetry()

    # Call the function to get the FastAPI app instance.
    # Ensure that the agent director name is the name of directory containing agent subdirectories,
    # where each subdirectory represents a single agent with __init__.py and agent.py files.
    # For this example this would be the current directory containing main.py.
    # Note: Calling this method attempts to set the global tracer provider, which has already been
    # set by the setup_opentelemetry() function.
    app = get_fast_api_app(
        agents_dir=AGENT_DIR,
        session_service_uri=SESSION_DB_URL,
        allow_origins=ALLOWED_ORIGINS,
        web=SERVE_WEB_INTERFACE,
    )

    # Lauch the web interface on port 8080.
    uvicorn.run(app, host="0.0.0.0", port=int(os.environ.get("PORT", 8080)))

Mendownload dan menjalankan aplikasi contoh

Kode contoh ini mengimplementasikan agen AI generatif yang dibuat menggunakan ADK. Agen dilengkapi dengan OpenTelemetry, yang dikonfigurasi untuk mengirim metrik, trace, 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 didefinisikan 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

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

Install the 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

Create or select a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

• Create a Google Cloud project:

  gcloud projects create PROJECT_ID

  Replace PROJECT_ID with a name for the Google Cloud project you are creating.

• Select the Google Cloud project that you created:

  gcloud config set project PROJECT_ID

  Replace PROJECT_ID with your Google Cloud project name.

Verify that billing is enabled for your Google Cloud project.

Enable the Vertex AI, Telemetry, Cloud Logging, Cloud Monitoring, and Cloud Trace APIs:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

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

Install the 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

Create or select a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

• Create a Google Cloud project:

  gcloud projects create PROJECT_ID

  Replace PROJECT_ID with a name for the Google Cloud project you are creating.

• Select the Google Cloud project that you created:

  gcloud config set project PROJECT_ID

  Replace PROJECT_ID with your Google Cloud project name.

Verify that billing is enabled for your Google Cloud project.

Enable the Vertex AI, Telemetry, Cloud Logging, Cloud Monitoring, and Cloud Trace APIs:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

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

1. Jika Anda menjalankan sampel 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 menyediakan kredensial untuk menulis data log, metrik, dan trace.

   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:

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

Luncurkan aplikasi

Untuk meluncurkan aplikasi contoh, lakukan langkah 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) python main.py
   

   Aplikasi akan menampilkan pesan yang mirip dengan berikut ini:

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

4. Untuk berinteraksi dengan agen, buka browser ke alamat yang tercantum di langkah sebelumnya.

5. Luaskan Pilih agen dan 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 bagi aplikasi Anda dan menulis kueri untuk mengoperasikan tabel yang dibuat. Agen hanya dapat membuat database sementara yang didukung oleh file .db yang dibuat di mesin yang menjalankan aplikasi.

Berikut ini menggambarkan contoh interaksi antara sql_agent dan pengguna:

Create a table for me to store weather data and also insert sample data in
the table. At the end show all data in the table you created.



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)
• 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 kustom atau peran yang telah ditentukan 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 dengan menggunakan kotak penelusuran.

2. Di toolbar, pilih Tambahkan filter, pilih Nama rentang, lalu pilih call_llm.

   Berikut ini menggambarkan 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 tersedia untuk dilihat.

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

   Halaman Detail akan terbuka. Halaman ini menampilkan rekaman aktivitas terkait dan rentang waktunya. Tabel di halaman menampilkan informasi mendetail untuk rentang yang Anda pilih. Informasi ini mencakup hal berikut:

   • Tab GenAI menampilkan peristiwa untuk agen AI generatif. Untuk mempelajari peristiwa ini lebih lanjut, lihat artikel 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, modelnya adalah Gemini. Rentang Gemini mencakup peristiwa AI generatif:

     

   • Tab Log & Peristiwa mencantumkan entri log dan peristiwa yang terkait dengan rentang. Jika Anda ingin melihat data log di Logs Explorer, pilih Lihat log di toolbar tab ini.

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

     {
       "logName": "projects/my-project/logs/otel_python_inprocess_log_name_temp",
       "jsonPayload": {
         "content": {
           "role": "model",
           "parts": [
             {
               "executable_code": null,
               "inline_data": null,
               "thought": null,
               "video_metadata": null,
               "code_execution_result": null,
               "function_response": null,
               "thought_signature": null,
               "text": "Okay, I will create a table named `weather` with columns `id`, `city`, `temperature`, and `date`. Then I will insert some sample rows into the table and display all the data in the table.\n",
               "file_data": null,
               "function_call": null
             }
           ]
         }
       },
       ...
     }
     

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