结构化日志记录指南

结构化日志记录将事件记录为命名字段，而不是将每个详细信息放在句子中。诸如 checkout failed for account 42 after 812 ms 之类的消息是可读的，但 SQL 必须先解析它，然后才能对故障进行分组或计算延迟。结构化事件分别存储event_name、account_id、status、error_type和latency_ms。

从一个问题开始

在选择字段之前写下操作或产品问题。 “哪个结帐步骤最常失败？”意味着稳定的步骤名称、状态、错误类别和时间戳。 “哪些客户受到影响？”还需要一个安全的帐户标识符。没有可能的过滤器、分组、计算或调试用途的领域可能是噪音。

优先选择有意义的边界内的一个事件：请求完成、作业用尽重试、Webhook 进行重复数据删除或用户达到激活里程碑。避免为同一工作流程的每个分支发出不同的表。一致的 status 场使成功和失败具有可比性。

await telemetry.log("checkout_completed", {
  checkout_version: "v2",
  account_id: account.id,
  status: "failed",
  error_type: "payment_declined",
  latency_ms: 812,
  attempt: 1,
});

保持合同稳定

使用 snake_case 名称、显式单位（例如 _ms 和 _bytes）以及 UTC 时间戳。当您需要可靠的分组维度时，请存储 payment_declined 等类别，而不是完整的例外文本。保持事件中的标识符一致，以便可以通过系统跟踪请求、帐户、发布或作业。

不要默默地将字段从数字更改为字符串。如果其含义发生变化，请添加版本字段或新的事件契约。 事件架构设计指南 更详细地解释了命名、所有权和演变。

保护敏感数据

将每个新字段视为可能出现在查询结果、仪表板或导出中的数据。请勿发送凭据、cookie、授权标头、完整请求正文、付款详细信息或原始提示。与电子邮件和自由格式的用户内容相比，更喜欢内部标识符和受控类别。在活动施工边界应用许可名单；摄入后的脱敏是一种后备措施，而不是主要控制措施。

验证事件

使用合成数据练习成功、失败、超时和重试分支。检查结果表，确认字段类型，并运行引发事件的查询。然后，仅在结果与业务定义匹配后才创建可视化或告警。

继续使用 结构化日志管理指南、典型的广泛事件、结构化事件与文本日志，或从 SQL配方库 复制完整查询。