結論：opt inの前に、headerを誰が見て何を判断するか決める
Claude Code 2.1.273では、LLM Gateway向けにrequest class、agent type、直前toolの所要時間、compactionなどを示すhint headersが追加されました。公式changelogの案内どおり、CLAUDE_CODE_GATEWAY_HINT_HEADERS=1でopt inできます。ただし、送信を有効にしただけで監査が完成するわけではありません。Gateway、collector、保存先、閲覧者、削除期限を先に決め、実データを送る前に検証してください。
読者の課題は「Gatewayを通しているのに、どの種類のrequestが遅いのか説明できない」ことです。hint headersは判断材料を増やしますが、本文やtool結果そのものを安全に保存する仕組みではありません。ラベルを観測用metadataとして扱い、プロンプト、秘密情報、顧客データと混ぜないことが最初の境界です。
根拠はClaude Code公式changelogとClaude apps gateway公式文書です。既存のApps GatewayのOTLP設計はcollector経路、telemetryのuser属性監査は識別情報の扱い、Gateway料金の実測は費用の照合が中心で、本稿は新しいhint headersを監査へ追加する手順に絞ります。
hint headersと既存telemetryを比較する
| 情報 | 分かること | 先に決めること |
|---|---|---|
| request class | requestの分類 | 分類名の社内定義と閲覧者 |
| agent type | agent種別の切り分け | 部署・案件との結合可否 |
| prev tool durations | 直前toolの所要時間 | 単位、集計、保持期間 |
| compaction / context compacted | 圧縮の発生状況 | 品質評価との結合方法 |
| OTel metrics・events・traces | 利用量や状態の観測 | 送信先、認証、collector障害時の扱い |
hint headersとOTelは同じものではありません。前者はGatewayがrequestを振り分ける時の補助情報で、後者は観測基盤へ送るmetrics、events、tracesです。Gatewayでheaderを受け取り、無制限にログへ複製すると、便利なmetadataが長期保存の新しい個人情報になり得ます。request IDなど必要な相関キーだけを残し、原文の転送や全文ログ化は別の承認にしてください。
有効化前に行う8手順
- 目的を書く。遅延調査、context圧縮の検知、agent別の負荷把握など、headerを見て行う判断を一文にします。
- 受信先を台帳化する。Claude Code、Gateway、upstream provider、collector、dashboardの経路を図にします。
- 許可するheaderを列挙する。公式に追加された5種類を全部保存するのか、request classだけ集計するのかを決めます。
- 値の意味を確認する。agent typeやtool durationを部署名、顧客名、担当者IDと結び付ける前に、必要性を確認します。
- 保持と削除を設定する。debug用の短期ログと、月次集計の長期データを分離し、削除が実行された証跡を残します。
- 権限を分ける。Gateway管理者、運用担当、監査担当で、受信設定、raw閲覧、集計閲覧を分離します。
- 検証環境でopt inする。
CLAUDE_CODE_GATEWAY_HINT_HEADERS=1を限定したprojectやmanaged settings scopeへ配布し、期待したrequestだけを確認します。 - 停止条件を試す。想定外の値、collector停止、認証エラー、ログ急増が出たら無効化し、通常のrequestが復旧するかを確認します。
検証では「headerが届いた」だけを成功条件にしません。想定したheader名がGatewayで保持され、不要な本文が保存されず、collector障害時に業務が止まらず、担当者が同じ画面から意味を説明できることを合格条件にします。headerが届かない場合も、version、環境変数のscope、Gatewayの受信設定、proxyの削除を順番に切り分けます。
特にGatewayを複数のproviderへ接続している場合は、headerの伝播をproviderごとに確認します。途中のproxyが未知のheaderを削除することも、逆に受信した値を別のログへコピーすることもあります。開発環境、検証環境、本番環境で同じ設定名でも保存先や閲覧者が異なるため、環境名とrelease versionを観測データへ付け、比較可能な単位を先に揃えます。異常を見つけた時に無効化できるownerとrollback方法まで決めて、初めて全社展開の候補になります。
記録の目的とアクセス権が変わった時は、同じheaderでも再審査します。
企業運用のチェックリスト
- Claude Codeのversionと更新日を記録した
- opt in変数を誰がどのscopeへ配布するか決めた
- Gatewayで受信・転送・破棄の境界を確認した
- tool durationの単位と欠損値を定義した
- agent typeを個人評価や人事評価へ直結させないルールを置いた
- raw headerと集計値の閲覧権限を分けた
- collector停止時、ログ急増時、認証失敗時の停止手順を試した
- 料金・品質の効果を公式保証と誤認しない記録を残した
数値を集めるほど、目的外利用の誘惑も強くなります。「見られるから見る」ではなく、毎週見る指標と、その指標で変更する設定を限定してください。context compactedの増加を検知しても、直ちにモデル変更や利用制限を決めず、入力サイズ、session時間、tool結果、利用者の作業内容を確認してから判断します。
よくある質問
環境変数を全社へ配れば安全ですか？
安全とは限りません。Gatewayの受信設定、ログ保存、collector権限、削除手順まで確認し、まず限定scopeで試します。
hint headersはpromptやtool結果を含みますか？
公式changelogが示すのはrequest classなどのheader追加です。本文やtool結果を別途収集する設定と混同せず、実際のGatewayログで確認します。
料金削減のために有効化できますか？
費用の原因を観測する材料にはなりますが、header追加だけの削減効果は公式保証されていません。既存のspend meterや利用量と照合してください。
公式情報
次の一歩
Gatewayの観測項目が増えても、業務のどこで判断が止まるかが曖昧なら運用は安定しません。Miraigentの無料診断では、対象業務、権限、ログ、停止条件を棚卸しし、最初に測る項目を一緒に決めます。