Google Cloud へのテレメトリ

gcp の adk-telemetry 機能は、トレースを Google Cloud Observability（Cloud Trace）に直接エクスポートし、構造化された JSON ログを書き込みます。Cloud Logging はこれをネイティブに解析し、重大度、メッセージ、トレース相関情報も含まれます。

機能を有効にする

[dependencies]
adk-telemetry = { version = "2.1.0", features = ["gcp"] }

または、アンブレラクレートを通じて有効にします（gcp-telemetry は gemini-agent-platform メタ機能にも含まれています）。

[dependencies]
adk-rust = { version = "2.1.0", features = ["minimal", "gcp-telemetry"] }

Google Cloud への直接エクスポート

init_with_gcp は gRPC 経由で https://telemetry.googleapis.com にスパンをエクスポートし、Application Default Credentials（ADC）から発行された Bearer トークンと x-goog-user-project ヘッダーを使用して各リクエストを認証します。バックグラウンドタスクは 5 分ごとにトークンを再発行するため、長時間稼働するエージェントでもトークンの有効期限が切れた後もエクスポートを継続できます。

use adk_telemetry::init_with_gcp;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Requires GOOGLE_CLOUD_PROJECT and Application Default Credentials.
    init_with_gcp("my-agent").await?;

    // Your agent code here

    adk_telemetry::shutdown_telemetry();
    Ok(())
}

要件:

注: この経路はトレースのみをエクスポートします。メトリクスは以下のコレクターサイドカー経由でルーティングしてください。

GCP リソース検出

init_with_gcp は、デプロイされたコンテナ内でプラットフォームが設定する環境変数から OpenTelemetry リソース属性を導出します。

GOOGLE_CLOUD_AGENT_ENGINE_ID は、Vertex AI Agent Engine がデプロイ済みコンテナに設定する単なる数値のエンジン ID です。gcp.agent_engine は、OpenTelemetry セマンティック規約における正規の cloud.platform 値です（2025 年 10 月に upstream に追加）。

同じ検出機能を単独でも利用できるため、独自のパイプラインを構成できます。

use adk_telemetry::gcp_resource_attributes;

let attributes = gcp_resource_attributes("my-agent");

Cloud Logging 向けの構造化 JSON ロギング

init_json_logging は、1 行ごとに 1 つの JSON オブジェクトを標準出力に書き込むため、Cloud Logging は不透明なテキストペイロードとして表示するのではなく、重大度とトレースフィールドを解析します。init_with_gcp は同じ形式を自動的にインストールします。

use adk_telemetry::init_json_logging;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    init_json_logging()?;

    tracing::info!(user.id = "u1", "request handled");
    Ok(())
}

出力されるフィールド：

トレース相関フィールドには、同じサブスクライバー内に OpenTelemetry レイヤーと GOOGLE_CLOUD_PROJECT が必要です。init_with_gcp はその両方を提供するため、ログエントリが Cloud Trace パネルにインラインで表示されます。

代替策: OTLP から Collector Sidecar へ

直接 API にアクセスできない場合、またはメトリクスも必要な場合は、OpenTelemetry Collector をサイドカーとして実行し、標準の OTLP エクスポーターをそこに接続します。

use adk_telemetry::init_with_otlp;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    init_with_otlp("my-agent", "http://localhost:4317")?;

    // Your agent code here

    adk_telemetry::shutdown_telemetry();
    Ok(())
}

Google Cloud に転送する Collector 設定（otel-collector-config.yaml。contrib ディストリビューションの googlecloud exporter を使用）:

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317

processors:
  batch:
    send_batch_size: 200
    timeout: 5s
  resourcedetection:
    detectors: [env, gcp]

exporters:
  googlecloud:
    project: my-project

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [resourcedetection, batch]
      exporters: [googlecloud]
    metrics:
      receivers: [otlp]
      processors: [resourcedetection, batch]
      exporters: [googlecloud]

開発用にローカルで実行します。

docker run --rm -p 4317:4317 \
  -v ./otel-collector-config.yaml:/etc/otelcol-contrib/config.yaml \
  -v ~/.config/gcloud:/root/.config/gcloud \
  otel/opentelemetry-collector-contrib:latest

パスの選択

関連

• テレメトリ - コアテレメトリの設定とスパンヘルパー
• デプロイメント - 本番環境のテレメトリ設定