使用 OpenTelemetry 监控 Agent 使用情况

本文介绍了如何为 VS Code 中的 Copilot Chat Agent 交互启用和配置 OpenTelemetry 监控。

Copilot Chat 可以通过 OpenTelemetry (OTel) 导出追踪 (traces)、指标 (metrics) 和事件 (events)，使您能够洞察 Agent 交互、LLM 调用、工具执行和令牌使用情况。所有信号名称和属性均遵循 OTel GenAI 语义规范，因此数据适用于任何兼容 OTel 的后端。

采集的内容

Copilot Chat 发出三种类型的 OTel 信号：追踪、指标和事件。

属性命名空间

Copilot Chat 在三个命名空间下发出 OTel 属性

旧版 copilot_chat.* 键将无限期持续发出，以便现有的收集器、仪表板和下游消费者无需更改即可继续工作。没有终止日期。本节中的表格将双重发出的行标记为旧版 (Legacy)，并指向首选键。

追踪 (Traces)

每个 Agent 交互都会产生一个分层跨度 (span) 树，以捕获完整的执行流

invoke_agent copilot                           [~15s]
  ├── chat gpt-4o                              [~3s]  (LLM requests tool calls)
  ├── execute_tool readFile                    [~50ms]
  ├── execute_tool runCommand                  [~2s]
  ├── chat gpt-4o                              [~4s]  (LLM generates final response)
  └── (span ends)

当 Agent 调用子 Agent（例如通过 runSubagent 工具）时，追踪上下文会自动传播。子 Agent 的 invoke_agent 跨度会作为父 Agent execute_tool 跨度的子级出现，从而在异步边界之间生成连接的追踪树。

invoke_agent 跨度

包装整个 Agent 编排，包括所有 LLM 调用和工具执行。

chat 跨度

每个 LLM API 调用对应一个跨度。

execute_tool 跨度

每个工具调用对应一个跨度。

execute_hook 跨度

每个钩子执行对应一个跨度（例如 PreToolUse, Stop）。

指标 (Metrics)

GenAI 语义规范指标

扩展特定指标

Agent 活动和结果指标跟踪所有界面（行内聊天、本地 Agent、Copilot CLI Agent、Claude Agent 和 Copilot 编码 Agent）的 Agent 代码更改

指标包含用于过滤的属性，例如 gen_ai.request.model, gen_ai.provider.name, gen_ai.tool.name, copilot_chat.edit.source 和 error.type。

活动

资源属性

所有信号都携带这些资源属性

使用 OTEL_RESOURCE_ATTRIBUTES 添加自定义资源属性，以便按团队、部门或其他组织边界进行过滤

export OTEL_RESOURCE_ATTRIBUTES="team.id=platform,department=engineering"

内容捕获

默认情况下，不会捕获提示内容、响应或工具参数。仅包含模型名称、令牌计数和持续时间等元数据。

要捕获完整内容，请启用 github.copilot.chat.otel.captureContent 在 VS Code 中打开 在 VS Code Insiders 中打开 设置，或设置 COPILOT_OTEL_CAPTURE_CONTENT=true。这将在跨度属性中填充完整的提示消息、响应消息、系统提示、工具架构、工具参数和工具结果。

启用 OTel 监控

当满足以下任何条件时，OTel 将被激活

• github.copilot.chat.otel.enabled 在 VS Code 中打开 在 VS Code Insiders 中打开 为 true
• github.copilot.chat.otel.dbSpanExporter.enabled 在 VS Code 中打开 在 VS Code Insiders 中打开 为 true
• 设置 COPILOT_OTEL_ENABLED=true
• 设置了 OTEL_EXPORTER_OTLP_ENDPOINT

VS Code 设置

打开设置（⌘, (Windows, Linux Ctrl+,)）并搜索 copilot otel

环境变量

环境变量的优先级始终高于 VS Code 设置。

命令

当 github.copilot.chat.otel.dbSpanExporter.enabled 在 VS Code 中打开 在 VS Code Insiders 中打开 为 true 时，Copilot Chat 会将 OTel 跨度持久化到本地 SQLite 数据库中。这对于离线检查或在不运行 OTLP 后端的情况下共享追踪数据非常有用。

后台 Agent 和 Claude Agent 的追踪结构

启用 OTel 后，所有 Agent 类型都会自动进行插桩。启用前台 Agent 追踪的相同设置也会启用 Copilot CLI 和 Claude Agent 追踪。

Copilot CLI (后台 Agent)

Copilot CLI SDK 在与聊天扩展相同的 VS Code 进程中运行，并生成丰富的追踪层次结构，包括子 Agent、权限、钩子和工具调用。扩展包装跨度 (invoke_agent copilotcli, 服务 copilot-chat) 是 SDK 原生跨度 (服务 github-copilot) 的父级。两者都会出现在您的收集器的同一个追踪中。

CLI 会话也会在 VS Code 的Agent Debug Log 面板中显示完整的 SDK 层次结构，与追踪查看器中显示的内容相同。调试面板即使在 OTel 导出被禁用时也能工作，因为 SDK 的内部追踪始终处于活动状态。

当 OTel 导出被禁用时，调试面板会自动捕获完整的提示和响应内容。当 OTel 导出被启用时， github.copilot.chat.otel.captureContent 在 VS Code 中打开 在 VS Code Insiders 中打开 设置将控制调试面板和 OTLP 导出的内容捕获。

Copilot CLI (终端会话)

使用 New Copilot CLI Session 启动的终端 CLI 会话在单独的进程中运行。启用 OTel 后，扩展会将 COPILOT_OTEL_ENABLED 和 OTEL_EXPORTER_OTLP_ENDPOINT 转发到终端进程。终端追踪显示为服务 github-copilot 下的独立根追踪，不会链接到扩展追踪。

CLI 运行时仅支持 otlp-http。当配置了 otlp-grpc 时，终端 CLI 仍使用 HTTP。在同一端口上同时提供两种协议的后端（例如 Aspire Dashboard）可以透明地工作。

Claude Agent

启用 OTel 后，Claude Agent 会话会生成服务 copilot-chat 下的扩展级跨度，并遵循 GenAI 语义规范。扩展通过拦截 Claude SDK 消息并代理通过本地 HTTP 服务器发出的 LLM 调用来创建跨度。

invoke_agent claude 根跨度包装了每个用户请求，并带有嵌套的 chat、execute_tool 和 execute_hook 跨度。当工具是 Agent（Claude 子 Agent 调用）时，子 chat 和 execute_tool 跨度会嵌套在下方，从而提供完整的子 Agent 可视性。

按 Agent 类型过滤

在您的追踪查看器中，按 service.name 过滤以查看特定 Agent 运行时的追踪

在 copilot-chat 服务中，通过 gen_ai.agent.name 区分 Agent 类型

与可观测性后端配合使用

Copilot Chat 的 OTel 输出适用于任何支持 OTLP 协议的后端。将 github.copilot.chat.otel.otlpEndpoint 在 VS Code 中打开 在 VS Code Insiders 中打开 设置或 OTEL_EXPORTER_OTLP_ENDPOINT 环境变量指向后端的 OTLP 摄取 URL，并配置导出器类型以匹配后端的协议 (otlp-http 或 otlp-grpc)。

Aspire Dashboard

Aspire Dashboard 是本地开发最简单的选择。它是一个带有内置 OTLP 端点和追踪查看器的单一应用程序，无需云账户。

您可以使用 Aspire CLI 启动仪表板

aspire dashboard run

或者从其 Docker 容器镜像运行相同的独立仪表板

docker run --rm -d -p 18888:18888 -p 4318:18890 --name aspire-dashboard \
  mcr.microsoft.com/dotnet/aspire-dashboard:latest

VS Code 配置

{
  "github.copilot.chat.otel.enabled": true,
  "github.copilot.chat.otel.captureContent": true
}

打开 https://:18888 并转到 Traces 以查看您的 Agent 交互跨度。

Jaeger

Jaeger 是一个开源的分布式追踪平台，直接支持 OTLP。

docker run -d --name jaeger -p 16686:16686 -p 4318:4318 jaegertracing/jaeger:latest

VS Code 配置

{
  "github.copilot.chat.otel.enabled": true,
  "github.copilot.chat.otel.otlpEndpoint": "https://:4318"
}

打开 https://:16686，选择服务 copilot-chat，然后选择 Find Traces。

Azure Application Insights

使用带有 Azure Monitor 导出器 的 OTel Collector，将 Copilot Chat 遥测数据转发到 Application Insights。将 VS Code 的 github.copilot.chat.otel.otlpEndpoint 在 VS Code 中打开 在 VS Code Insiders 中打开 设置指向收集器的 OTLP 端点，并配置收集器将其导出到您的 Application Insights 连接字符串。

有关带有现成仪表板的端到端设置，请参阅 使用 Grafana 监控 AI 编码 Agent。该指南介绍了如何运行 OTel Collector、将 VS Code 指向它，以及导入预制的 Azure Managed Grafana 仪表板。该仪表板可视化了来自 Application Insights 的 Copilot 操作、输入和输出令牌、聊天会话、工具调用以及每个模型的响应时间和 TTFT。

Langfuse

Langfuse 是一个开源的 LLM 可观测性平台，具有原生 OTLP 摄取功能，并支持 OTel GenAI 语义规范。

VS Code 配置

{
  "github.copilot.chat.otel.enabled": true,
  "github.copilot.chat.otel.otlpEndpoint": "https://:3000/api/public/otel",
  "github.copilot.chat.otel.captureContent": true
}

使用 OTEL_EXPORTER_OTLP_HEADERS 环境变量设置身份验证标头。有关详细信息，请参阅 Langfuse OTel 文档。

其他后端

任何兼容 OTLP 的后端均可工作，包括 Grafana Tempo、Honeycomb 和 Datadog。请参阅各后端的文档以获取 OTLP 摄取设置。

其他导出器示例

默认导出器是 otlp-http。您可以切换到 otlp-grpc、console 或 file 以适应您的后端或调试工作流程。

OTLP/gRPC

{
  "github.copilot.chat.otel.enabled": true,
  "github.copilot.chat.otel.exporterType": "otlp-grpc",
  "github.copilot.chat.otel.otlpEndpoint": "https://:4317"
}

控制台输出（快速调试）

{
  "github.copilot.chat.otel.enabled": true,
  "github.copilot.chat.otel.exporterType": "console"
}

基于文件的输出（离线或 CI）

{
  "github.copilot.chat.otel.enabled": true,
  "github.copilot.chat.otel.exporterType": "file",
  "github.copilot.chat.otel.outfile": "/tmp/copilot-otel.jsonl"
}

远程收集器的身份验证标头只能通过 OTEL_EXPORTER_OTLP_HEADERS 环境变量进行配置（例如 Authorization=Bearer your-token）。

安全与隐私

OTel 监控默认关闭，除非您显式启用，否则不会发出任何数据。您可以控制采集的内容及其去向。

相关内容

• Copilot 设置参考
• 排查 VS Code 中的 AI 问题
• OTel GenAI 语义规范
• 深入 LLM 调用：使用 OpenTelemetry 进行 GenAI 可观测性
• Aspire Dashboard 独立文档
• 视频：使用 OpenTelemetry 和 Aspire 追踪 Agent 会话