AIエージェント編集部
Claudeのエージェントのトレース(OpenTelemetry・ベータ)、既定はメタデータだけ
チュートリアル

Claudeのエージェントのトレース(OpenTelemetry・ベータ)、既定はメタデータだけ

2026-10-16 / あかりん

Claudeのリリースノートの2026年10月14日付の項目に、Messages APIのリクエストと Managed Agents のセッションのトレースを、OpenTelemetry で外部の観測ツールに書き出す機能がベータで加わったとあると伝えられている。Anthropicの解説記事は、この機能を公開ベータと表現している。リリースノート・解説記事・ドキュメントの各ページの本文は、当編集部として確認できていない。以下は、伝えられている範囲だ。

この記事は、Claude を API で本番のアプリに組み込んでいる開発者向けに、何が送られ、何が既定で、どう設定し、データがどこに残るかを順に整理する。最後に、Claude Code・Agent SDK 側の既存のテレメトリの設定との違いも並べる。

何が加わったか — 対象とスパン

対象は2つ、それに SDK が加わる。

属性は、遅延・トークン数・各種の ID で、OpenTelemetry の生成 AI 向けの規約に沿うとされる。

SDK では、登録の順番にも注意がいる。SDK は、アプリが登録した tracer provider を使う。そのため、追跡したい呼び出しのうち一番早いものより前に、tracer provider を登録しておく必要がある、とされる。

既定はメタデータだけ — 何が送られるか

既定で送られるのは、メタデータだけだ。識別子・時刻・状態・トークン数などで、プロンプトや応答の本文は含まれない。SDK の既定の値は metadata_only とされる。

本文も含めたいときは、明示的に設定する。ドキュメントにあるのは次の2つだ。

Full content にすると、システムプロンプト・入力・応答・ツールの引数と結果が、スパンの属性に入る。1スパンの内容は、既定で最大0.75MBとされる。つまり、メタデータだけの状態と比べて、送信先に運ばれる情報の性質がまるで変わる。

どちらのモードでも、会話の ID は書き出される。ドキュメントは、会話の ID に個人情報や秘密を入れないよう注意している、と伝えられている。

HIPAA・FERPA・K-12 のデータの取り扱いの制限がある組織では、API の送信先は、モードにかかわらずメタデータだけを書き出すとされる。これは API の送信先についての記述で、SDK のスパンには当てはめて読まないほうがよい。

設定の流れ

API 側 — 送信先を登録する

  1. 組織の OpenTelemetry の設定で、送信先として OTLP/HTTP のエンドポイントと認証ヘッダーを登録する。ベースの URL にはパスを含めない。Admin API でも作れる
  2. 観測ツール側で、service.name が claude-platform のものに絞って、届いているか確かめる

送信先は、OTLP を受けられるツールなら使えるとされる。ドキュメントは、Grafana Cloud・Honeycomb・Langfuse・LangSmith・Sentry・Splunk などを例に挙げている。

SDK 側 — クライアントに設定を渡す

クライアントに open_telemetry の設定を渡すと、ANTHROPIC_OPEN_TELEMETRY で始まる環境変数をまとめて上書きする、とされる。

API 側のスパンは、既定では独立したトレースになる。アプリのトレースの下に置くには、SDK のトレースを設定して、自分のスパンの中で SDK を呼ぶ、と解説記事にある。要するに、API 側が勝手に作るトレースと、アプリ側のトレースは、つなぎ方を決めない限り別々の線になる。

配信とデータの扱い

配信は、重複と欠落がありうる

配信は、少なくとも1回の配信でベストエフォートとされる。再送で同じスパンが重複して届きうるので、トレースの ID とスパンの ID で重複を除く必要がある。スパンが失われることもある、とされる。

データがどこに残るか

つまり、送ったあとの保管は、送信先のツールの設定の持ち分になる。

Claude Code・Agent SDK 側のテレメトリとの違い

Agent SDK は、Claude Code の CLI を子プロセスとして動かす。テレメトリは、その CLI が環境変数で出す、別の仕組みだ。今回のプラットフォーム側の機能とは、対象も設定の場所も違う。

Claude Code 側は、CLAUDE_CODE_ENABLE_TELEMETRY を 1 にして有効にし、送り先の種類を選ぶ必要がある。トレースは、さらにベータの別のスイッチ CLAUDE_CODE_ENHANCED_TELEMETRY_BETA を 1 にする。プロンプトの本文やツールの詳細は、既定で伏せられていて、OTEL_LOG_USER_PROMPTS と OTEL_LOG_TOOL_DETAILS で別に有効にする。管理者は、managed settings に置ける。

項目 Claude プラットフォーム側 Claude Code・Agent SDK 側
対象 Messages API のリクエスト、Managed Agents のセッション、SDK が出すスパン Claude Code の CLI(Agent SDK はこれを子プロセスとして動かす)
設定の場所 Console の送信先(API 側)と、SDK の open_telemetry の設定 環境変数(CLAUDE_CODE_ENABLE_TELEMETRY など)。管理者は managed settings
本文の扱い 既定はメタデータだけ。Full content か ANTHROPIC_OPEN_TELEMETRY_TRACES_CONTENT_MODE で本文を含める 既定で伏せられる。OTEL_LOG_USER_PROMPTS・OTEL_LOG_TOOL_DETAILS で別に有効にする
トレースを出す条件 送信先の登録(API 側)、tracer provider の登録(SDK) ベータの別のスイッチ CLAUDE_CODE_ENHANCED_TELEMETRY_BETA

Claude Code 側の OpenTelemetry は、2026年9月18日のClaude最新情報の記事(Claude Code 2.1.274でOpenTelemetryトレースにeffort属性が加わったと伝えた記事)で伝えた。Cowork の OpenTelemetry は、2026年4月11日の記事(CoworkのOpenTelemetryサポートを伝えた記事)で伝えた。

開発者が確かめること

運用に入れる前に、次の5点を確かめておくとよい。

  1. 既定はメタデータだけであること。本文を送るのは、明示的な設定をしたときだ。自分の環境がどちらのモードか、確かめておきたい
  2. 本文を送ると、送信先の保持の設定で保管されること。プロンプトや応答、ツールの引数と結果が、送信先のツールに残る前提で考えたい
  3. 会話の ID に、個人情報や秘密を入れないこと。会話の ID は、どちらのモードでも書き出される
  4. Managed Agents は、ゼロデータ保持の対象外であること。OpenTelemetry を使っても、保持の扱いは変わらないとされる
  5. ベータであること。ベータ向けのサービス規約の対象とされ、配信は重複と欠落がありうる。集計は、トレースの ID とスパンの ID で重複を除き、欠けがある前提で見ておくとよい

何が確認できていないか

まとめ

2026年10月16日のClaude最新情報の記事と、Meta、816BのMuse Spark Openの重みを公開。xAIはGrok Voice 3.0を発表もあわせて読んでほしい。

この記事で使ったツール

本記事はAIエージェントが収集・執筆した情報を含みます。内容の正確性・最新性については公式ドキュメントや一次情報源をご確認ください。