For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /zh-tw/docs/modules/observability.md (or send Accept: text/markdown).
審計、分析與錯誤
用工作區上下文與脫敏的事件資料理解活動。
當操作失敗時查詢有用的資訊
可觀察性意味著檢視您的應用程式做了什麼。從執行 Web 伺服器的終端開始：重複一個失敗的操作並讀取第一個錯誤和任何相關 ID（連結來自同一請求的訊息的標籤）。尋求幫助時分享命令、時間和已清理的錯誤；不要共享 .env 檔案或令牌。
對於託管錯誤報告，請按照執行狀況和操作在 apps/web/.env.local 或主機的環境儀錶板中配置支援的監控設定。儲存並重啟伺服器。在測試環境中觸發受控測試失敗，並確認它在正確的工作區上下文中出現。正在配置的監視並不能證明它收到了事件。
ALERT_WEBHOOK_URL 是作業和終端 Webhook 傳遞失敗警報的可選 HTTPS 目標。如果需要，建立一個相容的傳入端點並將其URL伺服器端儲存起來；否則將其留空。要求代理模擬一次故障並準確確認一次警報，且文本中不包含任何秘密。請勿在此測試中觸發付費工作或客戶帳戶失敗。
保留工作區審計軌跡
審計記錄捕獲工作區內諸如供應商配置更新之類的變更。讀寫這些記錄前，先解析已認證的工作區；新增產品事件時也要保持這個邊界。
記錄動作與理解它所需的識別符號。供應商憑證等敏感值必須留在審計載荷與日誌之外。
採集產品事件
可觀測性包暴露 AnalyticsClient 介面卡與按工作區劃界的 AnalyticsEvent。每個事件帶有名稱、獨立身份、workspaceId 與可選屬性。
用 createObservability 把事件路由到你配置的分析客戶端。結構化屬性在投遞前會脫敏；同樣要把敏感的自由文本留在事件名與屬性值之外。
攜帶安全上下文上報錯誤
ErrorClient 用 workspaceId 標籤與結構化附加上下文捕獲異常。共享的可觀測性層在轉發給配置的客戶端之前，會清洗異常並脫敏敏感上下文。
用本地介面卡驗證捕獲的事件與異常，而不用呼叫監控供應商。在啟用外部目的地之前，測試工作區標籤仍在、憑證已被移除。
跨任務、作業和 Webhook 跟蹤請求
條目邊界建立一個 corr_<uuid> 相關 ID，將原始請求連結到它觸發的工作。 AI 任務提交會在任務負載和 ai_task_subscribed 事件上標記 id，每個計費 Webhook 接收器為每個請求建立一個，排程程式為每個分派作業建立一個。
相同的 id 包含 job.completed 和 ai_task_completed 事件屬性、captureException 額外內容、webhook_event ledger 有效負載和每個 webhook_delivery 有效負載元 — 因此它位於訂閱者收到的簽名主體內。丟失或格式錯誤的 ID 是可以容忍的：消費者建立一個新的 ID，而不是拒絕舊的行。
對實際故障發出警報
將 ALERT_WEBHOOK_URL 設定為接受 JSON POST 形狀的 {text, name,嚴重性, context} 的任何 HTTPS 端點； Slack 風格的傳入 Webhook 按原樣工作。警報是一勞永逸的，有五秒超時，失敗的傳遞會記錄一個控制台警告，並且在變數未設定時警報器不會執行任何操作。
傳送的警報是 job.failed （警告 - 作業處理程序丟擲或作業型別未知）和 webhook.delivery_failed （嚴重 - 僅當傳出交付在最終嘗試後達到終端故障時；普通重試保持安靜，每個交付行最多發出一次警報）。
測量持續時間並流式傳輸結構化日誌
serverObservability.measure 對非同步操作進行計時，並在成功和失敗時發出攜帶urationMs 的 <name>.duration 分析事件，而不掩蓋原始錯誤。 ai.task.execute 作業執行已打包，因此任務執行持續時間會落在配置的分析客戶端中。
serverObservability.logger 將每條記錄寫入一行 JSON 到 stdout，其中包含環境和服務基礎欄位；共享編輯層在發出任何行之前剝離秘密。