Agent SDKのOpenTelemetry設定 トレースとメトリクスを送る

Claude Code エンジニアリング 7分で読めます

Claude Agent SDKで作ったエージェントを本番で動かすと、どのツールを呼んだか、モデルの応答にどれだけ時間がかかったか、トークンをいくら使ったか、どこで失敗したかを後から追えるようにする必要があります。Agent SDKはこれらをOpenTelemetryのトレース・メトリクス・ログイベントとして、OTLPを受け付ける任意のバックエンドへ送れます。この記事では、2026年11月8日に確認した公式ドキュメント「Observability with OpenTelemetry」と「Monitoring」を基に、設定方法とデータの読み方を整理します。応答ストリームからトークン数と費用を直接読む方法はAgent SDKのコスト追跡、対話で使うClaude Code本体の設定はOpenTelemetryでClaude Codeを監視する記事で扱っています。

テレメトリがSDKから流れる仕組み

Agent SDKはClaude Code CLIを子プロセスとして起動し、ローカルのパイプで通信します。OpenTelemetryの計測はCLI側に組み込まれており、SDK自身はテレメトリを作りません。SDKは設定を環境変数としてCLIへ渡し、CLIがコレクターへ直接送ります。そのためメトリクス名やイベント名はClaude CodeのMonitoringリファレンスと同じです。

環境変数を設定できる場所は2つあります。

ここに言語差があります。Pythonのenvは継承した環境の上にマージされますが、TypeScriptのenvは継承した環境を丸ごと置き換えます。TypeScriptでは...process.envを先に展開しないとPATHやANTHROPIC_API_KEYまで失われます。

CLIが送る信号は次の3種類で、スイッチもエクスポーターも独立しているため、必要なものだけ有効にできます。

信号内容有効にする変数
メトリクストークン、費用、セッション、コード行数、ツール判定のカウンターOTEL_METRICS_EXPORTER
ログイベントプロンプト、APIリクエスト、APIエラー、ツール結果ごとの構造化レコードOTEL_LOGS_EXPORTER
トレース(ベータ)やり取り、モデルリクエスト、ツール呼び出し、フックのスパンOTEL_TRACES_EXPORTERとCLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1

環境変数でエクスポートを有効にする

テレメトリは、CLAUDE_CODE_ENABLE_TELEMETRY=1を設定し、エクスポーターを1つ以上選ぶまで動きません。次はPythonで3信号すべてをOTLP HTTPでコレクターへ送る例です。トレースだけはベータのためCLAUDE_CODE_ENHANCED_TELEMETRY_BETAも必要です。

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

OTEL_ENV = {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "CLAUDE_CODE_ENHANCED_TELEMETRY_BETA": "1",
    "OTEL_TRACES_EXPORTER": "otlp",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://collector.example.com:4318",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer your-token",
}

async def main():
    options = ClaudeAgentOptions(env=OTEL_ENV)
    async for message in query(
        prompt="List the files in this directory", options=options
    ):
        print(message)

asyncio.run(main())

TypeScriptでは同じ内容をoptions: { env: { ...process.env, ...otelEnv } }の形で渡します。Dockerfile、Kubernetesのマニフェスト、シェルのプロファイルで同じ変数を設定すれば、options.envは省略できます。Claude Codeにはプロトコルの既定値がないので、otlpを使う場合はOTEL_EXPORTER_OTLP_PROTOCOL(または信号別のプロトコル変数)を必ず指定します。

SDK特有の注意点が2つあります。

短時間の実行で取りこぼさない

CLIはテレメトリをまとめて、一定間隔で送ります。正常終了時には残りを送ろうとしますが、短いタイムアウトがあるため、コレクターの応答が遅いとスパンが失われることがあります。CLIが終了処理に入る前にプロセスが強制終了されると、バッファ内のデータは失われます。間隔を短くすると、どちらの損失も小さくできます。

変数対象既定(ミリ秒)
OTEL_METRIC_EXPORT_INTERVALメトリクス60000
OTEL_LOGS_EXPORT_INTERVALログイベント5000
OTEL_TRACES_EXPORT_INTERVALトレース5000

公式の例は3つとも"1000"にして、短いタスクの実行中にデータがコレクターへ届くようにしています。リクエストごとに短時間で終わるエージェントでは、特にメトリクスの60秒がタスクより長くなりやすいので、この設定を先に検討します。

トレースを読みアプリと結び付ける

トレースを有効にすると、エージェントループの各段階がスパンになります。

claude_code.interaction
├── claude_code.llm_request
├── claude_code.hook                    (詳細ベータトレース時のみ)
└── claude_code.tool
    ├── claude_code.tool.blocked_on_user
    ├── claude_code.tool.execution
    └── (Agent ツール) サブエージェントの llm_request / tool スパン

Agentツールで起動したサブエージェントのスパンは親のclaude_code.toolの下に入るため、委譲の全体が1本のトレースで見えます。スパンには既定でsession.id属性が付くので、同じセッションに対する複数のquery()はこの値で絞ると1本の時系列になります。トレースはベータで、スパン名や属性はリリース間で変わる可能性があります。

アプリ側でOpenTelemetryのスパンが有効な状態でquery()を呼ぶと、SDKはTRACEPARENTとTRACESTATEを子プロセスの環境へ自動で注入します。これでclaude_code.interactionがアプリのスパンの子になり、エージェントの実行が独立したトレースにならずアプリのトレースの中に現れます。実行中のOTLPログレコードにも同じtrace_idとspan_idが付くので、バックエンドでイベントとスパンを突き合わせられます。

さらにCLIはBashとPowerShellのコマンドにもTRACEPARENTを渡すため、Bashツールから起動したコマンドが自前のスパンを出せば、claude_code.tool.executionの下に並びます。options.envでTRACEPARENTを明示すると自動注入は行われず、親を固定できます。なお対話型のCLIセッションは受け取ったTRACEPARENTを無視し、従うのはAgent SDKとclaude -pの実行だけです。

タグ付けと機密データの制御

既定のservice.nameはclaude-codeです。複数のエージェントや他のサービスと同じコレクターを共有するなら、OTEL_SERVICE_NAMEとOTEL_RESOURCE_ATTRIBUTESで区別します。指定した値は、そのエージェントが出すすべてのスパン・メトリクス・イベントに付きます。

1つのデプロイで多数の利用者を扱う場合は、さらに注意が必要です。CLIが付ける識別属性はAnthropicを呼ぶ認証情報に基づくので、示されるのはサービスの認証情報であって、実際の利用者ではありません。query()ごとに利用者IDをリソース属性として渡します。OTEL_RESOURCE_ATTRIBUTESではカンマ、空白、等号が予約されているため、値はパーセントエンコードします。

from urllib.parse import quote

options = ClaudeAgentOptions(
    env={
        # ... エクスポーターの設定 ...
        "OTEL_SERVICE_NAME": "support-triage-agent",
        # request は Web フレームワークの受信リクエスト
        "OTEL_RESOURCE_ATTRIBUTES": f"enduser.id={quote(request.user_id)},tenant.id={quote(request.tenant_id)}",
    },
)

TypeScriptではencodeURIComponentを使います。利用者IDを付けると、次のイベントを利用者単位の監査証跡としてSIEMへ転送できます。ログレコードの名前にはclaude_code.が前に付きます。

既定で送られるのは所要時間、モデル名、ツール名といった構造情報で、エージェントが読み書きした内容は含まれません。トークン数はAPIが使用量を返したときだけ記録されるので、失敗や中断のスパンには無いことがあります。内容を含めるには次の変数を明示的に設定します。

変数追加されるもの
OTEL_LOG_USER_PROMPTS=1claude_code.user_promptイベントとclaude_code.interactionスパンのプロンプト本文
OTEL_LOG_TOOL_DETAILS=1ファイルパス、シェルコマンド、検索パターンなどのツール入力。コストとトークンのメトリクスには実際のエージェント名・スキル名・プラグイン名・MCPサーバー名が入る
OTEL_LOG_TOOL_CONTENT=1claude_code.toolのtool.outputスパンイベントにファイル内容やBash出力など。既定で60KBで切り詰め、トレースの有効化が必要
OTEL_LOG_RAW_API_BODIESMessages APIの要求と応答のJSON全体。1はインラインで60KBまで、file:<dir>は切り詰めずディスクへ保存

OTEL_LOG_RAW_API_BODIESには会話履歴全体が含まれ(拡張思考の内容は伏せられます)、有効にすると上の3変数が明らかにする内容すべてに同意した扱いになります。切り詰めの上限はCLAUDE_CODE_OTEL_CONTENT_MAX_LENGTHで変更できます(v2.1.214以降)。公式は、エージェントが扱うデータの保存が承認されたパイプラインでない限り、これらを未設定のままにするよう案内しています。

参照した一次情報は、Claude Code公式の「Observability with OpenTelemetry」と「Monitoring」です。Claude APIやManaged Agentsの場合は別ページの案内があります。トレースはベータのため、導入前に最新版を確認してください。