Copilot Chat OpenTelemetry 埋点指南
为 Copilot Chat 统一设计和维护 OpenTelemetry 埋点。
文档明确要求通过 IOTelService、内容截断、captureContent 门控、敏感标识哈希及 Debug Panel/OTLP 隔离来降低数据暴露，并记录进程环境变量和 SDK 内部访问风险；但未规定逐次用户确认、明确回滚流程或依赖安全审计，因此未满分。
内容包含架构映射、操作模式、异常降级要求、配置同步清单、单元测试建议和诊断命令；但本次仅静态阅读，且关键引用文件和测试结果未在材料中完整提供，无法证明可运行性和异常路径，故限制在静态上限内。
目标用户、适用场景、四类 agent 路径、触发条件和若干不应采用的反模式都较清楚；但非适用范围、输入输出契约及中文文档支持不足。核心功能不完全依赖海外服务，但示例所涉外部监控后端可能存在网络可达性差异，因此扣分。
采用分层章节、表格、代码示例和检查清单，明确 MIT 许可及 Microsoft 官方仓库来源；但技能自身没有版本号、变更日志、独立维护责任或明确更新路径，安装和故障排查说明也不完整。
对新增或修改 OTel 埋点提供了可直接参考的架构、命名、数据处理和验证步骤，能覆盖核心开发任务；但依赖未提供的源代码与监控文档，且未见实际输出或端到端验证证据，静态评估按上限给分。
技能引用了具体源码路径、测试路径、CI 验证命令和已知风险，具备一定可审计性；但材料未包含这些测试的实际结果或多源复核，静态评估不能超过 5 分。
- 本评估未执行 TypeScript 检查、单元测试或 Aspire/Agent Debug Log 端到端验证。
- 实施前应核对文档中引用的源码路径、导出器过滤规则、内容捕获设置和 SDK 内部字段是否与该修订版一致。
- 遥测可能包含用户提示、工具参数、会话标识或模型响应；应确认 captureContent、截断、哈希和导出后端策略符合组织隐私要求。
- 若监控后端或依赖海外网络，需为中国大陆环境准备可达性、代理或离线替代方案。
它能做什么 & 适用场景
该技能专门指导 Visual Studio Code 仓库中 Copilot Chat 扩展的 OpenTelemetry 埋点工作。它覆盖前台代理、进程内 Copilot CLI、终端版 Copilot CLI 和 Claude Code 四条执行路径，以及 IOTelService、跨度、指标、事件和跨进程传播约定。修改实现时，必须同步更新用户监控文档、架构文档和相关测试。它适合需要在该代码库中新增或审查遥测的开发者，而不是通用的 OpenTelemetry 教程或独立运行时组件。
要求使用者先阅读 extensions/copilot/docs/monitoring/agent_monitoring.md 和 agent_monitoring_arch.md，并在代码变更的同一修改中维护文档。它规定通过 IOTelService 创建 invoke_agent、chat、execute_tool 和 execute_hook 等跨度，使用 genAiAttributes.ts 中的常量，并根据内容敏感度决定截断或由 captureContent 控制。它说明如何维护 Copilot CLI 的 Bridge SpanProcessor、Claude SDK 消息到 GenAI 跨度的合成、子代理上下文传播，以及 OTLP、文件和 SQLite 导出边界。它还要求更新设置注册、环境变量转换、导出操作名称和单元测试，并提供 tsc 编译检查、OTel/Bridge 测试及手动调试面板验证命令。
- 维护 Copilot Chat 前台代理的 invoke_agent、工具和钩子跨度时，开发者需要遵循统一的命名、属性和错误状态约定。
- 接入或修改进程内 Copilot CLI 时，开发者需要维护 Bridge SpanProcessor、跨度层级、traceparent 和钩子上下文。
- 调整 Claude Code 子进程遥测时，开发者需要根据 SDK 消息合成跨度，并通过本地语言模型服务器记录 chat 跨度。
- 新增指标、事件、属性或 OTel 配置时，开发者需要同步更新公开导出、监控文档和对应测试。
- 排查 Agent Debug Log 与 OTLP 或 SQLite 导出差异时，维护者需要确认 EXPORTABLE_OPERATION_NAMES 和调试面板隔离规则。
优缺点一览
- 针对 VS Code 仓库中的 Copilot Chat 扩展，给出了具体文件、类、属性命名空间和测试位置。
- 覆盖四种代理执行模型，并明确区分直接埋点、CLI 桥接、环境变量转发和 Claude 消息合成。
- 同时考虑调试面板、OTLP、文件和 SQLite 导出，包含旧属性的双写和内容捕获规则。
- 提供配置变更、跨边界传播、桥接修改和验证流程的检查清单。
- 范围严格限定于 microsoft/vscode 中 `.github/skills/otel/SKILL.md` 描述的 Copilot Chat 扩展，不能直接视为通用 OpenTelemetry 方案。
- 依赖对 VS Code 仓库目录结构和内部服务的了解，尤其是 IOTelService、NodeOTelService 和 Copilot CLI 桥接实现。
- Copilot CLI 桥接访问 OpenTelemetry SDK v2 的内部 `_spanProcessors` 状态，SDK 结构变化可能造成风险。
- 源材料没有提供独立安装流程、完整测试结果或其他平台的专门适配说明。
- Claude SDK 不提供文件导出，CLI 运行时仅支持 `otlp-http`；CLI SDK 的单一 captureContent 设置同时影响调试面板和 OTLP。
如何安装
源材料未提供单独的安装器或客户端注册步骤。可检出仓库并定位该技能文件：
git clone https://github.com/microsoft/vscode.gitcd vscodecat .github/skills/otel/SKILL.md
该技能位于 .github/skills/otel/；如何将它注册到具体 Agent Skills 客户端，源材料没有说明。
如何使用
在支持 Agent Skills 的客户端中，在需要修改 Copilot Chat OTel 时明确说明任务，例如："请按照 .github/skills/otel/SKILL.md，为新的工具执行点添加 execute_tool 跨度，并同步更新 agent_monitoring.md、架构文档和测试。" 进行提交前，从 extensions/copilot/ 执行 npx tsc --noEmit --project tsconfig.json，再执行 npm test -- --grep "OTel\|Bridge"；随后检查 Aspire Dashboard 和 VS Code Agent Debug Log。该技能没有定义独立命令、脚本或参数接口。