OTEL_METRICS_INCLUDE_ENTRYPOINTとは — 起点とリポジトリを可視化する変数

OTEL_METRICS_INCLUDE_ENTRYPOINT / OTEL_METRICS_INCLUDE_REPOSITORYとは

OTEL_METRICS_INCLUDE_ENTRYPOINTとOTEL_METRICS_INCLUDE_REPOSITORYは、Claude CodeのOpenTelemetryメトリクスとイベントに追加の属性を乗せる環境変数です。どちらも既定は無効で、trueにすると属性が付き始めます。

OTEL_METRICS_INCLUDE_ENTRYPOINTはapp.entrypoint属性を追加します。値はcli・sdk-cli・sdk-ts・sdk-py・claude-vscodeのように、セッションがどの起動経路で始まったかを表します。CLIからの利用とAgent SDK経由の利用、VS Code拡張からの利用を同じダッシュボードで区別できるようになります。v2.1.152で追加されました。

OTEL_METRICS_INCLUDE_REPOSITORYはvcs.repository.url.full・vcs.owner.name・vcs.repository.name・vcs.provider.nameの4つのvcs.*属性を追加します。セッションのoriginリモートから1セッションにつき1回だけ導出され、どのリポジトリでの作業かをメトリクスとイベントに紐づけられます。Claude Code v2.1.269以降が必要です。

両方ともメトリクスのカーディナリティ制御対象の変数で、標準属性の一覧に載っています。既定で外れているのは、値の種類が増えるほどメトリクスバックエンドのラベル数とストレージコストが増えるためです。

追加されたバージョン

古いバージョンのClaude CodeでOTEL_METRICS_INCLUDE_REPOSITORY=trueを設定しても、vcs.*属性は付きません。組織にセルフホスト環境やロールアウトの遅れがある場合は、コレクター側でバージョン混在を前提にクエリを組む必要があります。

vcs.*属性の中身と省略される条件

vcs.*属性はHTTPSリモートとSSHリモートのどちらからでも同じ値になります。vcs.repository.url.fullは.gitを除いたブラウザURL(例: https://github.com/example-org/example-repo)、vcs.owner.nameはオーナーまたはグループのパス、vcs.repository.nameはリポジトリ名だけを取り出した値です。vcs.provider.nameはGitHub・GitLab・Bitbucket・GiteaのいずれかをリモートのURL形状から推測し、該当しなければ省略されます。値はすべて小文字化され、認証情報・クエリ文字列・フラグメントはリモートURLから取り除かれてから格納されます。

次の条件ではvcs.*属性そのものが付きません。

• セッションにoriginリモートが無い
• リモートがURLの形をしていない
• 囲んでいるリポジトリがホームディレクトリだけ

vcs.owner.nameだけは単独で省略されることもあります。リモートのパスが1セグメントしかない場合(オーナーとリポジトリ名の2セグメント構造と異なるセルフホスト型のGitサーバーなど)はvcs.owner.nameが省略されます。vcs.repository.nameとvcs.provider.nameはこの影響を受けず、認識できたプロバイダーの種類に応じて独立に判定されます。

OTEL_RESOURCE_ATTRIBUTESでvcs.*のキーを自分で宣言すると、その値が導出値を上書きします。vcs.repository.url.fullを宣言した場合、Claude Codeはリモートを読みに行かず、宣言したキーだけを報告します。vcs.*属性は自分のエクスポーター宛にのみ流れ、Anthropic側のテレメトリではvcs.*キーがすべて破棄されます。

設定方法

シェルで直接有効にする場合は次のように書きます。

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_METRICS_INCLUDE_ENTRYPOINT=true
export OTEL_METRICS_INCLUDE_REPOSITORY=true
claude

組織全体に配りたい場合はmanaged settingsの env に書きます(公式の例に沿った形)。

{
  "env": {
    "OTEL_METRICS_INCLUDE_ENTRYPOINT": "true",
    "OTEL_METRICS_INCLUDE_REPOSITORY": "true"
  }
}

設定が反映されたかは、バックエンド側でclaude_code.session.countメトリクスを確認し、app.entrypointやvcs.repository.nameのラベルが付いているかを見れば判断できます。何も届かない場合はclaude --debug-file <path>でセッションを起動し、出力されるログに[3P telemetry]のエラーが無いかを確認します。

この2変数は、テレメトリのON/OFFや送信先を決める変数(CLAUDE_CODE_ENABLE_TELEMETRYやOTEL_EXPORTER_OTLP_*など)とは扱いが違います。公式ドキュメントが挙げる「project / local settingsがenvで設定できない変数」の一覧にOTEL_METRICS_INCLUDE_ENTRYPOINTとOTEL_METRICS_INCLUDE_REPOSITORYは含まれていません。つまりリポジトリの.claude/settings.jsonからでも有効化できます。マネージド設定のenvで同じ変数を指定しない限り、このリポジトリ側の値が反映されます(ユーザー設定よりプロジェクト設定が優先されます)。優先順位は、マネージド設定 > 起動時のコマンドライン引数 > .claude/settings.local.json(個人用のプロジェクト設定)> .claude/settings.json(共有プロジェクト設定)> ~/.claude/settings.json(ユーザー設定)の順です。envブロックの中身は通常の設定キーと同じ扱いなので、この2変数もこの序列にそのまま従い、設定ファイルのenvで指定した値はシェルで直接exportした同名の変数より優先されます。

app.entrypointとvcs.*は既定オフ側の属性 — 常時付く属性との違い

Claude Codeのメトリクスとイベントには、app.entrypointやvcs.*以外にも既定でオン・オフが分かれた標準属性が複数あります。全体像を見ると、2変数がどこに位置するかが分かります。

organization.id・user.id・user.email・terminal.typeは認証済み・検出済みなら常に含まれ、オフにする変数はありません。app.entrypointとvcs.*は、app.versionと同じく「既定でオフ」側のグループに属し、必要な組織だけが自分の判断でオンにする設計です。

他の変数との優先順位

OTEL_EXPORTER_OTLP_ENDPOINTのようなエクスポーター設定変数は、マネージド設定で1つ設定すると、開発者側が設定した競合する変数をClaude Codeが起動時に取り除く仕組みがあります。これはテレメトリの送信先を固定するための挙動です。

OTEL_METRICS_INCLUDE_ENTRYPOINTとOTEL_METRICS_INCLUDE_REPOSITORYはこの削除対象には含まれません。送信先を決める変数ではなく、送信する属性の中身を決める変数だからです。両方とも通常の設定ファイル間の優先順位に従い、同じ変数がマネージド設定にもあればユーザー設定・プロジェクト設定の値より優先されます。管理者が組織全体でオンを固定したい場合は、マネージド設定のenvに明示的に書いておく必要があります。

app.entrypointの値が示す起動経路

app.entrypointに入る値は5種類あります。それぞれ次の起動方法に対応します。

• cli: ターミナルから直接claudeコマンドを実行したセッション
• sdk-cli: Agent SDKが内部でCLIサブプロセスを起動して動かしたセッション
• sdk-ts: TypeScript版Agent SDKから直接APIを呼んだセッション
• sdk-py: Python版Agent SDKから直接APIを呼んだセッション
• claude-vscode: VS Code拡張から起動したセッション

同じ組織内で対話的なCLI利用と、CIに組み込んだAgent SDK経由の自動実行が混在している場合、app.entrypointが無いとこの2つのコストとトークン消費が同じ集計に混ざります。属性を付ければ、claude_code.cost.usageやclaude_code.token.usageをエントリポイント別に分解でき、自動実行側のコストだけを追ったり、対話的利用の伸びを別に見たりできます。

セッションカウンター(claude_code.session.count)にはstart_typeという別の属性(fresh・resume・continue・agents_view)も標準属性として乗ります。app.entrypointとstart_typeを組み合わせると、「VS Codeから新規に始めたセッション」と「CLIで--continueから再開したセッション」のような、起動経路と開始方法の両方を掛け合わせた分解ができます。

この2変数が効くシーン

app.entrypointはclaude_code.session.count・claude_code.cost.usage・claude_code.token.usageをはじめとする全メトリクスの標準属性に乗るため、既存のダッシュボードを崩さずに起動経路の内訳を追加できます。

紛らわしい点

• 変数名はMETRICSだが、実際はイベントにも同じ属性が付く: 公式ドキュメントの標準属性表は「すべてのメトリクスとイベントがこれらの属性を共有する」と明記しており、app.entrypointとvcs.*もその対象です。名前だけ見るとメトリクス限定の設定に見えますが、claude_code.user_promptのようなイベントにも同じ値が乗ります
• OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTESとは別物: こちらはOTEL_RESOURCE_ATTRIBUTESで自分が宣言したカスタムキー(departmentなど)をメトリクスのラベルに含めるかどうかの変数です。OTEL_METRICS_INCLUDE_REPOSITORYが制御するのは、既定ではoriginリモートから自動導出されるvcs.*属性で、対象も仕組みも異なります(導出のされ方は前述のとおりです)
• vcs.*はAnthropicの純正テレメトリには届かない: 社内のOTLPコレクターに送る設定をしていなければ、有効化してもリポジトリ情報を確認する手段はありません(自分のエクスポーター宛にのみ流れる仕組みは前述のとおりです)
• GitHub / GitLab / Bitbucket / Gitea以外はvcs.provider.nameが付かない: セルフホスト型のGitサーバーや、これら4種以外のホスティングサービスでは、vcs.repository.url.fullなどは入ってもvcs.provider.nameだけ省略されます

注意点

• vcs.*属性を除き、OTEL_RESOURCE_ATTRIBUTESで追加したカスタムキーがuser.idやsession.idのような標準属性と衝突した場合、Claude Codeは標準属性の値を優先します
• Claude CodeはOTEL_*環境変数をBashツール・hooks・MCPサーバー・言語サーバーなどのサブプロセスには渡しません。サブプロセス側で別途OpenTelemetryを設定している場合、この2変数の値は引き継がれません
• prometheusだけをメトリクスエクスポーターにしている場合、USD・tokens・sのような単位表記はエクスポート結果から省かれますが、app.entrypointやvcs.*のような文字列属性の扱いには影響しません

まとめ

OTEL_METRICS_INCLUDE_ENTRYPOINTとOTEL_METRICS_INCLUDE_REPOSITORYは、既定でオフになっている2つの分解軸(起動経路とリポジトリ)をテレメトリに追加する環境変数です。CLI・Agent SDK・VS Code拡張が混在する組織や、モノレポで利用量をリポジトリ単位に見たいチームは、trueにする価値があります。単一リポジトリ・単一起動経路の環境では、属性を増やすメリットよりバックエンドのラベル数が増えるコストの方が大きくなりやすいため、ダッシュボードで実際に起点別・リポジトリ別の分解が必要かを確認してから有効化するのが安全です。設定全体の流れはClaude CodeのOpenTelemetry可視化ガイド、テレメトリを完全に止めたい場合はDO_NOT_TRACKを参照してください。

有効化そのものは環境変数1行を書くだけで済みますが、効果が出るのはバックエンド側のクエリやダッシュボードを起点別・リポジトリ別に組み替えたときです。まずは開発環境で1セッション分のメトリクスを送ってみて、app.entrypointとvcs.*が想定どおりの値で入っているかを確認してから、組織全体のマネージド設定へ展開するのが安全な進め方です。