可观测性与稳定性 / 系统课时
一条应用日志应该包含什么
一条应用日志应该包含什么
应用日志字段不是越多越好,而是要让每条记录都能回答几个稳定问题:什么时候发生、严重程度如何、来自哪个服务和环境、发生了什么,以及这条日志如何与一次请求或业务对象关联。
学习目标
- 能规划应用日志中稳定且通用的基础字段
- 理解
timestamp、level、service、environment、message的职责 - 知道哪些上下文应作为扩展字段,而不是塞进消息文本
先固定一组基础字段
集中日志最怕同一含义在不同应用里使用不同名字。例如一个服务写 severity,另一个写 logLevel,查询全局错误时就必须维护多套条件。更稳妥的做法是先定义跨服务一致的基础字段,再允许业务增加自己的上下文。
| 字段 | 作用 | 示例 |
|---|---|---|
timestamp |
记录事件发生时间 | 2026-09-17T04:20:31.482Z |
level |
表示日志严重程度 | INFO、WARN、ERROR |
service |
标识产生日志的应用或服务 | payment-service |
environment |
区分运行环境 | production |
message |
描述发生的事件 | payment authorized |
这些字段应该尽量出现在所有应用日志中。字段名称一旦确定,应通过日志库封装、编码规范或公共组件保持一致,而不是由每个开发者自由命名。
基础字段应该怎样填写
timestamp 应记录日志事件实际发生的时间,并使用包含时区信息的标准时间格式。分布式系统通常优先采用 UTC,例如 ISO 8601 形式的 2026-09-17T04:20:31.482Z,展示时再由查询界面转换成本地时区。
level 应使用有限且稳定的枚举值,例如 DEBUG、INFO、WARN、ERROR。不要同时出现 warning、WARNNING、err 等不同写法,否则聚合统计会被拆成多个值。
service 和 environment 用于回答“日志从哪里来”。如果生产、测试和开发环境共用日志平台,这两个字段尤其重要。message 则负责描述事件本身,适合保持简短、稳定和可读。
把业务上下文放进独立字段
基础字段无法解释一次请求中的全部上下文,因此还需要按场景增加扩展字段。下面是一条支付服务日志的数据结构示例。
{
"timestamp": "2026-09-17T04:20:31.482Z",
"level": "INFO",
"service": "payment-service",
"environment": "production",
"message": "payment authorized",
"request_id": "req-7f31",
"order_id": "ord-9831",
"payment_id": "pay-2256",
"duration_ms": 46
}验证这类字段设计时,可以向日志平台写入多条请求日志,确认能够按 request_id 找到同一次请求的记录,按 order_id 定位某个订单,并把 duration_ms 作为数值进行排序或聚合。如果某个值只能从 message 中通过正则提取,通常说明它还没有被正确结构化。
扩展字段要控制边界
适合扩展的通常是具有明确查询价值的上下文,例如 request_id、trace_id、user_id、order_id、HTTP 状态码和耗时。不要为了“以后也许有用”把整个请求对象、完整响应体或大量临时变量都写入每条日志,否则会增加存储成本,也可能泄露敏感数据。
同一字段还应保持类型稳定。如果 duration_ms 已定义为数字,就不要在另一些日志里写成字符串 "46ms";如果 user_id 采用字符串,则所有服务最好沿用相同类型。稳定的字段名称、含义和类型,比单纯增加字段数量更能决定集中日志是否容易查询和维护。