從臨時日誌遷移到結構化事件和 SQL
自由格式的日誌對於本地除錯很有用，但重複出現的操作和產品問題需要穩定的欄位、明確的單位和可審查的定義。遷移不需要替換每個現有的日誌或可觀測性工具。從一個生產工作流程開始，在現有日誌旁邊發出一個有界完成事件，並在更改儀表板或警示之前證明其 SQL 回答了預期的問題。 結構化日誌管理指南 解釋了更大的操作模型。
本指南使用 API 請求作為範例，但相同的順序適用於作業、Webhook、AI 執行、計費工作流程和應用程式級資料庫操作。
1. 選擇一個決策，而不是整個日誌流
從一個已經消耗工程時間的問題開始：
- 哪些 API 路由具有有意義的 5xx 速率？
- 哪些限速請求在重試後會恢復？
- 哪些工作型別正在增加排隊年齡？
- 哪個提示版本產生的可接受結果較少？
- 哪個資料庫操作指紋在一個請求中重複？
寫下答案將支援的決定、所有者、報告視窗以及解釋費率所需的最小數量。這可以防止事件成為應用程式記憶體中每個可用值的副本。
當診斷日誌仍然有用時，保留堆疊追蹤或本地上下文的診斷日誌。結構化事件是所選問題的持久分析契約。
2. 盤點當前意義
在更改儀器之前，儲存現有的搜尋或儀表板定義並檢查幾個實際結果。記錄：
- 哪些訊息或屬性標識工作流程。
- 如何區分成功、重試、取消、終端失敗。
- 哪個時間戳標誌著工作的開始或完成。
- 重試是否建立額外記錄。
- 哪些欄位包含機密、個人資料、原始有效負載或無限文字。
- 哪些排除和最小量規則僅存在於操作員的記憶中。
該清單是語義基線，而不是舊結果正確的承諾。如果現有的搜尋將嘗試與邏輯請求混合在一起，請記錄該限制，而不是默默地複製它。
3. 定義一個有界完成事件
更喜歡一個事件而不是一個已完成的工作單元。使用明確的數字、布林值、單位和受控類別。僅當需要關聯時才使用路由範本而不是原始 URL、使用分類錯誤而不是不受限制的異常文字以及內部識別符號。
{
"event_name": "api_request_completed",
"request_id": "req_7d91",
"route_template": "/api/projects/:id/sync",
"method": "POST",
"status_code": 503,
"outcome": "dependency_failed",
"latency_ms": 842,
"attempt_number": 2,
"release": "2026.07.2",
"environment": "production",
"schema_version": 1
}
請勿傳送授權標頭、cookie、請求正文、連線字串、原始提示、webhook 負載、付款詳細資訊或不受限制的客戶內容。部署前檢視欄位允許列表。請參見 脫敏敏感資料 和 高基數字段。
4. 在現有日誌旁邊發出
執行有時間限制的雙寫週期。該應用程式繼續生成您的團隊所依賴的診斷記錄，同時還發出新事件。在中央邊界新增工具（中介軟體、作業包裝器、Webhook 排程程式或資料庫客戶端包裝器），以便成功和失敗路徑使用相同的時鐘和欄位名稱。
儀器不得將成功的應用程式變成失敗的應用程式。將分析交付視為單獨的、有限制的操作，具有明確的超時和適合您的系統的重試行為。在強制實施之前，請驗證缺失的設定是否在每個已部署的環境中安全回退。
在雙重寫入期間，監視事件攝取新鮮度、必填欄位完整性、模式版本和重複識別符號。 事件攝取新鮮度、必填欄位空率 和 重複的事件 ID 配方提供可重複使用的檢查。
5.將問題翻譯成複習過的SQL
從事件契約開始，而不是音譯文字搜尋表示式。對於 API 錯誤，保留計數和分母：
SELECT
route_template,
COUNT(*) AS requests,
SUM(CASE WHEN status_code >= 500 THEN 1 ELSE 0 END) AS errors,
100.0 * SUM(CASE WHEN status_code >= 500 THEN 1 ELSE 0 END)
/ NULLIF(COUNT(*), 0) AS error_rate_pct
FROM api_request_completed
WHERE timestamp_utc >= now() - INTERVAL '24 hours'
AND environment = 'production'
GROUP BY route_template
HAVING COUNT(*) >= 20
ORDER BY error_rate_pct DESC;
檢視時間邊界、狀態定義、重試粒度、後期事件處理和最小量。測試至少一項成功、預期失敗、重試、重複、空和延遲事件。如果查詢在操作上變得很重要，請在其旁邊儲存確定性固定裝置和預期結果。
SQL配方庫 包括型別化模式、只讀 DataFusion SQL、合成輸出、視覺化、邊緣案例、儀表板計劃和警示指導。 瀏覽器 SQL 遊樂場 在本地執行支援的裝置，而無需將範例行傳送到 Telemetry。
6. 比較語義，而不僅僅是總數
在同一個關閉的 UTC 視窗中執行舊的和新的答案。研究差異而不是針對任意精確匹配：
- 較低的新計數可能意味著重試被正確摺疊。
- 較高的計數可能會暴露訊息模式搜尋忽略的失敗。
- 不同的路由排名可能是由於穩定的路由範本替換了原始 URL 而導致的。
- 最近的小不匹配可能是由延遲事件或不完整的時間段引起的。
- 歷史資料可能不包含新合約引入的欄位。
為每個差異建立簡短的調節記錄：原因、可接受的行為、所有者以及事件或查詢是否需要更改。在新的 SQL 重現舊錯誤之前，請勿對其進行調整。
7、分階段推廣
一次移動一個消費者：
- 使用新的 SQL 製作探索性報告。
- 儲存審閱的查詢及其所有者和定義。
- 建置一個儀表板，除了費率之外還保留交易量並使用完整的儲存桶。
- 在非尋呼或影子模式下執行任何建議的警示。
- 新增持續時間規則、最小音量和回應連結。
- 僅當新消費者在商定的驗證視窗中存活下來後，才讓舊消費者退出。
儀表板切換是可逆的。刪除舊資料、刪除診斷日誌或禁用已建立的警示可能不會。將這些作為單獨的決定，並進行自己的保留和回滾審查。
8. 保留明確的回滾路徑
割接前，記錄：
- 之前的搜尋、儀表板和警示識別符號。
- 介紹該事件的版本。
- 事件和架構版本。
- 新的已儲存查詢識別符號。
- 將消費者返回到先前定義的標準。
- 雙重寫入和額外驗證可以結束的日期。
如果新事件丟失必填欄位、變得延遲或改變含義，請恢復受影響的消費者，同時繼續診斷生產者。回滾不應要求在同一事件期間刪除新的儀器。
此遷移不涵蓋哪些內容
此工作流程並不聲稱要替換本機主機指標、資料庫伺服器統計資訊、分散式追蹤或不受限制的診斷日誌。例如，Telemetry 的資料庫模式分析應用程式發出的資料庫遙測，例如安全查詢指紋、池等待、事務結果、鎖定觀察、複製訊號和遷移結果。他們不是 pg_stat_* 收藏家。
使用每個訊號來回答它可以回答的問題，並僅在操作價值證明資料和基數成本合理的情況下將系統與穩定的識別符號連線起來。
實際的首次遷移
對於API業務，從API 請求吞吐量、API 按路線的錯誤率和API 429 恢復開始。他們共享一個小型事件合約，同時回答不同粒度的流量、可靠性和重試問題。對於資料庫支援的工作流程，僅在請求和查詢指紋可以安全關聯後新增 N+1查詢檢測。
一旦一個工作流程穩定，請重複使用遷移清單以進行下一個決策，而不是毫無疑問地擴充套件原始事件。