Claude API の OpenTelemetry 連携が beta で始まった
Anthropic は 2026 年 10 月 14 日付のAPI リリースノートで、OpenTelemetry のエクスポートを beta として公開しました。Messages API のリクエストと Claude Managed Agents のセッションを、すでに使っている監視基盤でトレースできます。SDK は Python・TypeScript・C#・Go・Java・PHP・Ruby の 7 言語でスパンを出し、API 側のスパンは Claude Console で送信先を足して受け取ります。
LLM の呼び出しは、遅い・失敗する・トークンを使いすぎる、のどれかが起きたときに、アプリ側の処理とモデル側の処理のどちらが原因かを切り分けにくい箇所です。運用を担当する立場では、この切り分けを既存のトレースの中でできるかどうかが気になります。
本記事は、公式の概要ページ、SDK の設定ページ、API の設定ページを 2026 年 10 月 15 日に確認した内容だけで書いています。公式の表記は beta です。確認できなかった項目は、できないとは書かずに「記載が無い」と書きます。Claude Code の監視は別のドキュメントに分かれているので、ここでは扱いません。
SDK トレースと API トレースの違い
設定の方式は 2 つあり、片方だけでも、両方でも使えます。公式の比較表を、本記事の読み方に合わせてまとめます。
| 観点 | SDK トレース | API トレース |
|---|---|---|
| 設定する場所 | アプリのコード | Claude Console |
| 必要な権限 | なし | Console の admin ロール |
| 対象のクライアント | SDK を使うクライアント | どのクライアントでも |
| Messages API・Sessions API のリクエスト | 取れる | 取れる |
| トークン使用量 | 取れる | 取れる |
| リクエスト内のモデル実行ごとのスパン | 取れない | 取れる |
| Managed Agents のターン | 取れない | 取れる |
| API が実行するサーバーツール | 取れない | 取れる |
| tool runner が実行するクライアントツール | 取れる | 取れない |
| ファイルのアップロードなど他の API | 取れる | 取れない |
| 対応するプラットフォーム | どの提供経路でも | Claude Platform と Claude Platform on AWS |
両方を設定すると、1 つのリクエストの SDK のスパンと API のスパンが 1 本のトレースにまとまります。ただし Claude Platform on AWS へのリクエストでは、API のスパンは別のトレースになります。
FIXIT結局、どっちから入れればいいの？
Kaname権限が要らない SDK 側が先です。モデル実行やサーバーツールの中身まで見たくなったら、管理者に API 側を頼みます。
FIXITSDK を使ってないクライアントは？
Kanameその場合は API 側だけが選択肢です。公式の表でも、API トレースは「どのクライアントでも」になっています。
SDK 側の設定
SDK 側の手順は、公式では 4 段階です。
- SDK を最新版にする。Java は
anthropic-javaの 2.72.0 以上を指定します - OpenTelemetry の tracer provider を、最初の呼び出しより前に登録する
- exporter を、監視基盤の OTLP の送信先に向ける
- 必要ならオプションで、content mode や会話 ID を設定する
SDK は、アプリが登録した tracer provider を使います。そのため、SDK を呼ぶコードは変わりません。公式の Python の例は、スパンをコンソールに出す exporter を登録して、1 回呼び出すものです。
from anthropic import Anthropic
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor
provider = TracerProvider()
provider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))
trace.set_tracer_provider(provider)
client = Anthropic()
message = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello, Claude"}],
)コンソールに anthropic.messages.create のスパンが 1 つ出れば、SDK 側の準備は済みです。そのあと、コンソールの exporter を、監視基盤向けの OTLP exporter に差し替えます。言語ごとの exporter の設定は、公式が OpenTelemetry の各言語のドキュメントを案内しています。
主なオプションは次のとおりです。
| オプション | 用途 | 既定 |
|---|---|---|
traces.content_mode | プロンプトと応答をスパンに含める (content) | metadata_only |
traces.max_content_bytes | スパンごとの内容の上限を変える | 0.75 MB |
conversation_id | 複数の呼び出しを 1 つの会話にまとめる | なし |
open_telemetry を false にする | 1 つのクライアントでスパンを止める | 有効 |
会話 ID は gen_ai.conversation.id に書き込まれ、どちらの content mode でも送信先に出ます。個人情報や秘密を入れないでください。環境変数で設定する場合は ANTHROPIC_OPEN_TELEMETRY_TRACES_CONTENT_MODE=content のように指定します。クライアントに open_telemetry を渡すと、その項目の環境変数は丸ごと上書きされ、書かなかった入れ子の項目は、環境変数が設定されていても既定値に戻ります。
ストリームのスパンは、コードがストリームを最後まで読むか閉じた時点で終わります。途中でやめるときは、ストリームを閉じてください。
Console で API トレースの送信先を足す
API 側は、Console に送信先 (destination) を登録します。送信先は、監視基盤の OTLP のエンドポイントと認証の情報です。
事前に必要なものは 3 つです。
- Claude Console の組織の admin ロール。developer ロールでは、送信先を見るだけです
- HTTPS の 443 番ポートで、protobuf の OTLP/HTTP を受け付けるエンドポイント。自前の OpenTelemetry Collector は、OTLP/HTTP の受信口が既定で 4318 番ポートなので、443 番で HTTPS を受けるように設定するか、ロードバランサーやリバースプロキシを前に置きます
- エンドポイントの認証情報 (API キーなど)
手順は、Console のOpenTelemetry の設定ページで「Add destination」を押し、次の項目を入れます。
| 項目 | 入れる内容 |
|---|---|
| Provider | 監視基盤。一覧に無ければ Custom |
| OTLP endpoint URL | OTLP/HTTP のベース URL。ホスト名で指定し、/v1/traces は API が付けるので書かない |
| Request headers | 認証のヘッダー。保存後、Console は値を再表示しない |
| Content mode | Metadata only か Full content |
| Workspaces | All・Selected・All except のいずれか。スパンを受け取るワークスペースを決める |
保存したら、送信先の「More actions」メニューから「Test」を実行し、監視基盤に anthropic.test のスパンが届いたか確認します。実際のリクエストを送ったあと、「Delivery」の列が「Healthy」になるまで 1 分ほどかかります。監視基盤側では、service.name が claude-platform のスパンが目印です。Console のかわりに、Admin API や CLI でも送信先を登録できます。
アプリのトレースとつなぐには、SDK 側の設定も入れたうえで、自分のスパンの内側で SDK を呼びます。SDK は W3C の traceparent ヘッダーを付け、API はそれを読んでスパンを同じトレースに入れます。traceparent の sampled フラグが off のリクエストは、API のスパンが出ません。
配信と上限について、公式が書いている内容は次のとおりです。
- 配信は at least once で、同じスパンが複数回届くことがある。重複はトレース ID とスパン ID で取り除く
- 配信は best effort で、スパンが失われることがある。失われたスパンは再送されない
- 送信先は組織ごとに 10 件まで。無効のものも数える
- 送信先の応答は、TLS ハンドシェイクもレスポンスヘッダーも 5 秒以内、1 回の配信は合計 10 秒で打ち切られる
- 送信先がリダイレクト (3xx) を返す、ホスト名が公開されていない IP に解決される、24 時間すべて失敗する、のいずれかで API は送信先を無効にする
content mode の選び方
content mode は、スパンにプロンプトと応答を含めるかを決める設定です。送信先ごと、SDK のクライアントごとに選びます。
| モード | SDK での値 | スパンの内容 |
|---|---|---|
| Metadata only | metadata_only | 識別子・時間・ステータス・トークン数と、エージェントやツールの名前・説明、MCP サーバーの名前 |
| Full content | content | 上記に加えて、モデルへのプロンプトと応答 |
既定は Metadata only です。Full content にすると、失敗や遅延の理由を会話の中身から読めて、実際のトラフィックから評価用のデータも作れます。ただし、内容は監視基盤が自分のアクセス制御と保持期間で持つので、組織の要件に合うか先に確認するよう、公式が注意しています。
Full content では、スパンごとの内容の上限が既定で 0.75 MB です。英語のテキストなら 200k トークンの文脈に収まる大きさです。超えるとシステムプロンプトと古いメッセージから削られ、anthropic.content.truncated が true になります。画像と文書は種類だけが残ります。上限は SDK の traces.max_content_bytes か、Console の「Maximum content size in MB」で変えられます。1M トークンの文脈をそのまま入れるには、約 4 MB が必要とされています。
Anthropic との間に HIPAA・FERPA・K-12 のデータ取り扱い制限がある組織では、送信先は content mode にかかわらずメタデータだけを送ります。SDK のスパンは影響を受けません。
ZDR と Managed Agents の扱い
ZDR (ゼロデータ保持) との関係は、機能で分かれます。
- Messages API: ZDR のままでも Full content を使えます。API は内容を、送信先に届けるまでメモリにだけ保持します
- Claude Managed Agents: ZDR の対象外です。OpenTelemetry を使っても、データ保持の扱いは変わりません
どちらの場合も、届いたあとのデータは送信先の基盤が持ちます。Managed Agents を使う組織は、OpenTelemetry を入れても ZDR の対象外のままである点を、審査の前提にしてください。個別の仕様は、dynamic workflows の記事とweb_fetch の記事で扱っています。
トークンを集計するときの注意
トークンの数をトレースから集計するなら、二重に数えない決まりがあります。1 つのリクエストについて、取得元は 1 種類に絞ります。
- SDK のスパンと API のスパンは、どちらも名前が
anthropic.messages.createです。SDK のものはCLIENT、その子の API のものはSERVERの kind で区別します - 両方がある場合は、API のスパンを足します。API では
anthropic.messages.createかanthropic.model_requestのどちらか片方を足します gen_ai.usage.input_tokensはプロンプトキャッシュの読み書き分を含むので、キャッシュの属性を別に足さない- 配信の再送でスパンが重複するので、重複を取り除かない基盤では、トレース ID とスパン ID で数える
スパンの配信は best effort なので、課金や利用量の正確な記録としては保証されません。API キーごとの利用量を追うなら、公式は Usage API を使うよう案内しています。
beta の間に気をつけること
公式の SDK ページには、beta の間にオプションやスパンの形が、コードやクエリやダッシュボードを壊す形で変わりうると書かれています。新しい SDK でスパン名・属性・オプション・環境変数の名前が変わる例が挙がっています。SDK のバージョンを固定すれば、更新のタイミングを自分で選べます。
Java では、別の依存関係が opentelemetry-api を 1.57.0 未満に固定していると、スパンが tracer provider に届かない場合があります。TypeScript で @opentelemetry/instrumentation-undici を使うときは、propagation: false を設定するよう警告されています。
導入前に決める 5 項目
ここからは、公式の記載から考えた運用の提案です。Anthropic が示した手順ではないので、自社の要件に合わせて取捨してください。
- まず SDK 側だけで試す。権限が要らず、スパンはコンソールに出して確かめられます
- content mode を決める。既定の Metadata only で始め、Full content が必要な理由と、監視基盤の保持期間・アクセス制御を先に書き出します
- API 側を足す人を決める。送信先を登録できるのは Console の admin ロールです。ワークスペースの範囲も決めます
- 集計のルールを決める。トークンを足すスパンを 1 種類に決め、課金の確認は Usage API に分けます
- SDK のバージョン固定と更新の担当を決める。beta の変更が、ダッシュボードの壊れとして先に見つかる状態を避けます
注意
Managed Agents は ZDR の対象外です。ZDR を前提にしている組織は、OpenTelemetry を入れても Managed Agents の保持の扱いが変わらない点を、審査の資料に書いてください。
FIXIT の運用
FIXIT は AI 駆動開発のクリエイティブスタジオとして、Claude API を使ったプロダクト開発を手がけています。LLM を組み込むプロダクトでは、遅い・失敗する・コストが読めない、といった運用の問題が、後から表に出やすい箇所です。そのため、監視をどの粒度で入れるかは、設計の早い段階で決めておく項目だと考えています。
エージェントを業務に組み込む設計や評価はAI エージェント開発で、開発チームへのツール定着と権限設計の相談はAI 開発ツール定着支援で扱っています。
まとめ
Claude API の OpenTelemetry 連携は、2026 年 10 月 14 日に beta で始まりました。SDK 側は権限なしでコードから、API 側は Console の admin が送信先を足して設定します。プロンプトを送るかは content mode で決まり、既定は送らない Metadata only です。Managed Agents は ZDR の対象外で、beta の間は SDK のバージョンを固定したほうが安全です。
次の一歩は、手元のアプリで SDK のスパンをコンソールに出し、anthropic.messages.create が 1 つ出ることを確かめることです。SDK の移行を控えている場合は、Anthropic Python SDK v1 への移行も先に確認してください。監視の設計や Claude API の本番運用を相談したい場合は、お問い合わせから状況を教えてください。