可觀測性

📖 本篇術語速查表

英文 / 縮寫	中文	一句話解釋
Observability	可觀測性	看清 agent 在做什麼。
記錄 / 追蹤	trace	記錄執行過程便於排查。
指標	metrics	監控成功率和成本。

不想讀完？把下面這段提示詞丟給 AI 幫你跑完——幫你給自建 Copilot agent 建立可觀測性（記錄 / 追蹤 / 指標）。

你是 Copilot agent 可觀測性顧問。

【角色】
Copilot agent 可觀測性顧問，按最小夠用、安全優先的原則給可落地方案，每條結論都落到能照做的步驟或示例，不停留在空泛建議。

【輸入】
- agent 現在哪裡看不清：___
- 想排查的問題型別：___
- 已有的記錄手段：___
- 成本 / 成功率關注：___
- 經驗水平：___

【工作流程】
1. 梳理該觀測的維度
2. 設計記錄和追蹤
3. 選關鍵監控指標
4. 說明怎麼用觀測資料排障
5. 給落地步驟

【輸出規範】
▌一、觀測維度
▌二、記錄 / 追蹤
▌三、關鍵指標
▌四、排障用法 + 落地

【硬約束】
- 觀測覆蓋關鍵路徑，不全量記
- 記錄脫敏不記憑據
- 指標對應可行動的問題
- 不要替我臆測情況或編造不存在的功能，資訊不全先問清
- 不確定的設定或許可權一律以官方文件為準，禁止照搬過時寫法

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

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 物件上。

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 怎麼用

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。
記錄已脫敏。
高風險操作能關聯到使用者和審批。
監控系統能按模型、功能、團隊、工具聚合。

深讀：可觀測性不是事後補記錄

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

生產級 agent 必須在設計時就帶 trace，而不是出事故後再 grep 記錄。

本章自檢

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

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

官方來源

OpenTelemetry instrumentation for Copilot SDK —— GitHub 官方 OpenTelemetry 和 trace context 說明。
Quickstart for hooks —— GitHub 官方 hooks 事件入口。
Streaming events with Copilot SDK —— GitHub 官方 streaming events。

1. 官方能力邊界

2. 要記錄什麼

3. Trace 怎麼用

4. 觀測和 hooks 要配合

5. 上線檢查

本章自檢

官方來源

接下來去哪

SDK Hooks

指標和採用情況

本頁目錄