OpenTelemetry を使用して ADK アプリケーションを計測する

プレビュー版

この機能は サービス固有の規約の対象となります。 一般提供前の機能は「現状のまま」で提供されるものであり、サポートが制限されることがあります。 詳細については、リリース ステージの説明をご覧ください。

このドキュメントでは、Agent Development Kit（ADK）フレームワークで構築された AI エージェントを計測する方法について説明します。ADK フレームワークには、エージェントの主要なアクションからテレメトリーを収集する OpenTelemetry 計測が含まれています。組み込みの計測機能を有効にすると、その計測機能はテキスト プロンプトやエージェント レスポンスなどの情報を Google Cloud プロジェクトに送信します。このドキュメントでは、必要な変更の概要とサンプル アプリケーションへのリンクを示します。

ADK を使用するアプリケーションは、マルチモーダル プロンプトとレスポンスを収集することもできます。このドキュメントでは、テキスト プロンプトとレスポンスを収集する方法について説明します。マルチモーダル データを収集する場合は、追加の構成が必要です。詳細については、マルチモーダル プロンプトとレスポンスを収集して表示するをご覧ください。

ADK が提供するデフォルトのオブザーバビリティは、アプリケーションのユースケースには十分でない可能性があります。OpenTelemetry を使用してアプリの他の部分からテレメトリーをキャプチャしたり、独自のカスタム計測を使用してアプリケーション固有のデータをキャプチャしたりして、他の計測ライブラリを追加することで、よりきめ細かいオブザーバビリティを実現できます。たとえば、アプリケーションで次のような計測コードを記述できます。

• エージェントが起動したツールのリソース消費量を追跡する。
• アプリケーション固有の検証の失敗、ビジネスルールの違反、カスタムエラー回復メカニズムを追跡する。
• ドメイン固有の基準に基づいて、エージェントの回答の品質スコアを追跡する。

注: このドキュメントでは、バージョン 1.17.0 以降の ADK フレームワークを使用していることを前提としています。

生成 AI アプリケーションを計測してテレメトリーを収集する

AI エージェントを計測してログ、指標、トレースデータを収集する手順は次のとおりです。

1. OpenTelemetry パッケージをインストールします。
2. ADK 環境を構成します。

このセクションの残りの部分では、上記の手順について説明します。

OpenTelemetry パッケージをインストールする

次の OpenTelemetry 計測パッケージとエクスポータ パッケージを追加します。

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'

ログデータと指標データは、Cloud Logging API または Cloud Monitoring API を使用して Google Cloud プロジェクトに送信されます。opentelemetry-exporter-gcp-logging ライブラリと opentelemetry-exporter-gcp-monitoring ライブラリは、これらの API のエンドポイントを呼び出します。

トレースデータは、OpenTelemetry OTLP プロトコルを実装する Telemetry（OTLP）API を使用して Google Cloud に送信されます。opentelemetry-exporter-otlp-proto-grpc ライブラリは、Telemetry（OTLP）API エンドポイントを呼び出します。

トレースデータは、OpenTelemetry OTLP プロトコルで定義された proto ファイルと概ね一致する形式で保存されます。ただし、フィールドは保存前に OpenTelemetry 固有のデータ型から JSON データ型に変換されることがあります。ストレージ形式の詳細については、トレースデータのスキーマをご覧ください。

ADK 環境を構成する

ADK フレームワーク バージョン 1.17.0 以降には、OpenTelemetry の組み込みサポートと、OpenTelemetry テレメトリー データをGoogle Cloud Observability に送信する機能が含まれています。これを有効にするには、ADK 環境を構成します。

• adk web CLI コマンドでアプリケーションを実行するときは、--otel_to_cloud フラグを指定します。

• opentelemetry.env ファイルで、次の環境変数を設定します。

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

• 次の環境変数を opentelemetry.env ファイルに追加することもおすすめします。

  ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS=false
  

  この環境変数は次の処理を行います。

  • ADK 計測が属性サイズの上限を超えるスパン属性を付加しないようにします。
  • 個人を特定できる情報（PII）が属性としてスパンに付加されるのを防ぎます。

サンプル アプリケーションをダウンロードして実行する

このサンプルコードは、ADK を使用して構築された生成 AI エージェントを実装します。エージェントは OpenTelemetry で計測され、指標、トレース、ログを Google Cloud プロジェクトに送信するように構成されています。プロジェクトに送信されるテレメトリーには、生成 AI のプロンプトと回答が含まれます。

ADK エージェントのペルソナ

生成 AI エージェントは、エフェメラル SQLite データベースへの完全アクセス権を持つ SQL エキスパートとして定義されます。エージェントは Agent Development Kit で構築され、SQLDatabaseToolkit を使用してデータベースにアクセスします。データベースは最初は空です。

始める前に

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.

外部 ID プロバイダ（IdP）を使用している場合は、まず連携 ID を使用して gcloud CLI にログインする必要があります。

gcloud CLI を初期化するには、次のコマンドを実行します。

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 role (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.

外部 ID プロバイダ（IdP）を使用している場合は、まず連携 ID を使用して gcloud CLI にログインする必要があります。

gcloud CLI を初期化するには、次のコマンドを実行します。

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 role (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. Cloud Shell、 Google Cloudリソース、ローカル開発環境でサンプルを実行する場合は、このセクションに記載されている権限で十分です。本番環境アプリケーションの場合、通常、サービス アカウントはログ、指標、トレースデータを書き込む認証情報を提供します。

   サンプル アプリケーションがログデータ、指標データ、トレースデータを書き込むために必要な権限を取得するには、プロジェクトに対する次の IAM ロールを付与するよう管理者に依頼してください。

   • Cloud テレメトリー トレース書き込み（roles/telemetry.tracesWriter）
   • ログ書き込み（roles/logging.logWriter）
   • モニタリング指標の書き込み（roles/monitoring.metricWriter）
   • Vertex AI ユーザー（roles/aiplatform.user）

アプリケーションを起動する

サンプルアプリケーションを起動する手順は次のとおりです。

1. Cloud Shell で、次のコマンドを実行します。

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

2. サンプル ディレクトリに移動します。

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

3. 仮想環境を作成してサンプルを実行します。

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

   アプリケーションにより、次のようなメッセージが表示されます。

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

4. エージェントとやり取りするには、前の手順の出力に表示された URL を選択します。

5. [Select an agent] を開き、エージェントのリストから sql_agent を選択します。

エージェントとやり取りする

エージェントに質問したり、指示を出したりして、エージェントとやり取りします。たとえば、次のような質問をします。

What can you do for me ?

同様に、sql_agent のペルソナは SQL エキスパートであるため、アプリケーションのテーブルを作成し、作成したテーブルを操作するクエリを記述するように依頼することもできます。エージェントは、アプリケーションを実行しているマシンで作成された .db ファイルを使用するエフェメラル データベースのみを作成できます。

sql_agent とユーザーのやり取りの例を以下に示します。



生成 AI エージェントによって実行されるアクションは決定的ではないため、同じプロンプトでも回答が異なる場合があります。

アプリケーションを終了する

アプリケーションを終了するには、アプリケーションの起動に使用したシェルで Ctrl-C キーを押します。

トレース、指標、ログを表示する

このセクションでは、生成 AI イベントを表示する方法について説明します。

始める前に

ログ、指標、トレースデータを表示するために必要な権限を取得するには、プロジェクトに対する次の IAM ロールを付与するよう管理者に依頼してください。

• ログ閲覧者（roles/logging.viewer）
• モニタリング閲覧者（roles/monitoring.viewer）
• Cloud トレース ユーザー（roles/cloudtrace.user）

ロールの付与については、プロジェクト、フォルダ、組織に対するアクセス権の管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

テレメトリーを表示する

アプリケーションによって作成された生成 AI イベントを表示するには、[Trace エクスプローラ] ページを使用します。

1. Google Cloud コンソールで、[Trace エクスプローラ] ページに移動します。

   [Trace エクスプローラ] に移動

   このページは、検索バーを使用して見つけることもできます。

2. ツールバーで [フィルタを追加]、[スパン名]、[call_llm] の順に選択します。

   データのフィルタリング後の [Trace エクスプローラ] ページを以下に示します。

   

   Cloud Trace を初めて使用する場合は、Google Cloud Observability によって、トレースデータを保存するデータベースが作成される必要があります。データベースの作成には数分かかることがあり、その間トレースデータを表示することはできません。

3. スパンデータとログデータを調べるには、[スパン] テーブルでスパンを選択します。

   [詳細] ページが開きます。このページには、関連するトレースとそのスパンが表示されます。ページ上のテーブルには、選択したスパンの詳細情報が表示されます。詳細情報には次の情報が含まれます。

   • [入力/出力] タブには、生成 AI エージェントのイベントが表示されます。これらのイベントの詳細については、生成 AI イベントを表示するをご覧ください。

     次のスクリーンショットは、1 つのスパンに call_llm という名前が付けられているトレースを示しています。このスパンは、このエージェントで使用される LLM（大規模言語モデル）を呼び出します。このサンプルでは、Gemini です。Gemini スパンには生成 AI イベントが含まれます。

     

   • [ログとイベント] タブには、スパンに関連付けられているログエントリとイベントが一覧表示されます。ログ エクスプローラでログデータを表示する場合は、このタブのツールバーで [ログを表示] を選択します。

     ログデータには、sql_agent の回答が含まれます。たとえば、サンプル実行の場合、JSON ペイロードには次の内容が含まれます。

     {
       "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"
         }
       },
       ...
     }
     

サンプルが計測され、指標データが Google Cloud プロジェクトに送信されますが、指標は生成されません。