mcpField
A
adk-observability-guide

adk-observability-guide

github.com/googleクラウド・DevOps1.5k2.6k 回インストール今日更新
リポジトリ

adk-observability-guide について

ADK Observability Guideは、ADKエージェントのトレース、プロンプトと応答のログ、BigQuery分析、外部の可観測性ツールを解説します。開発者がテレメトリーを選んで設定できるよう、構成とトラブルシューティングの情報を提供します。

主な機能

  1. 01Cloud Traceの設定とスパンを解説
  2. 02プロンプト応答ログとプライバシーを説明
  3. 03BigQueryエージェント分析を紹介
  4. 04外部可観測性ツールを比較
  5. 05設定と問題解決のガイドを提供

活用シーン

  1. 01エージェントの実行過程と遅延を追跡
  2. 02モデルとのやり取りを監査
  3. 03BigQueryでエージェントイベントを分析
  4. 04可観測性連携を設定

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/google/adk-docs --skill adk-observability-guide

インストール後、Claude Code で/adk-observability-guideを入力して読み込まれたか確認します。

同梱ファイルreferences/bigquery-agent-analytics.mdreferences/cloud-trace-and-logging.md

詳細

ADK オブザーバビリティガイド

スキャフォールド済みのプロジェクトですか？ Cloud Trace とプロンプト／レスポンスのログ記録は、Terraform によって事前設定されています。インフラストラクチャの詳細、環境変数、検証コマンドについては、references/cloud-trace-and-logging.md をご覧ください。

スキャフォールドされていませんか？ 手動でセットアップするには、以下の ADK ドキュメントへのリンクに従ってください。本番環境のインフラストラクチャには、/adk-scaffold でスキャフォールドしてください。

リファレンスファイル
ファイル内容
references/cloud-trace-and-logging.mdスキャフォールド済みプロジェクトの詳細 — Terraform でプロビジョニングされるリソース、環境変数、検証コマンド、ローカルでの有効化／無効化
references/bigquery-agent-analytics.mdBQ Agent Analytics プラグイン — 有効化、主な機能、GCS へのオフロード、ツールの出所情報

オブザーバビリティの段階

ニーズに応じて、適切なオブザーバビリティのレベルを選択してください。

段階機能対象範囲デフォルトの状態最適な用途
Cloud Trace分散トレース — OpenTelemetry スパンを使用した実行フロー、レイテンシ、エラーの追跡すべてのテンプレート、すべての環境常に有効レイテンシのデバッグ、エージェントの実行フローの把握
プロンプト／レスポンスのログ記録GenAI のやり取りを GCS、BigQuery、Cloud Logging にエクスポートADK エージェントのみローカルでは無効、デプロイ時には有効LLM のやり取りの監査、コンプライアンス
BigQuery Agent Analytics構造化されたエージェントイベント（LLM 呼び出し、ツールの使用、結果）を BigQuery に記録プラグインを有効にした ADK エージェントオプトイン（スキャフォールド時に --bq-analytics を指定）会話分析、カスタムダッシュボード、LLM-as-judge 評価
サードパーティ連携外部オブザーバビリティプラットフォーム（AgentOps、Phoenix、MLflow など）すべての ADK エージェントオプトイン、プロバイダーごとにセットアップチームコラボレーション、専門的な可視化、プロンプト管理

ユーザーに 必要な段階を尋ねてください。複数を組み合わせることもできます。Cloud Trace は常に有効で、その他は追加で利用できます。

Cloud Trace

ADK は OpenTelemetry を使用して分散トレースを出力します。各エージェントの呼び出しでは、実行フロー全体を追跡するスパンが生成されます。

スパンの階層
invocation
  └── agent_run (one per agent in the chain)
        ├── call_llm (model request/response)
        └── execute_tool (tool execution)
デプロイ方法別のセットアップ
デプロイ方法セットアップ
Agent Engine自動 — デフォルトでトレースが Cloud Trace にエクスポートされます
Cloud Run（スキャフォールド済み）自動 — FastAPI アプリで otel_to_cloud=True が設定されています
GKE（スキャフォールド済み）自動 — FastAPI アプリで otel_to_cloud=True が設定されています
Cloud Run / GKE（手動）アプリで OpenTelemetry エクスポーターを設定してください
ローカル開発make playground で動作し、Cloud Console でトレースを確認できます

トレースを表示するには、Cloud Console → Trace → Trace explorer を開いてください。

詳しいセットアップ手順（Agent Engine CLI／SDK、Cloud Run、カスタムデプロイ）を確認するには、https://adk.dev/integrations/cloud-trace/index.md を取得してください。

プロンプト／レスポンスのログ記録

GenAI のやり取り（モデル名、トークン、タイミング）を記録し、GCS（JSONL）、BigQuery（外部テーブル）、Cloud Logging（専用バケット）にエクスポートします。デフォルトではプライバシーを保護するため、明示的に設定を変更しない限りメタデータのみが記録されます。

主な環境変数：OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT — NO_CONTENT（メタデータのみ。デプロイ環境でのデフォルト）、true（全コンテンツ）、または false（無効）を設定します。LOGS_BUCKET_NAME が設定されていない場合、ローカルではログ記録は無効です。

スキャフォールド済みプロジェクトの詳細（Terraform リソース、環境変数、プライバシーモード、有効化／無効化、検証コマンド）については、references/cloud-trace-and-logging.md をご覧ください。

ADK のログ記録に関するドキュメント（ログレベル、設定、デバッグ）を確認するには、https://adk.dev/observability/logging/index.md を取得してください。

BigQuery Agent Analytics プラグイン

構造化されたエージェントイベントを BigQuery に記録するオプションのプラグインです。スキャフォールド時に --bq-analytics を指定して有効にしてください。詳細については、references/bigquery-agent-analytics.md をご覧ください。

サードパーティ連携

ADK は複数のサードパーティ製オブザーバビリティプラットフォームに対応しています。それぞれ OpenTelemetry またはカスタム計装を使用して、エージェントの動作を記録します。

プラットフォーム主な差別化要因セットアップの複雑さセルフホストの選択肢
AgentOpsセッションリプレイ、2 行でセットアップ、ネイティブテレメトリを置き換え最小限なし（SaaS）
Arize AX商用プラットフォーム、本番環境のモニタリング、評価ダッシュボード低なし（SaaS）
Phoenixオープンソース、カスタム評価器、実験テスト低あり
MLflowOTel トレースを MLflow Tracking Server に送信、スパンツリーの可視化中（SQL バックエンドが必要）あり
Monocle1 回の呼び出しでセットアップ、VS Code のガントチャートビジュアライザー最小限あり（ローカルファイル）
WeaveW&B プラットフォーム、チームコラボレーション、タイムライン表示低なし（SaaS）
Freeplayプロンプト管理、評価、オブザーバビリティを 1 つのプラットフォームに集約低なし（SaaS）

ユーザーに希望するプラットフォームを尋ね、各選択肢のトレードオフを示して選んでもらいます。セットアップの詳細については、以下の詳細情報テーブルから該当する ADK ドキュメントページを取得してください。

トラブルシューティング

問題解決策
Cloud Trace にトレースが表示されないFastAPI アプリで otel_to_cloud=True が設定されていることを確認します。サービスアカウントに cloudtrace.agent ロールがあることを確認します
プロンプトと応答のデータが表示されないLOGS_BUCKET_NAME が設定されていることを確認します。バケットに対する SA の権限として storage.objectCreator が付与されていることを確認します。テレメトリのセットアップに関する警告がないか、アプリのログを確認します
プライバシーモードの設定が正しくないOTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT の値を確認します。メタデータのみを記録する場合は NO_CONTENT を使用し、無効にする場合は false を使用します
BigQuery Analytics のログが記録されないapp/agent.py でプラグインが設定されていることを確認します。BQ_ANALYTICS_DATASET_ID 環境変数が設定されていることを確認します
サードパーティ連携でスパンが記録されないプロバイダー固有の環境変数（API キー、エンドポイント）を確認します。一部のプロバイダー（AgentOps）はネイティブテレメトリを置き換えます
トレースにツールのスパンがないツール実行のスパンは execute_tool の下に表示されます。トレースエクスプローラーのフィルターを確認します
テレメトリのコストが高いNO_CONTENT モードに切り替えます。BigQuery の保持期間を短縮します。使用していない階層を無効にします

詳細情報：ADK ドキュメント（WebFetch URL）

このスキルで扱う内容を超える詳細なドキュメントについては、以下のページを取得してください。

トピックURL
オブザーバビリティの概要https://adk.dev/observability/index.md
エージェントのアクティビティログhttps://adk.dev/observability/logging/index.md
Cloud Trace 連携https://adk.dev/integrations/cloud-trace/index.md
BigQuery Agent Analyticshttps://adk.dev/integrations/bigquery-agent-analytics/index.md
AgentOpshttps://adk.dev/integrations/agentops/index.md
Arize AXhttps://adk.dev/integrations/arize-ax/index.md
Phoenix（Arize）https://adk.dev/integrations/phoenix/index.md
MLflow トレーシングhttps://adk.dev/integrations/mlflow/index.md
Monoclehttps://adk.dev/integrations/monocle/index.md
W&B Weavehttps://adk.dev/integrations/weave/index.md
Freeplayhttps://adk.dev/integrations/freeplay/index.md

コメント

Markdown 対応