# Claude API OpenTelemetry出力の統制設計

> Claude APIのOpenTelemetry出力（beta）で送信先と内容モードをどう統制するか。Console管理者が設定する送信先は組織あたり10件まで、既定はmetadata_onlyです。

- Canonical: https://kuucorp.com/blog/claude-api-opentelemetry-export-destination-governance-design/
- Date: 2026-10-16
- Last modified: 2026-10-16
- Publisher: Kuu株式会社 (https://kuucorp.com)

---
数百のワークスペースが同じ Claude 基盤を共有する環境で、「どのチームのどのリクエストが遅く、いくらかかったか」を横断して追えていますか。アプリごとに計装を足す方式では、SDKを使わないクライアントや Managed Agents のセッション内部が見えないままです。2026年10月14日、Claude API は OpenTelemetry 出力をベータで開始しました。API側から直接スパンを送れるため、計装の責任分界が変わります。

関連する設計は[エージェントのトレース計装](/blog/agent-observability-tracing-instrumentation/)と[監査ログのスキーマ設計](/blog/audit-log-tamper-proof-schema-design/)も参照してください。

## Claude API の OpenTelemetry 出力は何が取れるのか

> Messages API と Managed Agents セッションのスパンを、SDK側とAPI側の2経路で取得できます。API側は管理者がConsoleで設定します。

取得経路は2つあります。

| 経路 | 設定場所 | 取れるもの |
|---|---|---|
| SDK トレース | コード（権限不要） | クライアント側スパン、ツールランナーのクライアントツール、ファイルアップロード等 |
| API トレース | Console（Admin権限） | モデル実行ごとのスパン、サーバーツール、Managed Agents のターン |

API トレースは SDK を使わない任意のクライアントを対象にできます。両方を有効にすると、アプリのスパン、SDKのクライアントスパン、APIのサーバースパンが1本のトレースにつながります。属性は GenAI セマンティック規約に沿うため、対応する基盤ではそのまま認識されます。

## 送信先とワークスペースをどう統制するか

> 送信先の登録はAdminロールに限られ、ワークスペース単位で配信範囲を All・Selected・All except から選べます。

送信先（destination）は OTLP/HTTP のエンドポイントで、protobuf エンコードの HTTPS（443番ポート）が条件です。自前の Collector を使う場合は、受信側を443で待ち受けるかロードバランサーを前段に置きます。統制上の要点は次のとおりです。

- 組織あたりの送信先は無効分を含めて**10件**まで。ヘッダーは1送信先あたり20個まで
- 認証情報はヘッダー値にのみ入れる。保存後は Console に値が再表示されない
- 規制対象のワークスペースは **All except** で除外し、監査基盤にだけ **Selected** で送る
- 設定は Admin API・CLI・各言語SDKでも作成でき、Infrastructure as Code に載せられる

リダイレクト（3xx）を返す、非公開IPに解決される、24時間すべて失敗する、のいずれかで送信先は自動的に無効化されます。**Delivery** 列を監視対象に含めてください。

## 内容モードはどう選ぶべきか

> 既定のmetadata_onlyはプロンプトを含まず、contentはプロンプトと応答を含みます。選択は観測基盤の保持設定が決めます。

内容モードは送信先ごとに決まります。`metadata_only` は識別子・時間・ステータス・トークン数を送り、`content` はプロンプトと応答を含めます。`content` では span あたりの上限が既定で0.75 MBで、超過分はシステムプロンプトと最古のメッセージから切り詰められ、`anthropic.content.truncated` が `true` になります。

判断基準は観測基盤側の保持と権限です。公式ドキュメントも、送信後のデータは選んだサービスの保持・アクセス制御下に置かれると明記しています。HIPAA・FERPA・K-12 の制限が組織にある場合は、設定にかかわらずメタデータのみが出力されます。ゼロデータ保持（ZDR）の Messages API でも `content` は使えますが、Managed Agents は ZDR の対象外です。

## 集計とトレース連結で何に注意すべきか

> トークンは1リクエストにつき1つの経路のスパンだけを合計します。配信はat-least-onceで欠落もあり得ます。

SDKスパンとAPIスパンは両方とも `anthropic.messages.create` という名前で、種別（`CLIENT` と `SERVER`）で区別します。二重計上を避けるため、APIスパンを合計する場合は `anthropic.messages.create` か `anthropic.model_request` のどちらか一方だけを使います。同じスパンが再配信されることがあるため、トレースIDとスパンIDで重複を除きます。

スパンの配信はベストエフォートで、呼び出し側が `traceparent` のサンプリングフラグを落とせばスパンは出ません。**課金や漏えい調査の正本にはならない**ため、キー別の利用量は Usage API で照合してください。Managed Agents のセッション全体は `anthropic.session.id`、1スレッドは `gen_ai.conversation.id` で束ねます。MCPコネクタ経由では `params._meta` に `traceparent` が渡り、MCPサーバー側のスパンを同じトレースに入れられます。

ベータ機能のため、仕様変更に備えて送信先設定をコード管理し、Collector を挟んで基盤を差し替えやすくしておくことを推奨します。

## 参考

- [Claude Platform release notes — Claude Platform Docs](https://platform.claude.com/docs/en/release-notes/overview)
- [OpenTelemetry for the Claude API — Claude Platform Docs](https://platform.claude.com/docs/en/manage-claude/opentelemetry)
- [Use OpenTelemetry with the Claude API — Claude Platform Docs](https://platform.claude.com/docs/en/manage-claude/opentelemetry/api)
- [GenAI semantic conventions — OpenTelemetry](https://github.com/open-telemetry/semantic-conventions-genai)

## まとめ

Claude API の OpenTelemetry 出力は、アプリ側計装に頼らず基盤側で観測を統制できる仕組みです。Admin による送信先管理、ワークスペース単位の配信範囲、`metadata_only` を既定とした内容モードを組み合わせ、集計は経路を1つに絞ります。複数チームが共有する Claude 基盤の観測・監査設計は、[Kuuの大規模AI変革プログラム（RDE）](https://kuucorp.com/services/rde/)までご相談ください。