Menginstrumentasikan agen ReAct LangGraph dengan OpenTelemetry

Dokumen ini menguraikan langkah-langkah untuk menginstrumentasi agen LangGraph ReAct dengan OpenTelemetry, sehingga memungkinkan pengumpulan telemetri dari agen. Perintah pengguna serta respons dan pilihan agen disertakan dalam telemetri sebagai atribut yang dilampirkan ke span. Respons agen juga disertakan dalam entri log yang berkorelasi dengan span yang berisi peristiwa AI generatif. Petunjuk dalam dokumen ini berlaku saat agen menggunakan ChatVertexAI Langchain untuk memanggil model Gemini.

Aplikasi yang menggunakan agen ReAct LangGraph 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.

Melengkapi aplikasi AI generatif Anda untuk mengumpulkan telemetri

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

1. Menginstal paket OpenTelemetry
2. Mengonfigurasi OpenTelemetry untuk mengumpulkan dan mengirim telemetri
3. Melacak pemanggilan agen AI generatif

Menginstal paket OpenTelemetry

Tambahkan paket instrumentasi dan pengekspor OpenTelemetry berikut:

uv add 'opentelemetry-instrumentation-vertexai>=2.0b0' \
  'opentelemetry-instrumentation-sqlite3' \
  'opentelemetry-exporter-otlp-proto-grpc'

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 OpenTelemetry untuk mengumpulkan dan mengirim telemetri

Dalam kode inisialisasi agen LangGraph, konfigurasikan OpenTelemetry untuk menangkap dan mengirim telemetri ke project Google Cloud Anda:

Untuk melihat contoh lengkap, di toolbar contoh, pilih logo GitHub.

def setup_opentelemetry() -> None:
    credentials, project_id = google.auth.default()
    resource = Resource.create(
        attributes={
            SERVICE_NAME: "langgraph-sql-agent",
            CLOUD_PROVIDER: "gcp",
            CLOUD_ACCOUNT_ID: project_id,
            # The project to send spans to
            "gcp.project_id": project_id,
            CLOUD_REGION: "us-central1",
            SERVICE_NAMESPACE: "local",
            SERVICE_INSTANCE_ID: "local-instance",
        }
    )

    # 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(
            OTLPLogExporter(
                credentials=channel_creds,
                endpoint="https://telemetry.googleapis.com:443/v1/logs",
            )
        )
    )
    logs.set_logger_provider(logger_provider)

    reader = PeriodicExportingMetricReader(
        OTLPMetricExporter(
            credentials=channel_creds,
            endpoint="https://telemetry.googleapis.com:443/v1/metrics",
        )
    )
    meter_provider = MeterProvider(metric_readers=[reader], resource=resource)
    metrics.set_meter_provider(meter_provider)

    # Load instrumentors
    SQLite3Instrumentor().instrument()
    GoogleGenAiSdkInstrumentor().instrument()

Melacak pemanggilan agen AI generatif

Untuk melacak eksekusi pemanggilan agen LangGraph, buat span kustom di sekitar pemanggilan agen:

Untuk melihat contoh lengkap, di toolbar contoh, pilih logo GitHub.

# Invoke the agent within a span
with tracer.start_as_current_span("invoke agent"):
    result = agent.invoke({"messages": [prompt]}, config=config)

Anda mungkin ingin menyertakan kode sebelumnya di tempat-tempat penting dalam kode aplikasi Anda.

Untuk mempelajari lebih lanjut cara menambahkan span dan metrik kustom, lihat Menambahkan trace dan metrik kustom ke aplikasi.

Menjalankan contoh

Contoh ini adalah agen LangGraph yang diinstrumentasi dengan OpenTelemetry untuk mengirim trace dan log dengan perintah dan respons AI generatif, serta metrik ke projectGoogle Cloud Anda.

Persona agen LangGraph

Agen LangGraph didefinisikan sebagai pakar SQL yang memiliki akses penuh ke database SQLite sementara. Agen diimplementasikan dengan agen ReAct bawaan LangGraph dan mengakses database, yang awalnya kosong, menggunakan SQLDatabaseToolkit.

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

Jalankan contoh

Untuk menjalankan 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/langgraph-sql-agent
   

3. Konfigurasikan variabel lingkungan:

   # Capture GenAI prompts and responses
   export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
   # Capture application logs automatically
   export OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true
   # Set the location to one that supports gemini-3.5-flash
   export GOOGLE_CLOUD_REGION=global
   

   Jika Anda lebih suka menggunakan model lain, edit main.py. Pastikan model Anda mendukung lokasi yang Anda tentukan. Untuk mengetahui informasi tentang model, lihat Model Google.

4. Buat lingkungan virtual dan jalankan contoh:

   uv run main.py
   

   Aplikasi akan menampilkan pesan yang mirip dengan berikut ini:

   Starting agent using ephemeral SQLite DB.
   

5. Untuk membuat database, masukkan nilai pada perintah Talk to the SQL agent >>, lalu tekan Enter.

   Tindakan yang dilakukan oleh agen kemudian akan ditampilkan di Cloud Shell Anda.

   Berikut ini contoh interaksi antara pengguna dan aplikasi:

   Talk to the SQL agent >> Create a new table to hold weather data.
   👤 User: Create a new table to hold weather data.
   🤖 Agent: Okay, I'll create a table to hold weather data. First, I need to decide on the schema for the table. I'll include columns for date, location, temperature, humidity, and precipitation.
   
   CREATE TABLE weather (
     date DATE,
     location VARCHAR(255),
     temperature REAL,
     humidity REAL,
     precipitation REAL
   );
   
   🤖 Agent: I have created the weather table.
   👤 User: Add altitude to the table.
   🤖 Agent
   
   ALTER TABLE weather ADD COLUMN altitude REAL;
   
   

6. Untuk keluar, masukkan Ctrl-C.

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

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, 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 invoke agent.

   Bagian Menjalankan contoh menyertakan contoh eksekusi saat dua prompt dikirim ke aplikasi. 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 invoke_agent. Span tersebut memanggil 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 agen LangGraph. Misalnya, untuk contoh operasi, payload JSON menyertakan konten berikut:

     {
       logName: "projects/my-project/logs/otel_python_inprocess_log_name_temp"
       jsonPayload: {
         message: {
           role: "model"
           content: [
             0: {
               text: "Okay, I'll create a table to hold weather data. First, I need to decide on the schema for the table. I'll include columns for date, location, temperature, humidity, and precipitation.
     
               CREATE TABLE weather (
                   date DATE,
                   location VARCHAR(255),
                   temperature REAL,
                   humidity REAL,
                   precipitation REAL
               );
               "
             }
           ]
         }
       index: 0
       }
     ...
     }
     

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