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つあります。
- プロセスの環境: シェル、コンテナ、オーケストレーターで起動前に設定します。子プロセスは既定でアプリの環境を継承するので、コード変更なしですべての
query()に効きます。本番では公式がこちらを推奨しています。 - 呼び出しごとのオプション: Pythonは
ClaudeAgentOptions.env、TypeScriptはoptions.envに書きます。同じプロセス内のエージェントごとに設定を変えたいときに使います。
ここに言語差があります。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つあります。
consoleエクスポーターは使わない: 標準出力に書き出しますが、標準出力はSDKのメッセージ通信路です。手元で中身を見たいときは、OTEL_EXPORTER_OTLP_ENDPOINTをローカルのOpenTelemetry Collectorに向けます。- 送信エラーは既定で表示されない: 宛先に届かなくてもエージェントは普通に動き、テレメトリだけが捨てられます。実行後にコレクターのログで受信を確かめるか、
CLAUDE_CODE_OTEL_DIAG_STDERR=1を設定してSDKのstderrコールバック(TypeScriptはstderrオプション)で診断を読みます。これにはClaude Code v2.1.179以降が必要です。
短時間の実行で取りこぼさない
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 スパン
claude_code.interaction: プロンプトの受信から応答までの1ターンを包みます。claude_code.llm_request: Claude APIへの各呼び出しです。モデル名、レイテンシ、トークン数が属性に入ります。claude_code.tool: ツール呼び出しごとのスパンで、権限判定の待ち時間(blocked_on_user)と実行(execution)が子スパンになります。claude_code.hook: フックの実行です。ENABLE_BETA_TRACING_DETAILED=1とBETA_TRACING_ENDPOINTが必要で、この組み合わせはログとトレースの送り先も変えます。公式はデバッグ専用とし、本番では設定しないよう案内しています。
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.が前に付きます。
tool_decisionとtool_result: 各ツール呼び出しの許可・拒否と結果safety_event: どの検査(権限ルールやAutoモードの分類器など)が拒否または確認を求めたか(v2.1.307以降。イベントが出ない呼び出しもあります)mcp_server_connection: MCPサーバーの接続と接続失敗permission_mode_changed: 権限モードの変更
既定で送られるのは所要時間、モデル名、ツール名といった構造情報で、エージェントが読み書きした内容は含まれません。トークン数はAPIが使用量を返したときだけ記録されるので、失敗や中断のスパンには無いことがあります。内容を含めるには次の変数を明示的に設定します。
| 変数 | 追加されるもの |
|---|---|
OTEL_LOG_USER_PROMPTS=1 | claude_code.user_promptイベントとclaude_code.interactionスパンのプロンプト本文 |
OTEL_LOG_TOOL_DETAILS=1 | ファイルパス、シェルコマンド、検索パターンなどのツール入力。コストとトークンのメトリクスには実際のエージェント名・スキル名・プラグイン名・MCPサーバー名が入る |
OTEL_LOG_TOOL_CONTENT=1 | claude_code.toolのtool.outputスパンイベントにファイル内容やBash出力など。既定で60KBで切り詰め、トレースの有効化が必要 |
OTEL_LOG_RAW_API_BODIES | Messages 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の場合は別ページの案内があります。トレースはベータのため、導入前に最新版を確認してください。