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 Agent 会话当前使用的执行架构。它负责路由、可选的跟踪拦截和 SQLite 持久化、资源规范化，以及跨提供方的跟踪上下文。各提供方负责自己的原生埋点。

当 Agent Host 不可用时，扩展宿主中的 Copilot CLI 源仍会作为回退方案，并用于支持旧版会话迁移。Agent Host 可用时，该源通常会隐藏；它不是当前 Agent Host 架构。不要将其用作新工作的参考模型。

本地 Copilot Chat 仍是独立的、用户可见的扩展宿主界面。其前台聊天、大模型、工具、钩子、指标和事件埋点会继续通过 extensions/copilot/src/platform/otel/ 下的 IOTelService 实现。

运行时版本规范

Copilot 的原生 OTel 信号契约位于 github/copilot-agent-runtime 中，而不是 VS Code 的 TypeScript 属性常量中。审查或修改集成之前：

1. 查看根目录 package-lock.json 中的 @github/copilot-sdk 和 @github/copilot 版本。
2. 找到匹配的不可变运行时标签和提交。
3. 查看该修订版本中的运行时监控参考文档和实现。
4. 只有在确认相关文件与捆绑版本一致后，才使用运行时 main。

运行时的 docs/developer-docs/monitor.md 详细介绍了 Copilot 原生 span、属性、span 事件、指标、协议、环境变量、内容捕获、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 支持两种路由模式：

• 直通： 提供方 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 信号：

• 依赖 IOTelService，而不是直接从使用方依赖 OTel SDK。
• 存在标准 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 模式下会保留在本地。

记录支持情况前，请检查提供程序启动代码和捆绑的提供程序版本。

文档规则

• 在 src/vs/platform/agentHost/OTEL.md 中维护当前的 Agent Host 架构和数据流。
• 在 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

本地 Copilot Chat 示例，位于 extensions/copilot/：

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

对于仅涉及文档的更改，请验证：

• 每个相对链接都有效；
• 设置和命令 ID 均存在于源代码中；
• 环境变量名称与翻译和解析代码一致；
• 提供程序和运行时相关说明与捆绑版本一致；
• Mermaid 图表可以正常渲染；
• 没有任何当前文档引导贡献者使用已弃用的扩展主机 CLI 架构。

反模式

• 将已弃用的扩展主机 Copilot CLI 代码视为当前架构。
• 将运行时详尽的信号目录照搬到 VS Code 文档中。
• 假定运行时的 main 与 VS Code 捆绑的包一致。
• 将 Agent Host 和本地 Copilot Chat 设置描述为可以互换。
• 通过仅用于跟踪的 Agent Host 回环发送指标或日志。
• 声称所有提供程序都支持相同的 OTLP 协议。
• 未通过有效的内容捕获开关控制便输出敏感内容。
• 在所属组件提供常量时仍使用原始属性字符串。
• 在可导出的操作下添加仅用于调试的 span，却未明确声明不导出的约定。