结构化日志管理和 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;