使用 SQL 實現可觀測性與事件分析

SQL 可觀測性意味著透過可見、可審查的查詢來回答結構化事件中的操作和產品問題。您不必搜尋無限制的訊息並希望每個生產者都以相同的方式格式化它，而是定義有用的欄位，例如 route、status_code、latency_ms、account_id、release 和 outcome，然後直接聚合這些列。

這不會使文字日誌、指標或追蹤過時。它為軟體團隊提供了一個關係分析層，用於解決涉及可靠性、產品行為、成本和客戶影響的問題。

簡短版本

有用的 SQL 可觀測性工作流程包含五個部分：

1. 記錄一個終端事件以進行有意義的操作。
2. 保留一小組穩定的維度、度量和相關識別符號。
3. 將事件儲存在具有可信時間戳的型別化資料表中。
4. 使用只讀 SQL 來過濾、分組、聯接和比較行。
5. 將結果轉換為與決策相關的圖表、儀表板、警示或計劃報告。

Telemetry 遵循該形式：傳送 JSON 事件，檢查推斷資料表，執行 DataFusion SQL，然後發布結果。 SQL配方庫 使整個路徑可透過型別化合約、合成輸入、預期輸出、圖表和邊緣情況進行檢查。

為什麼 SQL 對於可觀測性有用

操作問題通常會變得相關，即使它們以日誌形式開始：

• 2026.07.28發布後哪些路由變慢了？
• 哪些帳戶受到付款事件的影響？
• 重試是否恢復了 Webhook 傳遞，或者僅增加了負載？
• 哪種人工智慧功能的每個接受輸出的成本最高？
• 哪些佇列作業在可見性超時後反覆失敗？

這些問題需要分組、條件聚合、連線、穩定身分和明確的時間視窗。 SQL 讓這些選擇變得可見。審閱者可以檢視速率是否使用行或唯一請求、是否包含最新的部分儲存桶以及內部聯接是否靜默刪除不匹配的資料。

SQL作為技能也是可移植的。函式名稱和時間戳語法因引擎而異，但 SELECT、WHERE、GROUP BY、CASE、連線和視窗函式形成了持久的心理模型。

將操作建模為事件，而不是訊息

從有意義的操作開始，例如 API 請求、結帳嘗試、後台作業、Webhook 傳遞或模型回應。當其結果已知時發出一個終止事件。

{
  "event_name": "api_request_completed",
  "request_id": "req_01J...",
  "account_id": "acct_42",
  "route": "/v1/orders/:id",
  "method": "GET",
  "status_code": 503,
  "latency_ms": 842,
  "release": "2026.07.28",
  "region": "us-west",
  "outcome": "error",
  "error_type": "upstream_timeout"
}

這是一個廣泛的事件：它保留了解釋操作所需的上下文，而不需要一系列脆弱的訊息解析。對 route、error_type 和 outcome 等欄位使用有界類別。預設情況下，保留秘密、原始請求正文、提示文字和私人客戶內容。

Telemetry 在攝取過程中新增 timestamp_utc。如果您還傳送業務時間戳，請根據其含義對其進行命名，例如 scheduled_at、completed_at 或 invoice_period_start，而不是建立第二個不明確的 timestamp。

維度、度量和標識

實際合約分為三種領域：

慎重選擇身分。僅當一行等於您要計數的單位時，計數行才是正確的。重試遙測、多步驟工作流程和定期快照通常會為一個邏輯操作生成多行。

有關架構設計詳細資訊，請使用 設計事件架構、相關 ID 和 高基數字段。

五個 SQL 模式涵蓋多項調查

1. 過濾到決策視窗

SELECT *
FROM api_request_completed
WHERE timestamp_utc >= now() - INTERVAL '24 hours'
  AND route = '/v1/orders/:id'
ORDER BY timestamp_utc DESC
LIMIT 200;

從原始行開始。在建置聚合之前確認單位、可為空性、路由標準化和結果值。

2. 使用明確的分母計算比率

SELECT
  route,
  COUNT(*) AS requests,
  SUM(CASE WHEN status_code >= 500 THEN 1 ELSE 0 END) AS errors,
  ROUND(
    100.0 * SUM(CASE WHEN status_code >= 500 THEN 1 ELSE 0 END)
      / NULLIF(COUNT(*), 0),
    2
  ) AS error_rate_pct
FROM api_request_completed
WHERE timestamp_utc >= now() - INTERVAL '24 hours'
GROUP BY route
ORDER BY error_rate_pct DESC, requests DESC;

分母是所有匹配的請求行。如果生產者將重試作為新行發出，請決定儀表板是否應顯示嘗試或唯一的邏輯請求。

3. 比較發布邊界

SELECT
  release,
  COUNT(*) AS requests,
  approx_percentile_cont(latency_ms, 0.95) AS p95_latency_ms,
  ROUND(
    100.0 * SUM(CASE WHEN status_code >= 500 THEN 1 ELSE 0 END)
      / NULLIF(COUNT(*), 0),
    2
  ) AS error_rate_pct
FROM api_request_completed
WHERE timestamp_utc >= now() - INTERVAL '7 days'
GROUP BY release
ORDER BY release;

版本比較需要流量份額和推出時間。小批次金絲雀不應被解釋為完整的生產部署。

4. 將技術影響加入穩定帳戶

SELECT
  r.account_id,
  a.plan,
  COUNT(*) AS failed_requests
FROM api_request_completed r
LEFT JOIN account_dimension a
  ON r.account_id = a.account_id
WHERE r.timestamp_utc >= now() - INTERVAL '2 hours'
  AND r.status_code >= 500
GROUP BY r.account_id, a.plan
ORDER BY failed_requests DESC;

即使濃縮較晚，左連線也會保留受影響的帳戶。保持維度的新鮮度和明確的每鍵一行規則。

5. 重建相關的時間線

使用 request_id、job_id 或其他工作流程識別符號按時間順序聯合或加入事件。在事件期間，時間線通常比單個聚合更有用，因為它顯示嘗試、重試、依賴性結果和最終狀態。

連線SQL實驗室 提供了六個合成資料表以及有關連線、漏斗、AI 成本、可靠性和恢復的指導課程。它完全在瀏覽器中執行。

將視覺化與問題相匹配

查詢結果應該決定視覺效果，而不是相反。

始終將結果資料表放在圖表旁邊。工具提示和軸可以隱藏底層行中明顯的舍入、空值和小分母。

每個公開的 Telemetry 配方都包括可爬行的結果資料表、視覺化預覽、JSON 和 CSV 裝置以及靜態圖表。從 API 按路線的錯誤率、透過指紋進行緩慢的資料庫查詢 或 按功能劃分的 LLM 成本 開始。

SQL 應該補充其他遙測技術

使用指標來獲得廉價、連續的聚合訊號並透過嚴格控制的標籤發出警示。使用追蹤來了解請求的分散式關鍵路徑。當確切的診斷訊息很重要或事先未知形狀時，請使用文字日誌。當團隊需要靈活的維度、業務上下文、聯接或可審查計算時，請使用結構化事件資料表。

系統可以共享關聯 ID。 SQL 結果可以識別受影響的版本和帳戶群組；然後，追蹤可以解釋代表性的緩慢請求；文字日誌可以顯示確切的依賴性錯誤。

如果沒有第二個儲存支援的決策，請勿將每個追蹤範圍或日誌行復制到第二個儲存中。重複的集合會產生成本和衝突的定義。

安全的收養順序

選擇一種不確定的工作流程並寫下資料應支援的決策。定義其終端事件，在影子模式下檢測它，將事件計數與現有源進行比較，並檢查原始行。然後才發布聚合。

如需從訊息搜尋逐步切換，請關注 從臨時日誌遷移到結構化事件和 SQL。如果當前團隊使用 LogQL、KQL 或 SPL，則 查詢語言遷移指南 對映常見模式，而無需假裝語言可以互換。

審查清單

在查詢開始執行之前：

• 確定行粒和分母；
• 記錄空號和遲到行為；
• 限制時間範圍；
• 驗證單位和時間戳時區；
• 當豐富可能滯後時保留不匹配的行；
• 決定重試和重複的計數方式；
• 排除或註釋不完整的時間段；
• 測試歷史或合成資料的閾值；
• 保留圖表中返回 SQL 和事件合約的連結。

SQL測試方法 解釋了 Telemetry 的自動檢查證明了什麼以及仍然需要業務判斷的內容。