GitHub Copilot Agent OpenTelemetry：Prompt → Model → Tool → Token → Error 全链路监控

摘要： 本文讨论如何用 OpenTelemetry 监控 GitHub Copilot Agent：VS Code 中的 Copilot Chat 和 Copilot CLI 已经内置 OTel 导出能力，可以把每一次 Agent 任务的提示词、模型调用、工具执行、Token 用量和错误，按 OTel GenAI 语义约定输出到任何兼容后端。最重要的结论是：打开一个设置就能拿到完整链路，但要真正用于团队监控，还需要做三件事——统一经过 Collector 脱敏、Token 只按 chat span 汇总以免重复计算、把 CLI 与编辑器的链路分开看。本文适合希望了解 Copilot Agent 实际行为、成本和失败原因的开发者、团队负责人和平台工程师。功能默认关闭、开启后即可使用。读完后你将获得一套经过端到端测试的本地监控栈、Collector 脱敏配置和一个自动生成链路报告与告警的分析脚本。

配套项目源码：下载 Copilot OpenTelemetry 配套监控工具包（ZIP）。解压后阅读 README.md，并在本地填写环境变量。

核心结论

GitHub Copilot Agent 的全链路监控可以直接靠官方内置的 OpenTelemetry 完成：在 VS Code 中打开 github.copilot.chat.otel.enabled，每次 Agent 任务都会生成一棵 invoke_agent → chat / execute_tool / execute_hook 的 span 树，分别对应“提示词与会话、模型调用、工具执行、Hook 决策”，Token 和错误作为属性挂在各个 span 上。

• 覆盖范围：VS Code 官方文档说明，Copilot Chat 同时输出 traces、metrics 和 events 三类信号，前台 Agent、Copilot CLI 后台 Agent 和 Claude Agent 都会被自动采集。
• 默认安全：功能默认关闭，不开启时连 OTel SDK 都不加载；开启后默认也不采集提示词、回复和工具参数，需要单独打开内容采集。
• 最容易算错的地方：invoke_agent span 上的 Token 是子 span 的汇总值，SigNoz 文档提醒全部相加会大约重复计算一倍，统计时只汇总 chat span。
• 容易混淆的地方：在终端运行的 Copilot CLI 会话是独立的根链路，服务名为 github-copilot，不会和编辑器里的链路连在一起。
• 行动建议：个人先用 Jaeger 或 Aspire Dashboard 在本地看链路；团队上线前加一层 OTel Collector 统一脱敏，再接入 Grafana、Langfuse 等后端。

背景与主要变化

先说结论：Copilot 从“补全工具”变成会读文件、跑命令、调 MCP、开 PR 的 Agent 之后，只看“用了多少次”已经不够，需要像监控微服务一样监控它的每一步。

在 Agent 模式下，一次看似简单的请求，背后可能是十几次模型调用、几十次工具执行，还可能委派给子代理。没有链路数据时，团队很难回答这些问题：这次任务为什么这么慢？是哪个工具反复失败？Token 花在了哪里？缓存命中率是多少？Agent 有没有执行被 Hook 拦截的危险命令？

VS Code 官方文档《Monitor agent usage with OpenTelemetry》（2026 年 9 月 16 日更新）给出了答案：Copilot Chat 的所有信号名和属性都遵循 OTel GenAI 语义约定，能直接接入任何兼容 OTLP 的后端。属性分布在三个命名空间中：

除了 VS Code 扩展，GitHub 的 Copilot SDK 也内置 OTel，可以通过 TelemetryConfig 指定 OTLP 端点，并支持在 JSON-RPC 中传递 W3C Trace Context，让自建应用的 span 与 Copilot 的 span 出现在同一条链路中。更多 Copilot 使用教程，可以在站内 Copilot 专题 中找到。

核心功能拆解

结论先行：标题中的 Prompt → Model → Tool → Token → Error 五个环节，在 Copilot 的遥测中都有明确的对应字段，理解这张对应表是搭建监控的前提。

Span 树：一次 Agent 任务长什么样

官方文档给出的典型结构如下：

invoke_agent copilot                    [~15s]
  ├── chat gpt-4o                       [~3s]   模型决定调用工具
  ├── execute_tool readFile             [~50ms]
  ├── execute_tool runCommand           [~2s]
  ├── chat gpt-4o                       [~4s]   模型生成最终回答
  └── (span 结束)

当 Agent 通过 runSubagent 等工具委派子代理时，链路上下文会自动传递，子代理的 invoke_agent span 会挂在父 Agent 的 execute_tool span 下面，形成跨异步边界的完整链路。

五个环节与字段对应

execute_hook span 值得单独关注：每次 PreToolUse、Stop 等 Hook 执行都会记录决策结果和耗时。结合上一篇 Agent 安全文章中的 Hook 拦截规则，你可以统计 Agent 被拦截了多少次、拦截的是哪类操作。

指标与事件

指标分为三组。GenAI 标准指标有模型调用耗时 gen_ai.client.operation.duration 和 Token 用量 gen_ai.client.token.usage。扩展指标包括工具调用次数与耗时、Agent 端到端耗时、每次调用的模型往返次数、首 Token 时间等。第三组是 Agent 产出指标，例如编辑被接受或拒绝的次数、被接受编辑增删的代码行数、AI 生成代码在接受后的“存活率”，以及通过 Agent 创建的 PR 数量。

事件方面，gen_ai.client.inference.operation.details 记录每次模型调用的完整元数据，copilot_chat.tool.call 记录每次工具调用的耗时与错误，copilot_chat.edit.survival 周期性测量 AI 代码被保留的比例。

适用人群与使用场景

结论：个人开发者用它排查“Agent 为什么慢、为什么失败”，团队负责人用它看成本与采纳效果，平台团队用它做统一审计与告警。

对个人开发者，最实用的场景是排查单次任务：打开链路就能看到哪次模型调用首 Token 很慢、哪个终端命令失败了三次、子代理做了什么。如果不想搭任何后端，官方还提供了本地 SQLite 导出和 Agent Debug Log 面板。

对团队负责人，可以按 OTEL_RESOURCE_ATTRIBUTES 中的团队标签，统计各团队的模型调用分布、Token 用量、缓存命中率，以及编辑接受率和代码存活率，用数据而不是感觉评估 Agent 的实际价值。

对平台和安全团队，可以通过 Copilot 托管设置统一下发遥测目的地，所有开发者的 VS Code 和 Copilot CLI 都会把数据送到指定的 Collector，再按需审计 MCP 工具调用、Hook 拦截和失败命令。

不适合的场景：如果你关心的是按组织统计的计费和席位使用情况，应以 GitHub 提供的用量与账单数据为准；OTel 中的 Token 是客户端观察到的调用明细，不等同于账单。关于 Agent 的更多实践，可以参考站内 Agent 实战教程。

安装、配置或使用步骤

结论：按以下 7 步，大约 20 分钟可以在本地搭好“Copilot → Collector（脱敏）→ Jaeger + 分析报告”的完整链路。

1. 启动监控栈：解压本文配套的 copilot-otel-kit.zip，执行 docker compose up -d，启动 OTel Collector（contrib 0.161.0）和 Jaeger。端口只绑定在本机。
2. 开启 VS Code 遥测：把 config/vscode-settings.json 合并进 VS Code 用户设置，核心是把 github.copilot.chat.otel.enabled 设为 true，端点指向 http://localhost:4318。
3. 开启 Copilot CLI 遥测：在终端执行 source config/copilot-cli.env.sh，设置 COPILOT_OTEL_ENABLED=true 和 OTEL_EXPORTER_OTLP_ENDPOINT。官方说明 CLI 只支持 otlp-http。
4. 添加团队标签：通过 OTEL_RESOURCE_ATTRIBUTES="team.id=YOUR_TEAM,department=engineering" 给所有信号加上组织维度，便于后续筛选。
5. 跑一次 Agent 任务：在 Agent 模式下让 Copilot 完成一个包含读文件、跑命令的任务。OTel 会批量发送数据，稍等几秒。
6. 查看链路：打开 http://localhost:16686，在 Jaeger 中选择服务 copilot-chat（编辑器）或 github-copilot（CLI 与 SDK）。
7. 生成链路报告：执行 python3 analyzer/copilot_trace_report.py data/copilot-traces.jsonl，得到按模型的 Token 汇总、工具失败统计、告警和最近几次任务的完整链路。

VS Code 设置片段：

{
  "github.copilot.chat.otel.enabled": true,
  "github.copilot.chat.otel.exporterType": "otlp-http",
  "github.copilot.chat.otel.otlpEndpoint": "http://localhost:4318",
  "github.copilot.chat.otel.captureContent": false
}

Collector 的关键是脱敏处理器。即使有开发者在客户端打开了内容采集，Collector 也会统一删除提示词、回复、工具参数和结果：

processors:
  attributes/redact:
    actions:
      - { key: gen_ai.input.messages, action: delete }
      - { key: gen_ai.output.messages, action: delete }
      - { key: gen_ai.tool.call.arguments, action: delete }
      - { key: gen_ai.tool.call.result, action: delete }
      - { key: github.copilot.tool.parameters.command, action: delete }
      - { key: copilot_chat.hook_input, action: delete }

完整配置已使用 otelcol-contrib 0.161.0 的 validate 命令校验通过。远程 Collector 需要鉴权时，官方说明认证头只能通过 OTEL_EXPORTER_OTLP_HEADERS 环境变量设置，例如 Authorization=Bearer YOUR_TOKEN。

实际工作流示例

结论：以一次“迁移服务并开 PR”的 Agent 任务为例，链路报告能在一屏内回答“慢在哪、错在哪、花了多少、有没有被拦截”。

端到端测试结果

为了验证配置和分析脚本，本文在测试环境中启动了真实的 otelcol-contrib 0.161.0，并用 OpenTelemetry Python SDK 按官方文档的属性名构造了两次模拟 Agent 任务：第一次包含读文件、一次失败的终端命令、委派子代理修复测试、调用 MCP 工具开 PR；第二次包含一次被 PreToolUse Hook 拦截的删除命令。模拟数据中故意放入了 API_KEY=sk-test、敏感文件路径和危险命令文本。

测试脚本的检查结果：

✅ Collector 已写出 1 行 OTLP JSON
✅ 提示词、工具参数、Hook 输入均未写入文件
✅ deployment.environment 已写入

分析脚本生成的报告摘录如下（这是模拟数据，不是真实 Copilot 的运行结果）：

Agent 调用 2 次｜模型调用 5 次｜工具调用 5 次｜工具失败率 20%｜缓存命中率 0.612

- Model claude-opus-5-5 0.05s｜Token 入 18000 / 出 600 / 缓存读 12000｜结束原因 ['tool_calls']
- Tool readFile（function） 20ms
- Tool runInTerminal（function） 200ms｜❌ Error CommandFailed: npm test exited with code 1
- Tool runSubagent（function） 71ms
  - Subagent test-fixer
    - Model claude-sonnet-5 0.05s｜Token 入 9000 / 出 900 / 缓存读 2000
    - Tool editFile（function） 20ms
- Tool mcp_github_create_pr（extension） 20ms
- Model claude-opus-5-5 0.05s｜Token 入 21000 / 出 1200 / 缓存读 17500｜结束原因 ['stop']

- Hook PreToolUse 决策 block

⚠️ 工具失败率 20% 超过阈值 10%

缓存命中率 0.612 由三个模型的缓存读取之和除以输入之和得出（39,500 ÷ 64,500），与手工核对一致。

测试中踩到的两个坑

第一个坑来自测试脚本本身：第一次运行时，“敏感内容已删除”的检查显示通过，实际上是 Collector 根本没有收到数据，文件是空的。原因是发送脚本调用了全局的 trace.get_tracer()，却没有注册自己创建的 provider，span 全部进入了默认的无操作实现，而且没有任何报错。修正后，测试脚本在文件为空时会直接判定失败。这个教训对所有监控配置都适用：检查“没有敏感数据”之前，先确认确实有数据。

第二个坑是 Token 口径。报告中第一次任务的 Token 包含了子代理的调用，因为子代理与父 Agent 处于同一条链路。分析脚本只汇总 chat span，避免与 invoke_agent 上的汇总值重复。

建议配置的告警规则

链路数据真正产生价值，是在异常出现时主动提醒。下面是一组起步规则，字段均来自官方文档，阈值需要按团队的实际情况调整：

配套脚本已内置前四条规则，可以用 --json 输出后接入企业微信、飞书或邮件通知。

对比与选型建议

结论：本地调试用 Aspire Dashboard 或 Jaeger，LLM 专项分析用 Langfuse，团队级监控用 Collector 接入 Grafana 或现有 APM；无论选哪个，都建议在前面放一层 Collector。

• Aspire Dashboard：官方称其为本地开发最简单的选项，一个应用自带 OTLP 端点和链路查看器，不需要云账号，可以直接用 aspire dashboard run 或 Docker 启动。
• Jaeger：开源分布式追踪平台，直接接收 OTLP，适合熟悉传统 APM 的团队。
• Langfuse：开源 LLM 可观测平台，原生支持 OTLP 和 GenAI 语义约定，适合关注提示词和回复质量的团队，但通常需要开启内容采集。
• Azure Application Insights + Grafana：官方文档介绍了通过 Collector 转发到 Application Insights，并导入现成的 Azure Managed Grafana 仪表盘，可以看到操作、Token、会话、工具调用和各模型的首 Token 时间。
• 其他后端：Grafana Tempo、Honeycomb、Datadog、SigNoz、OpenObserve、Last9 等兼容 OTLP 的平台都可以接入，其中 SigNoz 提供了现成的 Copilot 仪表盘模板。
• 不搭后端：开启 dbSpanExporter 后，span 会保存到本地 SQLite，可用 Chat: Export Agent Traces DB 命令导出；也可以用 file 导出器写成 JSON Lines。

为什么建议始终经过 Collector：客户端直连后端时，每个开发者的内容采集设置可能不同；Collector 可以统一脱敏、追加团队和环境标签、同时导出到多个后端。Copilot CLI 的一个 GitHub Issue 也提到，目前 CLI 没有接口让 Agent 给原生 span 追加交付上下文，如需关联提交、流水线等信息，可以在 Collector 或 OTLP 代理中补充。

风险、限制与注意事项

结论：遥测本身会成为新的敏感数据源，开启前要想清楚采集什么、存在哪里、谁能看。

内容采集的风险。 官方提醒，开启 captureContent 后会采集代码、文件内容和用户提示词，只应在可信环境中开启。本文的 Collector 默认删除这些字段；如果团队确实需要分析提示词质量，建议单独设立访问受控的后端，并用 maxAttributeSizeChars 限制单个属性的长度。

只设置一个环境变量也会开启遥测。 官方说明，只要设置了 OTEL_EXPORTER_OTLP_ENDPOINT，Copilot 的 OTel 就会启用。如果开发机上其他工具已经设置了这个变量，Copilot 数据可能会被发送到意料之外的地方，需要检查。

企业托管设置的优先级。 企业可以通过 Copilot 托管设置的 telemetry 区块统一下发 OTel 配置，托管值会覆盖用户设置；但官方也说明，在 Copilot Chat 扩展中，OTel 环境变量仍然可以覆盖托管值，因此需要从受管设备上移除冲突的环境变量。托管配置在 Copilot Chat 启动后才到达时，可能需要重新加载窗口。

链路可能是断开的。 终端里运行的 Copilot CLI 会话，与编辑器中的链路是相互独立的根链路；在编辑器中调用的后台 Copilot Agent 则会由扩展的包装 span 与 SDK 原生 span 连在同一条链路里。做统计时，要按 service.name 和 gen_ai.agent.name 区分来源。

统计口径。 Token 只按 chat span 汇总；Copilot 不输出总 Token 字段，总量需要用输入加输出计算。MCP 服务器名默认只以 SHA-256 哈希形式出现，这是为了保护隐私，需要识别具体服务器时要开启内容采集。

数据安全与访问控制。 Collector 和后端应只在内网或本机开放，远程传输使用 HTTPS 和认证头；认证令牌放在环境变量或密钥管理系统中，不要写进仓库。链路数据中包含仓库地址、分支和提交号，同样属于内部信息，应设置保留期限。

遥测不等于控制。 OTel 只能记录 Agent 做了什么，不能阻止它做什么。高风险操作的拦截仍要依靠 Hook、权限设置和人工审批，监控的作用是让你及时发现问题并复盘。

事实依据与来源

官方已确认的事实： Copilot Chat 输出 traces、metrics、events 三类信号并遵循 OTel GenAI 语义约定，三个属性命名空间及旧字段无下线日期，span 树结构与子代理链路传递，各类 span 的属性，指标与事件列表，资源属性，内容采集默认关闭，开启条件、VS Code 设置与环境变量及其优先级，认证头只能通过环境变量设置，本地 SQLite 导出，企业托管设置的优先级，CLI 终端会话为独立根链路且只支持 otlp-http，各后端的接入方式，以及默认关闭、无主动回传等安全说明，均来自 VS Code 官方文档《Monitor agent usage with OpenTelemetry》。Copilot SDK 的 TelemetryConfig 与 W3C Trace Context 传递来自 GitHub 官方文档。

第三方资料： invoke_agent 上的 Token 为汇总值、全部相加会重复计算、Copilot 不输出总 Token 字段，来自 SigNoz 的 Copilot 仪表盘文档；CLI 日志位置与调试级别来自 OpenObserve 文档；CLI 无法给原生 span 追加交付上下文，来自 github/copilot-cli 仓库的 Issue。

实测与编辑判断： Collector 配置已用 otelcol-contrib 0.161.0 校验；端到端测试使用真实 Collector 和 OpenTelemetry Python SDK 发送按官方属性名构造的模拟数据，并非真实 Copilot 的运行数据，真实导出中的字段可能多于或少于模拟数据。统一经过 Collector、Token 只按 chat span 汇总、告警阈值等为本文实施建议。

内容核验日期： 2026 年 9 月 25 日。

FAQ

怎么开启 GitHub Copilot 的 OpenTelemetry？

在 VS Code 设置中把 github.copilot.chat.otel.enabled 设为 true，默认会以 otlp-http 协议发送到 http://localhost:4318。也可以设置环境变量 COPILOT_OTEL_ENABLED=true，或者直接设置 OTEL_EXPORTER_OTLP_ENDPOINT，后者同样会启用遥测。环境变量的优先级高于 VS Code 设置。

默认会采集我的代码和提示词吗？

不会。官方文档说明，默认只采集模型名、Token 数量、耗时等元数据，提示词、回复和工具参数需要通过 captureContent 设置或 COPILOT_OTEL_CAPTURE_CONTENT=true 单独开启。功能本身默认关闭，关闭时不加载 OTel SDK，也没有向其他地方回传数据的行为。

Copilot CLI 也能监控吗？

能。Copilot CLI 使用相同的环境变量开启，数据的服务名为 github-copilot。需要注意两点：CLI 只支持 otlp-http，即使配置了 gRPC 也会使用 HTTP；在终端中运行的 CLI 会话是独立的根链路，不会和 VS Code 编辑器中的链路连接在一起。

为什么我统计的 Token 比实际多了一倍？

很可能是把所有 span 的 Token 都加在了一起。invoke_agent span 上的 Token 是其子 span 的汇总值，SigNoz 文档因此建议只汇总 chat span。Copilot 也不输出总 Token 字段，总量需要用输入 Token 加输出 Token 计算。

能看到 Agent 调用了哪些 MCP 工具吗？

能。MCP 工具的 execute_tool span 中，gen_ai.tool.type 为 extension，并记录被调用的 MCP 工具名。MCP 服务器名默认只以 SHA-256 哈希形式记录，开启内容采集后才会出现明文服务器名。

不想搭后端，有没有更简单的办法？

有三种方式。开启 github.copilot.chat.otel.dbSpanExporter.enabled 后，span 会保存到本地 SQLite，可用命令导出为数据库文件；把导出器类型设为 file，数据会写成 JSON Lines；或者直接在 VS Code 的 Agent Debug Log 面板中查看后台 Agent 的完整链路。本地可视化推荐 Aspire Dashboard，一条命令即可启动。

企业如何统一收集所有开发者的数据？

管理员可以通过 Copilot 托管设置中的 telemetry 区块，用 MDM、服务端管理的 GitHub 账号策略或磁盘上的 managed-settings.json 下发 OTel 配置，同时适用于 Copilot Chat 扩展和 Agent 主机进程。托管值会覆盖用户设置，但 OTel 环境变量在扩展中仍可覆盖托管值，所以要清理受管设备上的冲突变量。

OTel 数据能代替 Copilot 的账单统计吗？

不能。OTel 记录的是客户端观察到的每次调用明细，适合排查性能、失败和使用模式；计费、席位和组织级用量应以 GitHub 提供的账单与用量数据为准。两者可以配合使用，例如用 OTel 找出 Token 消耗最高的任务类型，再对照账单评估优化效果。

参考来源

• VS Code Docs：Monitor agent usage with OpenTelemetry
• GitHub Docs：OpenTelemetry instrumentation for Copilot SDK
• SigNoz：GitHub Copilot Dashboard
• SigNoz：GitHub Copilot OpenTelemetry Monitoring
• OpenObserve：GitHub Copilot Tracing
• GitHub Issue：允许 Copilot CLI 给原生 span 追加交付上下文
• Last9：GitHub Copilot 集成文档

内容核验日期：2026 年 09 月 25 日