使用 OpenTelemetry 監控 Agent 使用狀況

本文說明如何在 VS Code 中啟用並設定 Copilot Chat Agent 互動的 OpenTelemetry 監控。

Copilot Chat 可透過 OpenTelemetry (OTel) 匯出追蹤 (Traces)、指標 (Metrics) 與事件 (Events)，讓您能掌握 Agent 互動、LLM 呼叫、工具執行與 Token 使用量。所有訊號名稱與屬性均遵循 OTel GenAI 語意慣例，因此資料可與任何相容 OTel 的後端搭配使用。

資料收集內容

Copilot Chat 會發出三種類型的 OTel 訊號：追蹤、指標與事件。

屬性命名空間 (Attribute namespaces)

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 Span 會顯示為父 Agent execute_tool Span 的子項目，從而在非同步邊界產生連貫的追蹤樹。

invoke_agent Span

包裝整個 Agent 編排，包含所有 LLM 呼叫與工具執行。

chat Span

每個 LLM API 呼叫一個 Span。

execute_tool Span

每個工具呼叫一個 Span。

execute_hook Span

每個 Hook 執行一個 Span (例如 PreToolUse, Stop)。

指標 (Metrics)

GenAI 語意慣例指標

擴充功能專用指標

Agent 活動與結果指標可追蹤跨所有介面 (內聯聊天、本地 Agent、Copilot CLI Agent、Claude Agent 與 Copilot Coding Agent) 的 Agent 程式碼變更。

指標包含用於篩選的屬性，例如 gen_ai.request.model, gen_ai.provider.name, gen_ai.tool.name, copilot_chat.edit.source 與 error.type。

活動

資源屬性 (Resource attributes)

所有訊號都帶有這些資源屬性

使用 OTEL_RESOURCE_ATTRIBUTES 新增自訂資源屬性，以便依團隊、部門或其他組織邊界進行篩選

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

內容擷取

預設情況下，不會擷取提示內容、回應或工具參數。僅包含模型名稱、Token 數與持續時間等中繼資料。

若要擷取完整內容，請啟用 github.copilot.chat.otel.captureContent 在 VS Code 中開啟 在 VS Code Insiders 中開啟 設定，或設定 COPILOT_OTEL_CAPTURE_CONTENT=true。這會將完整的提示訊息、回應訊息、系統提示、工具定義結構、工具參數與工具結果填入 Span 屬性中。

啟用 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 Span 持續寫入本地 SQLite 資料庫。這對於離線檢查或在不安裝 OTLP 後端的情況下分享追蹤資料非常有用。

後台與 Claude Agent 的追蹤結構

當啟用 OTel 後，所有 Agent 類型都會自動進行檢測。啟用前景 Agent 追蹤的相同設定，也會啟用 Copilot CLI 與 Claude Agent 的追蹤。

Copilot CLI (後台 Agent)

Copilot CLI SDK 在與聊天擴充功能相同的 VS Code 程序中執行，並產生包含子 Agent、權限、Hook 與工具呼叫的豐富追蹤階層。擴充功能封裝 Span (invoke_agent copilotcli，服務 copilot-chat) 為 SDK 原生 Span (服務 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 語意慣例的擴充功能層級 Span。擴充功能透過攔截 Claude SDK 訊息，並透過本地 HTTP 伺服器代理 LLM 呼叫來建立 Span。

invoke_agent claude 根 Span 會包裝每個使用者請求，其中包含巢狀的 chat、execute_tool 與 execute_hook Span。當工具為 Agent (Claude 子 Agent 呼叫) 時，子 chat 與 execute_tool Span 會巢狀在下方，提供完整的子 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 互動 Span。

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 Coding Agent。本指南逐步說明如何執行 OTel Collector、將 VS Code 指向它，以及匯入預先建置的 Azure Managed Grafana 儀表板。儀表板會將 Copilot 操作、輸入與輸出 Token、聊天工作階段、工具呼叫，以及 Application Insights 中的個別模型回應時間與 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 工作階段