ag2-telemetry

テレメトリー — OpenTelemetry 計装

使用するタイミング

ユーザーが次のことをしたい場合：

• ターン／呼び出しごとのレイテンシの内訳を確認する
• 操作全体にわたるトークン使用量を関連付ける
• トレースを Jaeger、Grafana Tempo、Datadog、Honeycomb、Langfuse などに送信する
• print 文ではなく構造化スパンを使って、遅いエージェントをエンドツーエンドでデバッグする

手早く標準出力でデバッグしたいだけの場合は、代わりに LoggingMiddleware を案内してください（ag2-middleware を参照）。

インストール

pip install "ag2[openai,tracing]"

必須です。コードを提供する前に、このインストールを実行してください。コマンドを実行できない場合は、正確な pip install コマンドを提示してください。

60 秒で試すレシピ

from opentelemetry import trace
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import SimpleSpanProcessor, ConsoleSpanExporter

from ag2 import Agent
from ag2.config import OpenAIConfig
from ag2.middleware.builtin import TelemetryMiddleware

# 1. Configure OpenTelemetry
resource = Resource.create({"service.name": "ag2-quickstart"})
tracer_provider = TracerProvider(resource=resource)
tracer_provider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))
trace.set_tracer_provider(tracer_provider)

# 2. Wire the middleware
agent = Agent(
    "assistant",
    prompt="You are a helpful assistant.",
    config=OpenAIConfig(model="gpt-4o-mini"),
    middleware=[
        TelemetryMiddleware(
            tracer_provider=tracer_provider,
            agent_name="assistant",
        ),
    ],
)

# 3. Run — spans emit automatically
import asyncio
asyncio.run(agent.ask("What is the capital of France?"))

本番環境では、ConsoleSpanExporter を OTLPSpanExporter（または使用するバックエンドのエクスポーター）に、SimpleSpanProcessor を BatchSpanProcessor に置き換えてください。

スパンの階層

各 ask() は、次の子スパンを持つルートスパンを生成します。

invoke_agent assistant
  ├── chat gpt-4o-mini              # LLM API call
  ├── execute_tool get_weather      # tool execution
  ├── chat gpt-4o-mini              # LLM call after tool result
  └── await_human_input assistant   # human-in-the-loop

スパンの種類

すべてのスパンには、ag2.span.type 属性があります。

ag2.span.type	操作名	フック
agent	invoke_agent	on_turn — ターン全体
llm	chat	on_llm_call — LLM 呼び出しごと
tool	execute_tool	on_tool_execution — ツールごと
human_input	await_human_input	on_human_input — HITL

セマンティック属性（GenAI semconv）

スパンには、標準の OpenTelemetry GenAI 属性が含まれます。

属性	スパン	説明
gen_ai.operation.name	すべて	invoke_agent / chat / execute_tool / await_human_input
gen_ai.agent.name	agent, human_input	エージェント名
gen_ai.provider.name	agent, llm	自動検出（openai、anthropic、…）
gen_ai.request.model	agent, llm	例：gpt-4o-mini
gen_ai.response.model	llm	レスポンスから解決
gen_ai.response.finish_reasons	llm	例：["stop"]、["tool_calls"]
gen_ai.usage.input_tokens	llm	プロンプトのトークン数
gen_ai.usage.output_tokens	llm	補完のトークン数
gen_ai.usage.cache_creation_input_tokens	llm	プロンプトキャッシュへの書き込み（Anthropic）
gen_ai.usage.cache_read_input_tokens	llm	プロンプトキャッシュからの読み取り（Anthropic、OpenAI、Gemini）
gen_ai.tool.name	tool	ツール関数名
gen_ai.tool.call.id	tool	ツール呼び出し ID
gen_ai.tool.type	tool	常に function

コンテンツの取得（デフォルトで有効）

デフォルトでは、メッセージの内容、ツールの引数、結果がスパンに含まれます。デバッグに便利ですが、機密データが漏えいするおそれがあります。

TelemetryMiddleware(
    tracer_provider=tracer_provider,
    agent_name="assistant",
    capture_content=False,   # omit messages, tool args, results
)

有効にすると、次の属性が追加されます。

属性	スパン	内容
gen_ai.input.messages	llm	JSON リクエストメッセージ
gen_ai.output.messages	llm	JSON レスポンスメッセージ
gen_ai.tool.call.arguments	tool	ツールの引数（JSON）
gen_ai.tool.call.result	tool	ツールの結果
ag2.human_input.prompt	human_input	人間に表示されたプロンプト
ag2.human_input.response	human_input	人間の応答

プライバシーに配慮が必要なバックエンド（または、テレメトリーが自社のインフラ外に送信される環境）では、capture_content=False を設定してください。

コンストラクターのリファレンス

パラメーター	型	デフォルト	説明
tracer_provider	TracerProvider | None	グローバルプロバイダー	OpenTelemetry TracerProvider
capture_content	bool	True	メッセージ／ツールの内容をスパンに含める
agent_name	str | None	"unknown"	スパン属性に使用するエージェント名
provider_name	str | None	None	プロバイダーの上書き（未設定の場合は自動検出）
model_name	str | None	None	モデルの上書き（未設定の場合は自動検出）

バックエンド連携

TelemetryMiddleware は標準の OpenTelemetry を使用するため、OTLP 互換のバックエンドであれば利用できます。

• Jaeger — OTLPSpanExporter(endpoint="http://localhost:4318/v1/traces")
• Grafana Tempo — 同じ OTLP エクスポーターを使い、Tempo のゲートウェイを指定します
• Langfuse、Honeycomb、Datadog — ベンダー固有のエクスポーターを使用します。エージェント側のセットアップは同じです

コンテナーでオーケストレーションされたスタック向けに、このリポジトリには otel-collector と Grafana Tempo 用の Docker Compose 設定を含む tracing/ ディレクトリがあります。

詳しく見る

• website/docs/user-guide/telemetry.mdx — 属性の全一覧、設定、サンプルです。
• tracing/ — ローカルの otel-collector、Tempo、Grafana 用の Docker セットアップです。
• ログ、リトライ、履歴の上限など、関連するミドルウェアについては ag2-middleware を参照してください。

よくある落とし穴

• 本番環境での SimpleSpanProcessor + ConsoleSpanExporter の使用 — 同期処理のため、スパンを出力するたびに処理がブロックされます。開発環境以外では、BatchSpanProcessor と実際のエクスポーター（OTLP／Jaeger／ベンダー）を使用してください。
• テレメトリーへのコンテンツ漏えい — デフォルトでは capture_content=True です。プライバシーに配慮が必要なプロンプト（PII、認証情報）では、capture_content=False を設定し、バックエンドに保持されるデータも監査してください。
• trace.set_tracer_provider(...) の設定忘れ — 設定しなくても、ミドルウェアに渡した tracer_provider は問題なく使用できますが、自動計装するサードパーティライブラリは別のプロバイダーを使用する可能性があります。
• トークン使用量が取得できない — gen_ai.usage.* の取得には、プロバイダークライアントがレスポンスに使用量を含める必要があります。ストリーミングプロバイダーでは、使用量が最後にのみ出力されることがあります。確認できない場合は、プロバイダーのレスポンス形式を確認してください。
• スパン階層に親子関係が表示されない — エクスポーターまたはバックエンドで、OTLP/gRPC だけでなく OTLP/HTTP パスも有効にする必要がある場合があります。両方を確認してください。
• AG2 Classic のトレーシングドキュメントとの比較 — セマンティック属性の形式は同じですが、エージェントの計装方法が異なります（AG2 Classic では instrument_agent()／instrument_llm_wrapper()／instrument_pattern() を使用し、AG2 では TelemetryMiddleware を使用します）。