otel

VS Code の OpenTelemetry

まず、実行環境を特定します。VS Code には、所有者と構成が異なる OTel パイプラインが別々にあります。

環境	プロセスとデータの生成元	構成	VS Code の正式なドキュメント
Agent Host セッション（Copilot、Claude、Codex）	Agent Host ユーティリティプロセスによってルーティングされる、プロバイダー固有のテレメトリ	chat.agentHost.otel.*	src/vs/platform/agentHost/OTEL.md
ローカル Copilot Chat	Copilot Chat 拡張機能ホストと IOTelService	github.copilot.chat.otel.*	extensions/copilot/docs/monitoring/agent_monitoring.md

これらのパイプラインを統合したり、一方の設定が他方も構成すると想定したりしないでください。

現在のアーキテクチャ

Agent Host は、Copilot、Claude、Codex のエージェントセッションにおける現在の実行アーキテクチャです。ルーティング、オプションのトレースインターセプトと SQLite 永続化、リソースの正規化、プロバイダー間のトレースコンテキストを担います。各プロバイダーは、それぞれのネイティブな計装を担います。

拡張機能ホスト内の Copilot CLI ソースは、Agent Host が利用できない場合のフォールバックとして、またレガシーセッションの移行をサポートするために残されています。通常、Agent Host が利用可能な場合は非表示になり、現在の Agent Host アーキテクチャではありません。新しい作業のモデルとして使用しないでください。

ローカル Copilot Chat は、ユーザーに表示される別個の拡張機能ホスト環境として残っています。フォアグラウンドチャット、LLM、ツール、フック、メトリクス、イベントの計装では、引き続き extensions/copilot/src/platform/otel/ の IOTelService を使用します。

ランタイムのバージョン管理

Copilot のネイティブ OTel シグナルの契約は、VS Code の TypeScript 属性定数ではなく、github/copilot-agent-runtime にあります。統合を監査または変更する前に、次の手順を実施してください。

1. ルートの package-lock.json から @github/copilot-sdk と @github/copilot のバージョンを確認します。
2. 対応する不変のランタイムタグとコミットを特定します。
3. そのリビジョンのランタイム監視リファレンスと実装を読みます。
4. 関連ファイルがバンドルされたリビジョンから変更されていないことを確認した後に限り、ランタイムの main を使用します。

ランタイムの docs/developer-docs/monitor.md には、Copilot ネイティブのスパン、属性、スパンイベント、メトリクス、プロトコル、環境変数、コンテンツのキャプチャ、TLS、管理対象設定が網羅されています。VS Code のドキュメントにシグナルの表をコピーするのではなく、バンドルされたパッケージに対応するリビジョンで読み、調査やレビューの証拠にはその不変のリビジョンへのリンクを使用してください。

所有範囲の一覧

Agent Host の統合

src/vs/platform/agentHost/
├── OTEL.md
├── common/
│   ├── agentService.ts                         # setting IDs, env names, settings → env translation
│   └── otel/agentHostOTelService.ts            # service contract and synthetic span names
├── electron-main/electronAgentHostStarter.ts   # Electron spawn-time env binding
├── node/
│   ├── nodeAgentHostStarter.ts                  # server spawn-time env binding
│   ├── otel/agentHostOTelService.ts             # pass-through and DB-mode routing
│   ├── copilot/                                 # Copilot SDK configuration and trace context
│   ├── claude/                                  # Claude launch environment
│   └── codex/                                   # Codex launch overrides
└── test/node/otel/                              # pipeline integration tests

共有トランスポートと永続化は、次の場所にあります。

src/vs/platform/otel/
├── common/                                      # normalized span data and shared attributes
└── node/
    ├── otlp/                                    # receiver, decoder, outbound forwarders
    └── sqlite/                                  # persistent span store

Agent Host は、次の 2 つのルーティングモードをサポートします。

• パススルー： プロバイダー SDK が、構成済みの送信先に直接エクスポートします。
• DB モード： プロバイダートレースはプライベートな OTLP/HTTP JSON ループバックを使用し、SQLite にデコードされます。さらに、互換性のある外部送信先に転送される場合があります。プロバイダーのログとメトリクスは、トレースのループバックを経由しません。

いずれかのモードを変更する前に、src/vs/platform/agentHost/OTEL.md を読んでください。

ローカル Copilot Chat

extensions/copilot/src/platform/otel/
├── common/                                      # IOTelService, config, attributes, events, metrics
└── node/                                        # SDK implementation and exporters

extensions/copilot/src/extension/
├── prompt/node/chatMLFetcher.ts                 # chat spans
├── intents/node/toolCallingLoop.ts              # invoke_agent spans
├── tools/vscode-node/toolsService.ts            # execute_tool spans
├── chat/vscode-node/chatHookService.ts           # execute_hook spans
├── byok/vscode-node/                            # BYOK chat spans
└── trajectory/vscode-node/                      # Agent Debug Log conversion

拡張機能が出力する属性には、extensions/copilot/src/platform/otel/common/genAiAttributes.ts の定数を使用してください。これらの定数は、プロバイダー固有の Agent Host テレメトリに対する正式な定義ではありません。

構成チェックリスト

Agent Host の構成を変更する場合：

1. common/agentHostStarter.config.contribution.ts の設定登録を更新します。
2. common/agentService.ts の設定 ID、環境変数名、buildAgentHostOTelEnv() を更新します。
3. 該当する場合は、readAgentHostOTelEnv() またはプロバイダー起動時の変換を更新します。
4. 優先順位を意図的に維持します。エンタープライズ管理ポリシー、継承された環境変数、ローカル設定はそれぞれ独立した経路です。
5. src/vs/platform/agentHost/OTEL.md を更新します。
6. 対象を絞った変換テストと統合テストを追加します。
7. エンタープライズ制御に関しては、policy-and-managed-settings スキルを呼び出します。

ローカルの Copilot Chat 構成を変更する場合：

1. extensions/copilot/package.json を更新します。
2. extensions/copilot/src/platform/otel/common/otelConfig.ts の resolveOTelConfig() を更新します。
3. agent_monitoring.md を更新します。
4. 対象を絞った構成テストを追加します。

新しいランタイム管理設定を反映するだけの目的で、新しい VS Code 設定を追加してはいけません。ランタイム管理設定の所有権ルールに従ってください。

シグナルとルーティングのチェックリスト

Agent Host のプロバイダー固有シグナルの場合：

1. そのシグナルを所有するプロバイダー／ランタイムのリポジトリで変更します。
2. そのプロバイダーの正式なシグナルリファレンスを更新します。
3. ルーティング、正規化、永続化、親コンテキスト、またはホスト生成メタデータが変わる場合に限り、VS Code を更新します。
4. パススルーと DB モードの動作を個別に確認します。
5. そのシグナルがトレース、メトリック、ログのどれに当たるか確認します。Agent Host のループバックと SQLite ストアに入るのはトレースのみです。
6. 実際にバンドルされるプロバイダーのバージョンでテストします。

ホスト生成スパンの場合：

• 名前と属性は common/otel/agentHostOTelService.ts または共有プラットフォーム定数に記述します。
• プロバイダーごとのサービス名を維持しつつ、service.namespace=vscode.agent-host を保持します。
• タイトル、プロンプト、応答、ツール引数、ファイルパス、コマンド、生のサーバー名は機密コンテンツとして扱います。
• 有効なコンテンツ取得ポリシーに基づいて機密コンテンツを制御し、必要に応じて明示的な上限を適用します。
• プロバイダーがサポートする境界を通じて、W3C の traceparent と tracestate を伝播します。

ローカルの Copilot Chat シグナルの場合：

• 利用側では OTel SDK を直接使用せず、IOTelService に依存します。
• 標準の gen_ai.* キーがある場合は、それを使用します。
• 新しい Copilot 固有属性は github.copilot.* に追加します。新しい copilot_chat.* キーは追加しないでください。
• 既存の利用側で二重出力が必要な場合は、文書化済みのレガシーキーを維持します。
• 新しい操作をエクスポート可能にするかどうかを明示的に決定します。
• Agent Debug Log 専用のレコードは、ユーザー向けの OTLP および SQLite エクスポートに含めないでください。
• 自由形式のコンテンツは、設定された最大値を指定して truncateForOTel に渡します。

プロバイダーの境界

すべての Agent Host プロバイダーに共通する単一のプロトコル対応表があると説明してはいけません。

• Copilot ランタイムは、ネイティブな OTLP/HTTP JSON／protobuf の動作を管理しており、OTLP/gRPC はサポートしていません。
• Claude は起動環境を通じて OTel の構成を受け取ります。
• Codex は起動時の otel.* オーバーライドを受け取ります。
• Agent Host の DB ループバックは常に OTLP/HTTP JSON です。
• 外部の protobuf および gRPC トレースは Agent Host でトランスコードできないため、DB モードではローカルにとどまります。

サポートについて文書化する前に、プロバイダーの起動コードとバンドルされるプロバイダーのバージョンを確認してください。

ドキュメントのルール

• 現在の Agent Host のアーキテクチャとデータフローは src/vs/platform/agentHost/OTEL.md に記載します。
• ローカルの拡張機能ホストでの使用方法は extensions/copilot/docs/monitoring/agent_monitoring.md に記載します。
• Copilot 固有のシグナルを網羅的に記載する場合は、ランタイムのリポジトリに記載します。
• このスキルは手順に特化させます。設定、環境変数、属性、イベント、メトリックの完全な一覧表をここに重複して記載しないでください。
• イシューやプルリクエストで他のリポジトリの根拠を引用する場合は、不変のコミットパーマリンクを使用します。更新プロセスで最新性を維持する場合を除き、常時参照するガイダンスではバージョン固有のリンクを避けてください。
• 実行可能なソースとドキュメントの内容が異なる場合は、テストで確認し、どちらかを黙って選ぶのではなく、相違点を明記します。

検証

変更を網羅する最小限のチェックを選んでください。

Agent Host の例：

./scripts/test.sh --grep "AgentHostOTel\|agent host.*OTel"
./scripts/test-integration.sh --run src/vs/platform/agentHost/test/node/otel/agentHostOTelService.integrationTest.ts

extensions/copilot/ のローカル Copilot Chat の例：

npx tsc --noEmit --project tsconfig.json
npm test -- --grep "OTel"

ドキュメントのみを変更した場合は、次の点を確認してください。

• 相対リンクがすべて解決されること。
• 設定 ID とコマンド ID がソースに存在すること。
• 環境変数名が翻訳コードおよび解析コードと一致すること。
• プロバイダーとランタイムに関する記述が、バンドルされているバージョンと一致すること。
• Mermaid 図が正しく表示されること。
• 現行のドキュメントで、コントリビューターを非推奨の拡張機能ホスト CLI アーキテクチャへ誘導していないこと。

アンチパターン

• 非推奨の拡張機能ホスト Copilot CLI コードを、現行のアーキテクチャとして扱う。
• ランタイムの網羅的なシグナルカタログを VS Code のドキュメントに転載する。
• ランタイムの main が VS Code にバンドルされているパッケージと一致すると想定する。
• Agent Host とローカル Copilot Chat の設定が相互に置き換え可能だと説明する。
• トレース専用の Agent Host ループバック経由でメトリクスやログを送信する。
• すべてのプロバイダーが同じ OTLP プロトコルをサポートすると主張する。
• 有効なコンテンツ取得ゲートを通さずに、機密コンテンツを出力する。
• 所有コンポーネントが定数を提供しているのに、生の属性文字列を使用する。
• 明示的な非エクスポート契約なしに、エクスポート可能な操作の配下にデバッグ専用スパンを追加する。