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/web/setup-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，其中包含環境和服務基礎欄位；共享編輯層在發出任何行之前剝離秘密。

安裝與配置

1. 設定 SENTRY_DSN 以報告錯誤；捕獲的異常會帶有請求關聯 ID 和工作區標籤。

2. 設定 NEXT_PUBLIC_POSTHOG_KEY 和 NEXT_PUBLIC_POSTHOG_HOST 以啟用產品分析；它們按設計會公開給瀏覽器。

3. 將 ALERT_WEBHOOK_URL 設定為相容 Slack 的端點以接收失敗告警；應用會傳送包含 {text, name, severity, context} 的 JSON。

SENTRY_DSN=https://…@….ingest.sentry.io/…

NEXT_PUBLIC_POSTHOG_KEY=phc_…
NEXT_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com

ANALYTICS_PROVIDER=off    # off | local | plausible | posthog
# ANALYTICS_SITE_ID=
# ANALYTICS_HOST=

ALERT_WEBHOOK_URL=https://hooks.slack.com/services/…

實現流程

可觀測性層會清理異常內容，並在轉發前隱藏已知金鑰；但自由填寫的事件文本由編寫者負責，請勿把憑據放入事件名稱或屬性值。

本地介面卡允許測試斷言捕獲的事件和異常，不會呼叫 Sentry 或 PostHog；本地執行無需這些變數。

事件已開始流動？繼續閱讀《設定自定義域名》。

驗證與排障

觸發測試異常並確認它進入 Sentry 且金鑰已從資料中移除，然後檢查配置的失敗是否會向 ALERT_WEBHOOK_URL 傳送 POST。如果收不到事件，請確認 DSN/金鑰配對正確，且伺服器能訪問該主機。