テレメトリー

ADK-Rust は、tracing エコシステムと OpenTelemetry を使用して構造化ロギングと分散トレーシングを統合する adk-telemetry クレートを通じて、プロダクションレベルの可観測性を提供します。

概要

テレメトリーシステムは以下を可能にします。

Structured Logging: コンテキスト情報を含むリッチでクエリ可能なログ
Distributed Tracing: エージェント階層とサービス境界を越えたリクエストの追跡
OpenTelemetry Integration: 可観測性バックエンド (Jaeger, Datadog, Honeycomb など) へのトレースのエクスポート
Automatic Context Propagation: セッション、ユーザー、および呼び出し ID がすべての操作を通じて流れる
Pre-configured Spans: 一般的な ADK 操作のためのヘルパー関数

クイックスタート

基本的なコンソールロギング

開発およびシンプルなデプロイメントの場合、コンソールロギングを初期化します。

use adk_telemetry::init_telemetry;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize telemetry with your service name
    init_telemetry("my-agent-service")?;
    
    // Your agent code here
    
    Ok(())
}

これは、適切なデフォルト設定で構造化ロギングを標準出力に構成します。

OpenTelemetry エクスポート

分散トレーシングを伴うプロダクションデプロイメントの場合：

use adk_telemetry::init_with_otlp;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize with OTLP exporter
    init_with_otlp("my-agent-service", "http://localhost:4317")?;
    
    // Your agent code here
    
    // Flush traces before exit
    adk_telemetry::shutdown_telemetry();
    Ok(())
}

これは、トレースとメトリクスを OpenTelemetry コレクターエンドポイントにエクスポートします。

コンポーザブルレイヤー (上級)

すでに tracing サブスクライバーが構成されている場合は、グローバルサブスクライバーを初期化する代わりに、build_otlp_layer を使用してコンポーザブルレイヤーを取得します。

use adk_telemetry::build_otlp_layer;
use tracing_subscriber::{layer::SubscriberExt, util::SubscriberInitExt};

let otlp_layer = build_otlp_layer("my-agent", "http://localhost:4317")?;

tracing_subscriber::registry()
    .with(otlp_layer)
    .with(tracing_subscriber::fmt::layer())
    .init();

ログレベル

RUST_LOG 環境変数を使用してロギングの冗長性を制御します。

レベル	説明	ユースケース
`error`	エラーのみ	本番環境 (最小限)
`warn`	警告とエラー	本番環境 (デフォルト)
`info`	情報メッセージ	開発、ステージング
`debug`	詳細なデバッグ情報	ローカル開発
`trace`	非常に詳細なトレース	詳細なデバッグ

ログレベルの設定

# Set global log level
export RUST_LOG=info

# Set per-module log levels
export RUST_LOG=adk_agent=debug,adk_model=info

# Combine global and module-specific levels
export RUST_LOG=warn,adk_agent=debug

テレメトリーシステムは、RUST_LOGが設定されていない場合、デフォルトでinfoレベルになります。

ロギングマクロ

ロギングには標準のtracingマクロを使用します:

use adk_telemetry::{trace, debug, info, warn, error};

// Informational logging
info!("Agent started successfully");

// Structured logging with fields
info!(
    agent.name = "my_agent",
    session.id = "sess-123",
    "Processing user request"
);

// Debug logging
debug!(user_input = ?input, "Received input");

// Warning and error logging
warn!("Rate limit approaching");
error!(error = ?err, "Failed to call model");

構造化フィールド

より良いフィルタリングと分析のために、ログメッセージにコンテキストフィールドを追加します:

use adk_telemetry::info;

info!(
    agent.name = "customer_support",
    user.id = "user-456",
    session.id = "sess-789",
    invocation.id = "inv-abc",
    "Agent execution started"
);

これらのフィールドは、オブザーバビリティバックエンドでクエリ可能になります。

インストルメンテーション

自動インストルメンテーション

関数にスパンを自動的に作成するには、#[instrument]属性を使用します:

use adk_telemetry::{instrument, info};

#[instrument]
async fn process_request(user_id: &str, message: &str) {
    info!("Processing request");
    // Function logic here
}

// Creates a span named "process_request" with user_id and message as fields

機密パラメーターのスキップ

トレースから機密データを除外します:

use adk_telemetry::instrument;

#[instrument(skip(api_key))]
async fn call_external_api(api_key: &str, query: &str) {
    // api_key won't appear in traces
}

カスタムスパン名

use adk_telemetry::instrument;

#[instrument(name = "external_api_call")]
async fn fetch_data(url: &str) {
    // Span will be named "external_api_call" instead of "fetch_data"
}

事前設定されたスパン

ADK-Telemetryは、一般的な操作のためのヘルパー関数を提供します:

Agent実行スパン

use adk_telemetry::agent_run_span;

let span = agent_run_span("my_agent", "inv-123");
let _enter = span.enter();

// Agent execution code here
// All logs within this scope inherit the span context

モデル呼び出しスパン

use adk_telemetry::model_call_span;

let span = model_call_span("gemini-2.5-flash");
let _enter = span.enter();

// Model API call here

ツール実行スパン

use adk_telemetry::tool_execute_span;

let span = tool_execute_span("weather_tool");
let _enter = span.enter();

// Tool execution code here

コールバックスパン

use adk_telemetry::callback_span;

let span = callback_span("before_model");
let _enter = span.enter();

// Callback logic here

コンテキスト属性の追加

現在のスパンにユーザーとセッションのコンテキストを追加します:

use adk_telemetry::add_context_attributes;

add_context_attributes("user-456", "sess-789");

LLMトークン使用量の追跡

すべてのLLMプロバイダーにおけるトークン消費量を、OpenTelemetry GenAIセマンティック規約に従って追跡します。llm_generate_spanは、事前に宣言されたgen_ai.usage.*フィールドを持つスパンを作成し、応答が到着した後にrecord_llm_usageがそれらを埋めます:

use adk_telemetry::{llm_generate_span, record_llm_usage, LlmUsage};

let span = llm_generate_span("openai", "gpt-5-mini", true);
let _enter = span.enter();

// After receiving the LLM response with usage metadata:
record_llm_usage(&LlmUsage {
    input_tokens: 100,
    output_tokens: 50,
    total_tokens: 150,
    cache_read_tokens: Some(80),
    ..Default::default()
});

すべてのADKモデルプロバイダー（Gemini, OpenAI, Anthropic, Ollama, Bedrock, DeepSeek, Groq, Azure AI, およびすべてのOpenAI互換プロバイダー）は、すべてのgenerate_content呼び出しでトークン使用量を自動的に記録します。手動でのインストルメンテーションは不要です — 追跡機能はプロバイダーレイヤーに組み込まれています。

記録されるスパンフィールドは、OpenTelemetry GenAI規約に従います:

フィールド	説明
`gen_ai.usage.input_tokens`	プロンプト / 入力トークン数
`gen_ai.usage.output_tokens`	完了 / 出力トークン数
`gen_ai.usage.total_tokens`	合計トークン数
`gen_ai.usage.cache_read_tokens`	プロンプトキャッシュから読み取られたトークン数
`gen_ai.usage.cache_creation_tokens`	キャッシュ作成に使用されたトークン数
`gen_ai.usage.thinking_tokens`	Chain-of-thought推論トークン
`gen_ai.usage.audio_input_tokens`	音声入力トークン数
`gen_ai.usage.audio_output_tokens`	音声出力トークン数

プロバイダーが報告した場合（非None）にのみ、オプションフィールドが記録されます。

手動スパン作成

カスタム計測の場合、スパンを手動で作成します。

use adk_telemetry::{info, Span};

let span = tracing::info_span!(
    "custom_operation",
    operation.type = "data_processing",
    operation.id = "op-123"
);

let _enter = span.enter();
info!("Performing custom operation");
// Operation code here

スパン属性

属性を動的に追加します。

use adk_telemetry::Span;

let span = Span::current();
span.record("result.count", 42);
span.record("result.status", "success");

OpenTelemetry設定

OTLPエンドポイント

OTLPエクスポーターはトレースをコレクターエンドポイントに送信します。

use adk_telemetry::init_with_otlp;

// Local Jaeger (default OTLP port)
init_with_otlp("my-service", "http://localhost:4317")?;

// Cloud provider endpoint
init_with_otlp("my-service", "https://otlp.example.com:4317")?;

ローカルコレクターの実行

開発用に、OTLPサポート付きでJaegerを実行します。

docker run -d --name jaeger \
  -p 4317:4317 \
  -p 16686:16686 \
  jaegertracing/all-in-one:latest

# View traces at http://localhost:16686

トレースの可視化

設定が完了すると、オブザーバビリティバックエンドにトレースが表示され、以下が示されます。

Agentの実行階層
Model呼び出しのレイテンシ
Toolの実行タイミング
エラーの伝播
コンテキストフロー（ユーザーID、セッションIDなど）

ADKとの統合

テレメトリーシステムが初期化されると、ADK-Rustコンポーネントは自動的にテレメトリーを出力します。

use adk_rust::prelude::*;
use adk_telemetry::init_telemetry;
use std::sync::Arc;

#[tokio::main]
async fn main() -> std::result::Result<(), Box<dyn std::error::Error>> {
    // Initialize telemetry first
    init_telemetry("my-agent-app")?;
    
    let api_key = std::env::var("GOOGLE_API_KEY")?;
    let model = Arc::new(GeminiModel::new(&api_key, "gemini-2.5-flash")?);
    
    let agent = LlmAgentBuilder::new("support_agent")
        .model(model)
        .instruction("You are a helpful support agent.")
        .build()?;
    
    // Use Launcher for simple execution
    Launcher::new(Arc::new(agent)).run().await?;
    
    Ok(())
}

Agent、Model、Toolの操作は、構造化されたログとトレースを自動的に出力します。