google-agents-cli-observability

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

Cloud Trace はそのまま使え、インフラストラクチャは不要です。プロンプトとレスポンスのロギングおよび BigQuery Agent Analytics には、Terraform でプロビジョニングされたインフラストラクチャ（サービスアカウント、GCS バケット、BigQuery データセット）が必要です。agents-cli infra single-project --apply --project PROJECT_ID を実行して、これらのリソースをプロビジョニングしてください。Go プロジェクトでも BigQuery テレメトリースタックが利用できますが、プロンプトとレスポンスのロギングで使用する GCS への完了データのアップロードと BigQuery Agent Analytics プラグインは Python のみ対応です。詳細、環境変数、検証コマンドについては、references/cloud-trace-and-logging.md を参照してください。プロジェクトをまだスキャフォールディングしていない場合は、先に /google-agents-cli-scaffold を参照してください。

デプロイの順序

Terraform で管理されたオブザーバビリティを使用しますか？	アクション
いいえ	agents-cli deploy を直接実行します（すべてのターゲットで動作します）。
はい	先に agents-cli infra single-project --apply を実行し、その後 agents-cli deploy を実行します。

すでに agents-cli deploy を命令的に実行している場合： その後で Terraform を適用しないでください。Gemini platform の Agent Runtime では、Terraform がエンジン全体（サービスアカウント、デプロイ仕様、環境変数）を管理するため、リソースの管理を引き継がない限り、後から適用しても整合性を保てません。 デプロイを削除して最初からやり直すか、SDK でデプロイしたインスタンスをそのまま使用してください。その場合は infra single-project をスキップし、agents-cli deploy --update-env-vars "KEY=VALUE,..." を再実行してオブザーバビリティ環境変数を設定します。デプロイでは、表示名で既存の Reasoning Engine を照合してその場で更新するため、デプロイ以外で設定した環境変数は保持されます。また、Terraform モジュールがプロビジョニングするはずのテレメトリー IAM ロールも、そのサービスアカウントに付与する必要があります。ロールは roles/storage.admin（ログバケットへの完了データの書き込み）、roles/logging.logWriter、roles/cloudtrace.agent に加え、--bq-analytics を指定してスキャフォールディングした場合は roles/bigquery.dataOwner と roles/bigquery.jobUser です。すべてのロールは deployment/terraform/single-project/iam.tf（app_sa_roles 内）と telemetry.tf にあります。このモードでは Terraform 管理の環境変数は利用できません。

リファレンスファイル

ファイル	内容
references/cloud-trace-and-logging.md	スキャフォールディングしたプロジェクトの詳細 — Terraform でプロビジョニングされたリソース、環境変数、検証コマンド、ローカルでの有効化／無効化
references/bigquery-agent-analytics.md	BQ Agent Analytics プラグイン — 有効化、主な機能、GCS へのオフロード、ツールのプロヴェナンス
references/adk-docs.md	ADK： このスキルの詳細を確認するために取得する adk.dev のページ
references/feedback-mechanism.md	ユーザーフィードバック用エンドポイントの追加 — リクエストモデル、構造化ロギング、ログシンク → BigQuery

---

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

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

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

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

---

クラウドトレース

スキャフォールディングされたエージェントは、OpenTelemetry を使用して分散トレースを出力します。エージェントを呼び出すたびにスパンが生成され、実行フロー全体を追跡できます。

スパン階層

ADK プロジェクト。 これらは ADK のスパン名です。他のフレームワークでは、それぞれ独自のスパン名が出力されます（generate_content はどちらの場合も共通の google-genai インストルメンターによって生成されます）。

invoke_workflow (top-level run)
  └── invoke_agent (one per agent in the chain)
        ├── call_llm (model request)
        │     └── generate_content (underlying GenAI model call)
        └── execute_tool (tool execution)

デプロイの種類ごとのセットアップ

デプロイ	セットアップ
Agent Runtime	自動 — 起動時にエクスポーターが接続されます。GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY（デプロイ時に設定）に応じて有効になり、Cloud Trace／Logging と Google Cloud コンソールの Agent Runtime ページにエクスポートされます
Cloud Run／GKE（スキャフォールディング済み）	自動 — 起動時にエクスポーターが接続され、Cloud Trace／Logging にエクスポートされます
Cloud Run／GKE（手動）	アプリで OpenTelemetry エクスポーターを設定します
ローカル開発	agents-cli playground で動作し、トレースは Cloud Console に表示されます

アプリの起動時に接続されます — ADK Python： app/fast_api_app.py の get_fast_api_app(otel_to_cloud=True)、ADK Go： observability.go の setupObservability()。その他のテンプレートではそれぞれ独自の方法で接続します。詳細は references/cloud-trace-and-logging.md を参照してください。

トレースを表示するには、Cloud Console → Trace → Trace explorer に移動します。

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

---

プロンプトと応答のログ記録

GenAI のやり取りをキャプチャし、GCS（JSONL）と BigQuery（ログシンクおよび外部テーブル経由）にエクスポートします。内容は独立した 2 つの階層によって制御されます。Terraform でデプロイした場合の実質的なデフォルトは、GCS／BigQuery には全コンテンツを含め、トレースには含めない設定です。

階層	キャプチャ対象	制御方法	デフォルト（Terraform デプロイ）
GCS／BigQuery の補完	プロンプトと応答の全内容（プロンプトと応答のログ記録機能）	OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK=upload + LOGS_BUCKET_NAME	有効 — 全コンテンツ
トレーススパン／Cloud Logging イベント	スパン／イベントの内容	OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT（および ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS=false、ADK Python のみ）	無効 — NO_CONTENT

この 2 つの階層は独立しています。アップロード用の環境変数が設定されていれば、GCS／BigQuery へのアップロードでは常に全コンテンツがキャプチャされ、トレース／イベント階層のみを制御する OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT の設定は適用されません。

ADK Python では、この値は experimental-semconv の列挙型として読み取られます。

• NO_CONTENT — スパン／イベントにコンテンツを含めません（スキャフォールディング時のデフォルト）
• EVENT_ONLY — Cloud Logging イベントにコンテンツを含めます
• SPAN_ONLY／SPAN_AND_EVENT — トレーススパンにコンテンツを含めます
• true／false — 無効。NO_CONTENT にフォールバックします

ADK Go では、同じ環境変数をブール値として読み取ります。"1" または "true" の場合はコンテンツをキャプチャし、それ以外の値（上記の列挙型の値を含む）の場合はコンテンツを除外します。

仕組みの詳細（semconv のオプトイン、宣言型 Terraform 設定、環境変数の一覧、有効化／無効化、確認コマンド）については、references/cloud-trace-and-logging.md を参照してください。ADK のログ記録ドキュメント（ログレベル、設定、デバッグ）については、https://adk.dev/observability/logging/index.md を取得してください。

---

BigQuery Agent Analytics プラグイン

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

---

サードパーティ連携

多くのサードパーティ製オブザーバビリティプラットフォームでは、エージェントのテレメトリを（OpenTelemetry またはカスタム計装を介して）取り込めます。以下の表では、一般的なものを紹介しています。全リストはさらに多くあります（下記のリンク先を参照してください）。

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

ユーザーに希望するプラットフォームを尋ね、トレードオフを提示して選んでもらいます。ADK： https://adk.dev/integrations/<slug>/index.md からプラットフォームのセットアップページを取得します（上の表のスラッグ：agentops、arize-ax、phoenix、mlflow-tracing、monocle、weave、freeplay）。ADK にはさらに多くのオブザーバビリティ連携（Datadog、Galileo、LangWatch、Latitude、Future AGI、Respan、Zespan、…）があります。最新の全リストは https://adk.dev/integrations/（observability トピック）で確認してください。他のフレームワークでも OpenTelemetry ベースのプラットフォームは引き続き動作しますが、各プラットフォームのセットアップドキュメントに従ってください。

---

トラブルシューティング

問題	解決策
Cloud Trace にトレースがない	テレメトリのセットアップが起動時に実行されることと、SA に cloudtrace.agent ロールがあることを確認します。ADK Python： fast_api_app.py では get_fast_api_app(otel_to_cloud=True) を使用します。ADK Go： observability.go でエクスポーターを手動でビルドします。Agent Runtime ではさらに、GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY によって制御されます。
プロンプトと応答のデータが表示されない	LOGS_BUCKET_NAME が設定されていることを確認します。SA にバケットの storage.objectCreator があることを確認し、テレメトリのセットアップに関する警告がないかアプリのログを確認します
トレース／イベントにコンテンツが含まれる（望ましくない場合）	ADK Python： OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=NO_CONTENT を設定すると、コンテンツがスパン／イベントに含まれなくなります。ADK Go： 1／true 以外の値を指定すると同様にコンテンツが除外されるため、設定を解除するか false を設定します。注意：GCS／BigQuery の補完では引き続き全コンテンツが記録されます。これを停止するには、LOGS_BUCKET_NAME／OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK を削除します（service.tf のアップロードブロックを削除します）。
BigQuery Analytics のログが記録されない	ADK Python： プラグインが app/agent.py で設定されていることを確認し、BQ_ANALYTICS_DATASET_ID 環境変数が設定されていることを確認します
サードパーティ連携でスパンが取得されない	プロバイダー固有の環境変数（API キー、エンドポイント）を確認します。一部のプロバイダー（AgentOps）はネイティブテレメトリを置き換えます
トレースにツールのスパンがない	ADK： ツール実行のスパンは execute_tool の下に表示されます（他のフレームワークでは独自のスパン名を使用します）。トレースエクスプローラーのフィルターを確認します
テレメトリのコストが高い	コンテンツの取得をオフにします（Python では NO_CONTENT、Go では false）。BigQuery の保持期間を短縮し、使用していない階層を無効にします

---

関連スキル

• /google-agents-cli-deploy — デプロイ先、CI/CD パイプライン、本番環境のワークフロー
• /google-agents-cli-workflow — 開発ワークフロー、コーディングガイドライン、運用ルール
• /google-agents-cli-adk-code — エージェントコード作成に役立つ ADK API クイックリファレンス（Python と Go）