跳至主要內容
Telemetry
瀏覽說明文件
指南更新於 2026年7月29日由 Telemetry 編輯團隊和產品團隊審查閱讀約需 3 分鐘

讓程式設計代理使用這篇文件

開啟 Claude Code、Codex、Cursor 或其他編碼代理的集中提示包,然後將其適應此處介紹的工作流程。

本頁內容
  1. 從有界訊號開始
  2. 範圍受影響的路線和發布
  3. 建立並儲存時間線
  4. 驗證恢復情況

使用 SQL 回應故障

當回應者以相同的順序回答相同的問題時,事件回應會更快:更改何時開始、哪些使用者和工作流程受到影響、發生了什麼變化以及系統是否已恢復?結構化事件保留了這些維度,因此您可以從廣泛的訊號轉移到可防禦的時間線,而無需搜尋非結構化訊息。

將 HTTP 5xx 峰值與版本和受影響的結帳路線關聯起來的事件儀表板

從廣泛開始,然後保留路線併發布可以解釋變化的維度。

從有界訊號開始

選擇一個穩定的完成事件,例如 api_request_completed,然後比較完整的五分鐘桶。將路由範本、發布識別符號、狀態、錯誤類別和安全帳戶識別符號保留為單獨的欄位。

SELECT
  date_bin(INTERVAL '5 minutes', timestamp_utc, TIMESTAMP '1970-01-01') AS bucket,
  COUNT(*) AS requests,
  100.0 * SUM(CASE WHEN status = 'failed' THEN 1 ELSE 0 END)
    / NULLIF(COUNT(*), 0) AS error_rate_pct
FROM api_request_events
WHERE timestamp_utc >= now() - INTERVAL '2 hours'
GROUP BY bucket
ORDER BY bucket;

不要從一個小容量的儲存桶中宣告事件。將費率與請求量以及該服務的運營目標進行比較。

範圍受影響的路線和發布

一旦開始時間明確,保留可以解釋變化的維度。按路由和發布進行分組,保留最小數量閾值,並按失敗請求和比率進行排名。

SELECT
  route_template,
  release,
  COUNT(*) AS requests,
  SUM(CASE WHEN status = 'failed' THEN 1 ELSE 0 END) AS failed_requests,
  100.0 * SUM(CASE WHEN status = 'failed' THEN 1 ELSE 0 END)
    / NULLIF(COUNT(*), 0) AS error_rate_pct
FROM api_request_events
WHERE timestamp_utc >= now() - INTERVAL '30 minutes'
GROUP BY route_template, release
HAVING COUNT(*) >= 20
ORDER BY failed_requests DESC, error_rate_pct DESC;

僅當該維度可以更改回應時,才使用 error_type、依賴項、區域或隱私安全帳戶識別符號重複查詢。避免使用原始請求正文、授權標頭、電子郵件和自由格式的異常文字。

建立並儲存時間線

在事件日誌中記錄每個假設、查詢、時間視窗、結果和操作。將最有用的查詢儲存在儀表板旁邊,以便第二個回應者可以重現範圍。使用準確的 UTC 時間戳標記部署、功能標記更改、依賴項故障和恢復操作。

使用 API 錯誤率配方 對受影響的路由進行排名,使用 發布迴歸配方 比較建置,並使用 錯誤預算燃燒配方 將事件與可用性目標聯絡起來。當回應者需要明確的客戶影響合約時,請從 incident_impact_observed 事件模式 開始。

驗證恢復情況

回滾或設定更改本身並不是恢復。等待完整的儲存桶,驗證錯誤率和延遲是否返回到預期範圍,並檢查流量是否沒有消失。繼續觀察足夠長的視窗以涵蓋延遲的重試和後台工作。

事件發生後,將經過驗證的檢測查詢轉換為儀表板或警示,記錄其最小數量和所有權,並在回應者缺乏隔離影響所需的安全欄位時更新事件合約。 警示故障排除指南 解釋瞭如何在不產生噪音的情況下測試生成的通知路徑。

相關產品功能

將審查的 SQL 提升到自有閾值和回應工作流程中。

內容責任與技術參考

Telemetry 編輯團隊負責維護本文;產品團隊審查功能行為、範例和適用範圍。

檢視編輯規範