AI 代理可觀察性應能重建一次執行中的用戶請求、模型呼叫、工具選擇、政策決定、工具執行、下游副作用、重試和最終回應。日誌、指標、追蹤和評估各自回答不同問題，因此只收集模型文字並不足夠。
先選擇一項失敗或成本高昂的工作流程，再確認是否有一個識別碼能一路追蹤至權威後端結果。
追蹤完整的決策和執行路徑
sequenceDiagram
participant U as User
participant A as Agent
participant M as Model
participant P as Policy
participant T as Tool
participant B as Backend
U->>A: Request
A->>M: Model call
M-->>A: Tool selection
A->>P: Authorize identity and action
P-->>A: Decision
A->>T: Tool call with operation ID
T->>B: Downstream request
B-->>T: Authoritative result
T-->>A: Structured result
A-->>U: Response
使用 trace 表示一次執行、span 表示模型和工具工作，而生命週期可能比 trace 更長的副作用則使用 operation ID。在可行情況下，把 tool-call ID 傳入伺服器。數據庫數據列應能連回操作和 trace，但無需儲存完整追蹤本身。
OpenTelemetry 發佈了模型、代理和工具 span 的 GenAI 語意慣例。這些慣例仍在演進，因此應固定版本，並保留一個精簡的內部結構描述層，避免實驗性屬性名稱散落在應用程式各處。
擷取能解釋執行過程的事實
模型 span
記錄供應商、模型、回應識別碼、延遲、token 用量、結束原因、重試次數和提示範本版本。只有政策允許時才儲存完整提示；一般追蹤使用雜湊、經遮蔽的樣本或受保護參照可能已經足夠。
工具 span
記錄可見的工具名稱和版本、tool-call ID、經遮蔽的參數、選擇來源、執行時間、結果類別、重試次數和下游 operation ID。明確區分「模型選擇工具」、「政策允許工具」和「後端完成操作」。
政策和批准 span
記錄所代表的身份、租戶、資源、操作、政策版本、決定、原因碼和批准參照。絕不能記錄存取權杖或原始密鑰。遭拒絕的請求是預期的政策結果，不一定是應用程式錯誤。
復原 span
把恢復的工作連回原有工作流程和操作。記錄系統是在重試、對賬未知結果、補償已完成操作，還是停止並等待人員審查。失敗復原指南會說明這些分支。
使用指標找出模式，而不是解釋個別事件
匯總指標應包括：
- 成功、失敗、遭拒絕和取消的執行；
- 任務完成率和轉交人員處理的比率；
- 以百分位數顯示的模型和工具延遲；
- 每項任務和每個租戶的 token 與供應商成本；
- 工具選擇、驗證、授權和後端錯誤率；
- 重試、重複呼叫、循環停止和未知結果；
- 佇列延遲、進行中的執行和檢查點時間。
不要在 label 中加入提示文字、用戶 ID、工具參數或 trace ID 等種類不受限制的值。這些資訊應放在受保護的日誌或追蹤中，指標維度則應保持有限。
把日誌保存為個別且經遮蔽的事件
日誌適合記錄部署變更、政策決定、操作轉換、供應商錯誤和清理工作。使用穩定的事件名稱和結構化欄位，不要在每一層重複記錄完整的模型負載。
數據離開程序前便要完成遮蔽。密鑰、授權標頭、個人數據、檢索文件和工具輸出都可能出現在提示和錯誤之中；匯出後才取樣無法消除已經發生的暴露。
使用評估衡量質素
遙測會告訴你發生了甚麼，但如果沒有預期行為，它無法判斷回應是否有幫助、工具選擇是否正確。把生產環境失敗和抽樣追蹤加入有版本的評估集合，再於變更模型、提示或工具合約前執行評估。
AI 代理評估指南會區分確定性斷言、模型裁判、重複試驗和發佈門檻。
針對人員能採取的操作設定警示
對有明確應對方法的情況發出警示，例如部署後大量授權失敗、具破壞性的工具呼叫急增、追蹤中斷、反覆出現未知結果、佇列等待過久、超出支出限制，以及執行超出呼叫或時間預算。
不要為每個模型錯誤發出即時通知。請先按供應商、模型、工具、發佈版本和結果類別分組。儀表板可以呈現較嘈雜的質素變化；即時通知則應指向具體的限制或回復操作。
加入儀表板前先審計一條追蹤
選擇一次真實執行並手動追蹤。你能否找出提示版本、工具清單、政策決定、下游請求、業務結果、成本和每次重試？能否從 trace 找到受影響的操作，也從操作找到 trace？
下方提示會在不傳送數據的情況下對儲存庫執行這項審計。第一個缺少的連結，比另一張匯總圖表更適合作為 instrumentation 工作。