使用 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 的自动检查证明了什么以及仍然需要业务判断的内容。