Claude Media
Claude apps gatewayのテレメトリ設定 — クライアントとゲートウェイをOTLPで追跡する
Claude Codeチュートリアル

Claude apps gatewayのテレメトリ設定 — クライアントとゲートウェイをOTLPで追跡する

信号ごとに宛先を分ける設定、クライアントへ自動配信される6つの環境変数、AWSでのコレクター接続とコンテナメトリクス収集を扱います。

読了目安 約9分

Claude apps gatewayで何が二重に追跡できるか

Claude apps gatewayを経由すると、開発者側の設定を一切追加せずにClaude CodeのOTLP(OpenTelemetry Protocol)エクスポートがゲートウェイへ届き、そこから設定した宛先へ中継されます。ゲートウェイ自身も、認証・支出上限・upstreamエラーといった運用イベントを別系統のログとして出します。この2つは出所も内容もまったく別物で、片方だけ集めても運用の全体像は見えません。

本記事ではtelemetry.forward_toで信号ごとに宛先を分ける方法、クライアントへ自動で配信される6つの環境変数の中身、そしてAWS上でクライアントテレメトリとコンテナメトリクスをどう収集するかを扱います。ゲートウェイ自身の監査ログ形式や運用ログレベルはデプロイと運用にまとまっています。前提条件はgateway.yamlのlisten.public_urlが設定済みであることだけです。

ステップ1: telemetry.forward_toで信号ごとに宛先を選ぶ

telemetry.forward_toは宛先のリストで、各宛先はmetrics・logs・tracesを個別にopt-inします。既定はmetricsのみです。

telemetry:
  forward_to:
    - url: https://otel-collector.internal.example.com
      headers:
        Authorization: ${OTLP_TOKEN}
      metrics: true
      logs: false
      traces: false
    - url: https://api.datadoghq.com/api/v2/otlp
      headers:
        DD-API-KEY: ${DD_API_KEY}

metricsはトークン数・リクエスト数・レイテンシーの集計値ですが、logsとtracesはClaude Codeが開発者のマシンで実行したbashコマンド・ツールへの入力・ファイルパスまで運びうる点が決定的に違います。アクセス制御と保持ポリシーがそのデータに見合う宛先だけでlogs/tracesを有効にします。

なお、trace span自体はユーザープロンプトの本文・ツール入力の詳細・ツールの出力内容を既定で伏せています。生の中身まで含めるにはOTEL_LOG_USER_PROMPTS=1・OTEL_LOG_TOOL_DETAILS=1・OTEL_LOG_TOOL_CONTENT=1という開発者マシン側の追加opt-inが要るため、forward_to側のtraces有効化と、この中身レベルのopt-inは別の防御線として重ねて設計できます。

URLはhttps://が必須です。唯一の例外はゲートウェイ自身のループバック上のコレクターですが、ホストによって挙動が違います。http://localhost:<port>は設定の検証自体は通るものの、CLAUDE_GATEWAY_ALLOW_LOOPBACK=1を設定しない限りSSRFガードが全エクスポートをECONNREFUSED_SSRFで止めます。一方http://127.0.0.1:<port>やhttp://[::1]:<port>はこの変数を設定していないとゲートウェイのboot自体が失敗します。クラスター内コレクターを使う場合は、独立したHTTPSエンドポイントとして公開するか、この環境変数を設定したサイドカーとして動かします。ゲートウェイはテレメトリをバッファ・集計・保存せず、届いたOTLPを宛先へそのまま中継するだけです。protobuf・JSONどちらのOTLPエンコーディングも中継されるため、OpenTelemetry互換のバックエンドであれば製品を問いません。

実務では宛先を用途で分けるのが定石です。上のYAML例のように、コスト可視化に使うDatadogのようなSaaSにはmetricsだけを渡し、bashコマンドやファイルパスまで含みうるlogs/tracesはアクセス制御が及ぶ社内コレクターだけに絞ると、可観測性と情報漏えいリスクのバランスが取れます。宛先を1つに統一する必要は無く、信号ごとに別の宛先を指定できる設計そのものが、この使い分けを前提にしています。

ステップ2: クライアントには6つの環境変数が自動で届く

telemetry.forward_toとlisten.public_urlの両方を設定すると、テレメトリが有効になり、ゲートウェイは接続済みの全クライアントへ/managed/settings経由で次の6つの環境変数をプッシュします。

  • CLAUDE_CODE_ENABLE_TELEMETRY=1
  • OTEL_METRICS_EXPORTER=otlp
  • OTEL_LOGS_EXPORTER=otlp
  • OTEL_TRACES_EXPORTER=otlp
  • OTEL_EXPORTER_OTLP_ENDPOINT=<public_url>
  • OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf

エンドポイントはpublic_urlから自動で組み立てられるため、metricsとlogsについては開発者側でもポリシー側でもOTELの設定は不要です。この配信はmanagedティアで適用され、開発者がローカルで設定したOTEL_*変数より優先されます。forward_toを設定していなくても、ゲートウェイにサインインしたCLIがOTLP/HTTPエクスポートを有効にしていればエクスポート先はゲートウェイになり、対応する宛先が無い信号は、ゲートウェイが受け取ったうえでエラーを返さずに破棄します。すでに自前でClaude Codeのテレメトリを集めている場合は、そのコレクターをforward_toの宛先に加えるだけで済みます。

traces(ベータ)はこの自動配信の対象外です。有効化には各クライアントにCLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1が別途必要で、ゲートウェイはこれをプッシュしないため、managed policyのenvブロックで配信します。プッシュされるOTLPエンドポイント設定も、このenvブロック経由のtraces有効化変数も、いずれの配信も接続中クライアントに承認ダイアログが出ます。

CLIは認証済みユーザーのJWTからuser.id・user.email・user.groupsをエクスポートへ自動でスタンプします。ゲートウェイを介さない一般的なOTel構成ではOTEL_RESOURCE_ATTRIBUTESをスクリプトやポリシーで手動配線する必要がありますが、ゲートウェイ経由ではこの帰属付けが開発者側の追加設定なしに最初から効いています。イベント個々の中身や指標カタログの全量はClaude CodeのOpenTelemetry監視にまとまっています。

このmanagedティアでの上書きは統治の観点でも意味を持ちます。開発者が自分のマシンで別のOTLPエンドポイントを設定していても、ゲートウェイ経由でサインインしている間はプッシュされた設定が優先されるため、組織が承認していない宛先へ推論関連のテレメトリが流出する経路を構造的に塞げます。

ステップ3: AWSでクライアントテレメトリとコンテナメトリクスを別経路で集める

クライアントのmetrics/logs/tracesは、AWS Distro for OpenTelemetry(ADOT)コレクターのような内部サービスをhttps://で立て、telemetry.forward_toの宛先に指定して受けます。コレクターからAmazon CloudWatch・Amazon Managed Service for Prometheus・任意のOTLPバックエンドへ書き出します。

ゲートウェイ自身の監査ログ・運用ログは別経路です。ECS Fargateではawslogsドライバーが追加設定なしにstderrを/ecs/claude-gatewayロググループへ配送しますが、EKSではPodのログが既定でCloudWatchへ届かないため、Amazon CloudWatch Observability add-on(コンテナログ収集を有効化)かFluent Bit DaemonSetを別途入れないと監査証跡が失われます。CPU・メモリ・ネットワークのようなタスク単位のコンテナメトリクスは、aws ecs update-cluster-settings --cluster claude-gateway --settings name=containerInsights,value=enabledでContainer Insightsを有効化するか、EKSならCloudWatch Observability add-onを入れて取得します。

aws ecs update-cluster-settings \
  --cluster claude-gateway \
  --settings name=containerInsights,value=enabled

クライアント側のforward_to設定自体はupstreamのクラウドを問わず共通です。一方でコレクター接続の具体例が公式に用意されているのはAWS向けだけで、Google Cloud向けのデプロイガイドには対応するTelemetry節がありません。Google Cloud上で運用する場合も、自前で立てたOTelコレクターをhttps://で公開してforward_toの宛先に指定し、そこからCloud LoggingやCloud Monitoring、任意のOTLPバックエンドへ書き出す構成は同じ考え方で組めますが、AWSのADOTコレクター相当の作り込み例までは公式に示されていないため、収集基盤の選定は自組織で判断する必要があります。

テレメトリは事後の可視化です。「誰が今どれだけ使っているか」をリアルタイムに強制するのは支出上限のenforcementが担う別の仕組みで、共有upstreamクレデンシャルに対する2つの異なる防御線だと捉えると役割が整理できます。

よくあるつまずき

  • forward_toだけ設定してlisten.public_urlを忘れる: 両方が揃って初めてクライアントテレメトリが有効になる。片方だけでは動かない
  • ループバックコレクターでCLAUDE_GATEWAY_ALLOW_LOOPBACK=1を忘れる: http://localhost:<port>は検証は通ってもエクスポートがECONNREFUSED_SSRFで止まり、http://127.0.0.1:<port>やhttp://[::1]:<port>はそもそもboot自体が失敗する
  • tracesも自動で届くと思い込む: CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1をmanaged policyのenvで別途配る必要がある
  • logs/tracesを既定の宛先で有効にする: bashコマンドやファイルパスまで流れるため、アクセス制御と保持ポリシーが緩い宛先で有効にすると情報漏えいの経路になる
  • EKSでは監査ログが自動で残ると思い込む: awslogsドライバーが効くのはECS Fargateで、EKSはadd-onかFluent Bitを別途入れないとPodログがCloudWatchに届かない
  • GCPでもAWSと同じ手順を探してしまう: Google Cloud向けのデプロイガイドには専用のTelemetry節が無いため、コレクターの構築自体は自分で設計する前提になる

まとめ

Claude apps gatewayのテレメトリは、クライアント側のOTLPエクスポートをゲートウェイが中継するレイヤーと、ゲートウェイ自身の監査・運用ログという別系統の2本立てです。telemetry.forward_toとlisten.public_urlを揃えれば6つの環境変数が自動配信されユーザー帰属も勝手に付きます。AWSではクライアント信号をADOTコレクター経由で、コンテナ・監査ログをContainer InsightsとCloudWatch(ECS/EKSで手順が異なる)経由で、それぞれ別の配線として設計してください。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →