Claude Apps GatewayのOTLP転送を設計する

結論：Gatewayの転送経路とClaude Code個別設定を分けて管理する

一次情報はClaude Code公式changelogと公式Monitoring文書です。changelogは2.1.265のGateway telemetry relay変更と2.1.266の関連修正、Monitoring文書はOpenTelemetryのmetrics・events・traces、OTLP endpoint、managed settingsによる宛先固定、debug確認を説明しています。既存のuser属性記事は属性の対象と監査単位を扱うため、本記事は転送経路とcollector設計に限定します。

3つのtelemetry経路を比較する

経路	主な管理者	確認すること
Gateway管理collector	Gateway管理者	名前、endpoint、protocol、direct export
Claude Code exporter	組織またはsession設定	metrics・logs・traces、OTLP環境変数、scope
子プロセスのtelemetry	アプリ・MCP・hookの所有者	親から変数が渡らない、独自endpointとsecret

公式Monitoring文書では、Claude Codeはmetricsをmetrics protocol、eventsをlogs/events protocol、任意のdistributed tracesをtraces protocolでexportします。OTLP exporterのendpointやheaderを設定できますが、Claude CodeはOTEL_*環境変数をBash、hooks、MCP、language serverへ渡しません。アプリ側のtelemetryを同じcollectorへ送るなら、アプリ自身の設定と責任者を別に決めます。

7手順：collectorへの到達とデータ範囲を検証する

1. Claude Codeのversion、Apps Gatewayの設定revision、collectorのversionと管理者を記録します。
2. 送るデータをmetrics、logs/events、tracesに分け、prompt本文・tool内容・user属性を収集するか決めます。
3. Gatewayが名前付きcollectorを指定しているか、relayを使う経路が残るか、設定の正本で確認します。
4. managed settingsではendpoint、protocol、credentials、exporter selectorを分け、個人設定が宛先を上書きしないことを確認します。
5. collector側でTLS、認証、受信port、resource attribute、保持期間、閲覧権限を設定します。認証値は本文やチケットへ記載しません。
6. 検証用sessionでmetricsを一件、prompt eventを一件、必要ならtraceを一件だけ発生させ、collectorの受信時刻と相関IDを確認します。
7. Claude Codeの--debugでexporterエラーを確認し、direct export・relay・未送信を分類してから限定展開します。

検証では、収集できたことと収集してよいことを分けます。Monitoring文書にはprompt、tool details、tool content、raw API bodiesなど内容を含む設定があります。企業利用ではredaction、個人情報、秘密情報、保存期間、閲覧者を先に決め、必要な信号だけ有効化します。telemetryのuser.emailやuser.groupsを監査単位へ使う場合はユーザー属性の記事、設定確認は組織ポリシーの記事、費用把握は利用状況の監視記事も参照してください。

managed settingsで宛先を固定する時の注意

公式Monitoring文書では、managed settingsでOTEL_EXPORTER_OTLP_ENDPOINTを設定すると、開発者が指定したsignal別endpointを削除します。protocolも同様に競合を抑え、credentialsをmanaged settingsで設定すると、開発者が指定したendpointと個別credentialも削除する扱いです。これは意図しないcollectorへ認証情報を送らないための境界ですが、設定を置いた担当者は、何が削除されるかを文書化してください。

一方、子プロセスへの継承は別問題です。MCP serverやlanguage serverが独自にOTLPを出すなら、Claude Codeの設定だけを確認しても不十分です。子プロセスのendpoint、credential、data classificationを所有者と確認し、Claude Codeのsession telemetryと同じ場所へ送るか、分離するか判断します。

障害時の判断：relay停止とcollector停止を分ける

Gatewayのrelayが止まった場合と、direct export先のcollectorが受け付けない場合では、切り分ける担当が異なります。2.1.266の修正を理由に全sessionを再ログインさせるのではなく、設定revision、Gateway名、collector status、Claude Code debugのerror、発生時刻をそろえます。collector停止中に再送されるか、欠損を許容する信号か、業務上必須の監査証跡かも事前に決めます。

料金について、OTLP転送の専用料金を今回の公式文書から断定しません。利用モデル、Claude Codeの契約、Gatewayの運用基盤、collectorやストレージの費用は別々に確認し、telemetryを増やした結果の保存費用も自社の見積りに含めます。

チェックリスト：転送を本番化する前に

□versionとGateway revisionを記録した　□metrics・events・tracesを分類した　□promptとtool内容の収集可否を決めた　□direct exportとrelayを区別した　□endpointとprotocolをmanaged settingsで固定した　□credential管理者を決めた　□子プロセスへ継承されないことを確認した　□collectorのTLS・保持・閲覧権限を確認した　□debugで受信を検証した　□停止時の欠損と再送を決めた

よくある質問

Gatewayを使えばOTLP設定は不要ですか？

不要とは限りません。Gatewayが名前付きcollectorを管理する場合でも、Claude Code側のexporter、signal、managed settings、collector受信設定の整合を確認します。

子プロセスのMCPログも自動でcollectorへ届きますか？

届きません。公式文書ではClaude CodeがOTEL_*環境変数を子プロセスへ渡さないため、MCPやアプリ側の設定を別に設計します。

全部のtelemetryを有効にすべきですか？

目的に必要な信号だけを選びます。promptやtool内容は個人情報・秘密情報・保持期間の影響が大きいため、最小限から検証します。

公式情報と無料診断

転送仕様は公式changelogと公式Monitoring文書を公開直前にreadbackしています。Miraigentの無料診断では、Gateway、collector、telemetry、権限、保持期間を企業の監査要件へ接続して整理できます。