結構化日誌管理和 SQL

定義

結構化日誌管理有何變化

傳統的應用程式日誌對於描述本地執行很有價值，但重要的問題通常會跨越許多訊息：結帳是否完成？哪些帳戶受到影響？重試恢復了嗎？新版本是否改變了延遲？結構化事件將結果及其分析上下文記錄為一個型別物件。

結構化日誌管理是定義這些物件、控制其架構和隱私邊界、將它們保留為可查詢資料表以及操作結果搜尋、SQL 查詢、視覺化、儀表板和警示的實踐。它補充了追蹤和指標；它並不要求每條除錯訊息都成為業務事件。

有用的事件贏得它的欄位

從問題和決定開始。每個欄位都應該有助於過濾、分組、關聯、計算、保護或解釋工作流程。無限制的有效負載會帶來成本和隱私風險，並且無法保證更好的答案。

文字日誌和結構化事件

不同的形狀適合不同的工作

關注	面向訊息的日誌	規範結構化事件
主要單位	關於原生代碼路徑的一條訊息	一項已完成的工作流程或有意義的狀態更改
背景	通常分佈在許多線路和服務中	穩定的識別符號、結果、持續時間和維度
分析	搜尋和解析模式	型別過濾器、組、連線、百分位數、漏斗和群組
模式	隱含在散文和格式中	具有明確型別、單位和允許值的命名欄位

JSON

規範的完成事件

json

{
  "event": "checkout_completed",
  "timestamp": "2026-07-28T18:42:16Z",
  "request_id": "req_01K1A9",
  "account_id": "acct_812",
  "plan": "growth",
  "status": "success",
  "duration_ms": 842,
  "amount_usd": 129.00,
  "payment": {
    "provider": "stripe",
    "attempt": 1
  }
}

活動合約

保持分析永續性的設計規則

選擇決策邊界

當請求、作業、Webhook、代理執行、賬單更改或產品里程碑達到某人可能需要解釋的結果時發出事件。

一次捕獲足夠的上下文

包括穩定事件名稱、UTC 時間、狀態、持續時間、環境、發布、安全識別符號以及已知問題所需的有界維度。

保護區型別和單位

將數字保留為數字，將布林值保留為布林值，將單位保留在欄位名稱中。避免稍後解析訊息字串中的延遲、金錢或計數。

限制敏感內容

排除機密、憑據、授權標頭、原始提示、付款詳細資訊和不必要的個人資料。更喜歡分類錯誤上下文。

DataFusion SQL

將事件轉化為可操作的答案

sql

SELECT
  date_trunc('hour', timestamp_utc) AS hour,
  COUNT(*) AS checkouts,
  SUM(CASE WHEN status = 'success' THEN 1 ELSE 0 END) AS succeeded,
  ROUND(
    100.0 * SUM(CASE WHEN status = 'success' THEN 1 ELSE 0 END)
      / NULLIF(COUNT(*), 0),
    2
  ) AS success_rate_pct,
  approx_percentile_cont(duration_ms, 0.95) AS p95_duration_ms
FROM checkout_events
WHERE timestamp_utc >= now() - INTERVAL '24 hours'
GROUP BY date_trunc('hour', timestamp_utc)
ORDER BY hour;