OpenTelemetry 設定を組織設定で配布して、Claude Team に所属するユーザー全員の Claude Code 利用状況をSplunkで可視化した

CARTA fluct エンジニアのなっかー @konsent_nakka です。

対象読者

Claude Team プラン利用者 (おそらくEnterpriseも同様)

概要

Claude Code は OpenTelemetry を出力できるため、設定さえ仕込めばユーザーごとのトークン消費量やコスト、利用頻度を可観測基盤に集約できます。ただし、これを「組織全体で当たり前に集まる状態」にするには、各メンバーが個別に settings.json を書く運用では限界があります。誰かが書き忘れる、トークンの渡し方をどうするか毎回考える、退職時の取り回しが面倒、といった話が一気に噴出します。

Claude Team の 組織設定 には、settings.json を所属ユーザー全員に強制配布する仕組みが用意されています。これを使うと、OTelの仕組みを、ユーザー側の操作を経由せずに配ることができます。fluct ではこれを使って Splunk に Claude Code の利用ログを集約し、ユーザーごとのコスト・トークン消費量の可視化、利用量のリーダーボードを社内に公開しました。

結論: 組織設定の settings.json に OTel 設定を一括で配る

Claude Team の管理画面から配布する settings.json に、OTel を有効化する env を含めて配ります。設定の中身としては、概ね次のようなイメージになります。

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_EXPORTER_OTLP_HEADERS": "X-SF-Token=<splunk-ingest-token>",
    "OTEL_EXPORTER_OTLP_METRICS_ENDPOINT": "https://ingest.us1.signalfx.com/v2/datapoint/otlp",
    "OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE": "delta",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf",
    "OTEL_LOGS_EXPORTER": "none",
    "OTEL_LOG_USER_PROMPTS": "0",
    "OTEL_METRICS_EXPORTER": "otlp"
  }
}

Claude Team の組織設定とは

Claude Team の管理者向けの画面には、所属ユーザーに対して settings.json の中身を配布する機能があります。配布された設定は、各ユーザーの Claude Code が起動するときに マージされた上で適用 されます。

重要なのは、組織設定で指定された値は ユーザーによる上書きが不可能 という点です。ローカルの ~/.claude/settings.json で同じキーを書き直しても、組織設定が常に勝ちます。これは管理者目線では強力な保証になります。telemetry を全社的に取りたいというニーズに対して、ユーザー個別の意思では off にできない、という運用を作れます。

なぜ組織配布で配るのか

OTel の送信先 (Splunk / Datadog / 任意の OTLP collector など) には、ほぼ必ず認証ヘッダが必要です。これをユーザー個別に配ると、次のような問題が一気に噴出します。

各ユーザーがトークンを取得する経路を整備しないといけません。Vault や 1Password にトークンを置く、社内 Wiki に貼る、Slack で DM する、どれも面倒で漏れの温床になります。

さらにトークンを抱えるユーザーが Claude Code を再インストールしたり、別 PC でセットアップし直したときに、また同じ作業を踏ませることになります。

組織設定でトークンを配布すれば、これらが全部 1 箇所での管理に集約されます。fluct では Splunk の INGEST 専用トークン を発行して組織設定に載せています。INGEST 専用トークンは「データを書き込めるだけで、データの読み出しや管理操作はできない」ものなので、万が一漏れたとしても被害は軽微です。

何が見えるようになるか

OTel が流れ始めると、Splunk 側にはユーザー単位の利用ログが蓄積されていきます。fluct で実際に出しているビューは大きく分けて 2 種類です。

ユーザーごとの コストとトークン消費量。Claude Code が出力する OTel イベントには、リクエスト単位のトークン数、モデル種別、コスト相当の情報が含まれます。これを Splunk 側で集計すれば、誰が・どのモデルを・どれくらい使っているかが可視化できます。組織として「誰が Claude Code を使い倒しているか」「Premiumシートを誰に配るべきか」「コストの傾きはどう推移しているか」を月単位で見れるようになります。

ユーザー利用コストの リーダーボード。要は社内の Claude Code ヘビーユーザーのランキングです。これは「Claude Code 使え使え」と号令をかけるよりも、ランキングが見えるだけで自然と「あいつ使ってるなら自分も触ってみるか」という気運を生む効果が大きく、導入直後のキックスタートには特に効いている感覚があります。導入が進んだ後も、利用が伸びていないチームのフォローや、ヘビーユーザーから知見をヒアリングする入り口として使えないかと模索中です。

注意点

組織設定の OTel 配布は仕組みとしてはシンプルですが、運用上いくつか踏みやすい点があります。

設定の反映には Claude セッションの再起動が必要

組織設定を更新しても、すでに起動中の Claude Code セッションには反映されません。/loginでアカウントを切り替えても反映はされません。設定はセッション開始時に読まれるため、変更を反映させるには Claude Code を一度終了して立ち上げ直す必要があります。

これは初回配布時に特に注意が必要です。「組織設定を配ったのに OTel が流れない」と思ったら、単に既存セッションが古い設定で動き続けているだけ、というケースが多いです。配布のアナウンスと一緒に「Claude Code を再起動してください」と添えておくと、問い合わせが減ります。

個人アカウントに切り替えると個人アカウントの利用履歴も OTel に流れる

組織設定が反映された Claude Code セッションで、ログイン中のアカウントを個人アカウント (Claude Team 配下ではない Anthropic アカウント) に切り替えると、その個人アカウントでの利用履歴も組織側の OTel エンドポイントに送信され続けます。これは「組織設定の env が claude プロセスに焼き付いている」ことに起因する挙動で、アカウントを切り替えても OTel 設定までは切り替わりません。

技術的にデータ漏洩というわけではない (利用しているのは本人なので) ですが、気持ち悪さを感じるユーザーは一定数います。アナウンスの中で「組織アカウントから個人アカウントに切り替える際は、いったん Claude Code を終了してから切り替えてください」と案内しておくと丁寧です。