---
title: "可觀測性"
description: "說明 Copilot SDK 的 OpenTelemetry 支援、trace context 傳播、tool spans 和生產化觀測清單。"
verifiedAt: "2026-05-06"
---

可觀測性（observability）讓團隊知道 agent 做了什麼、呼叫了什麼工具、哪裡失敗、耗時在哪裡。沒有 trace 和日誌，自定義 agent 不能進入生產流程。

> [!IMPORTANT]
> Copilot SDK 支援把 OpenTelemetry 配置到 CLI 程序，並在 SDK 和 CLI 之間傳播 W3C Trace Context（W3C 標準的追蹤上下文）。這條機制是把"agent 應用"接進現有可觀測性堆疊的關鍵，而不是另起一套日誌系統。

## 1. 官方能力邊界

GitHub 官方 observability 頁面說明：

- SDK 有內建 telemetry 支援。
- 可以配置 OpenTelemetry 到 CLI process。
- SDK 和 CLI 之間支援 W3C Trace Context 傳播。
- Outbound 方向可以透過 `onGetTraceContext` 提供 trace context。
- Inbound 方向，CLI 呼叫 tool handler 時，`traceparent` 和 `tracestate` 會出現在 `ToolInvocation` 物件上。

```mermaid
flowchart TD
    App["Your app span"] --> SDK["Copilot SDK"]
    SDK --> CLI["Copilot CLI process"]
    CLI --> Session["Session span"]
    Session --> Tool["Tool invocation"]
    Tool --> Handler["Your tool handler"]
    Handler --> Child["Child span"]
    Child --> Backend["Backend / API / DB"]

    style SDK fill:#dbeafe,stroke:#2563eb,stroke-width:2px
    style Tool fill:#fef3c7,stroke:#d97706,stroke-width:2px
    style Child fill:#dcfce7,stroke:#16a34a,stroke-width:2px
```

## 2. 要記錄什麼

最小觀測欄位：

- session id。
- user id 或 tenant id。
- model。
- prompt metadata，不記錄原始敏感內容。
- tool name。
- tool args 摘要。
- tool result 狀態。
- duration。
- error category。
- trace id。
- cost 或 request metadata。

不要把原始 prompt、金鑰、客戶資料、完整檔案內容直接打進日誌。

## 3. Trace 怎麼用

推薦 span 層級：

1. HTTP request 或 job span。
2. SDK session span。
3. model response span。
4. tool invocation span。
5. downstream API / DB span。

這樣排障時可以回答：

- 這次 agent 為什麼慢？
- 哪個 tool 呼叫失敗？
- 是模型、SDK、CLI、MCP server，還是外部 API 出錯？
- 某個使用者或團隊是否觸發異常用量？

## 4. 觀測和 hooks 要配合

Hooks 捕獲事件，OpenTelemetry 負責串 trace。推薦組合：

- `onSessionStart`：寫入 session metadata 和 trace context。
- `onUserPromptSubmitted`：記錄 prompt 型別和長度，不記錄敏感原文。
- `onPreToolUse`：記錄工具申請和許可權決策。
- `onPostToolUse`：記錄結果狀態、耗時和錯誤。
- `onErrorOccurred`：記錄 error category 和降級路徑。

## 5. 上線檢查

上線前至少確認：

- 每個 session 都能查到 trace id。
- 每個 tool call 都能查到 tool name 和結果狀態。
- 錯誤有分類，不是隻記錄 stack trace。
- 日誌已脫敏。
- 高風險操作能關聯到使用者和審批。
- 監控系統能按模型、功能、團隊、工具聚合。

<details>
<summary>深讀：可觀測性不是事後補日誌</summary>

Agent 行為是多階段的：prompt、planning、tool call、MCP、外部 API、response。事後只看最終文本，無法解釋中間發生了什麼。

生產級 agent 必須在設計時就帶 trace，而不是出事故後再 grep 日誌。
</details>

## 本章自檢

1. 是否能把一次使用者請求追蹤到 SDK session？
2. 是否能定位每個 tool call 的耗時和結果？
3. 是否避免記錄原始敏感內容？
4. 是否把 hooks 和 trace 串起來？
5. 是否能區分模型失敗、工具失敗和外部系統失敗？

透過標準：任意一次 agent 執行都能查到 trace、工具呼叫、錯誤和成本線索。

## 官方來源

- [OpenTelemetry instrumentation for Copilot SDK](https://docs.github.com/en/copilot/how-tos/copilot-sdk/observability/opentelemetry) —— GitHub 官方 OpenTelemetry 和 trace context 說明。
- [Quickstart for hooks](https://docs.github.com/en/copilot/how-tos/copilot-sdk/use-hooks/quickstart) —— GitHub 官方 hooks 事件入口。
- [Streaming events with Copilot SDK](https://docs.github.com/en/copilot/how-tos/copilot-sdk/use-copilot-sdk/streaming-events) —— GitHub 官方 streaming events。

## 接下來去哪

<Cards>
  <Card title="SDK Hooks" description="用 hooks 把關鍵事件送進 trace。" href="/zh-Hant/docs/github-copilot/official/09-sdk-and-custom-agents/sdk-hooks" />
  <Card title="指標和採用情況" description="SDK 應用也要進入組織級使用覆盤。" href="/zh-Hant/docs/github-copilot/official/08-security-governance/metrics" />
</Cards>
