日志格式化最佳实践:九条规则让日志机器可解、人亦可读

日志格式化决定了日志能否被高效检索与分析。本文讲解非结构化/半结构化/结构化三种日志格式的区别,以及九条生产环境日志格式化实践:JSON 输出、ISO-8601 时间戳、字符串级别、来源信息、版本号、堆栈跟踪、上下文字段规范、关联 ID 与对象字段控制。

最佳实践
日志、指标与链路追踪示意图

日志格式化(Log Formatting)是指对日志条目的结构、编码、上下文字段组织方式和分隔规则的标准化设计。 格式差的日志如同大海捞针;格式好的日志则能被自动检索、聚合与告警,是整个日志体系效率的前提。

三种日志格式

1. 非结构化日志:自由文本,开发时好读,规模上来后难以检索:

1687927940843: 应用在 3000 端口启动
数据库备份时发生意外错误

2. 半结构化日志:时间戳、级别、进程号等头部标准化,但消息体仍是自由文本:

2026-08-25 19:09:48 I [969609:60] MyApp -- 应用在 3000 端口启动

3. 结构化日志:整条日志是格式统一的数据对象(通常是 JSON),字段明确、机器可解析:

{"time": "2026-08-25T17:20:19+08:00", "level": "info", "service": "MyApp", "msg": "应用在 3000 端口启动"}

生产环境应统一到结构化;开发环境可切换为彩色易读格式,多数框架支持按环境切换。

核心要点速览

  • 生产日志统一用 JSON 结构化输出;
  • 级别用字符串(error 而非 50),时间戳用 ISO-8601/UTC;
  • 日志带可区分实例的来源信息与构建版本(如 commit hash),按需记录代码位置;
  • 记录异常时按排查需要保留堆栈跟踪,优先保留关键调用帧;
  • 上下文字段全公司统一命名,用 trace_id 串联请求;
  • 对自定义对象实现选择性输出,防止敏感字段被意外记录。

九条实践详解

1. 使用结构化 JSON 日志

采用原生支持 JSON 的日志框架(如 Go slog 的 JSONHandler)。按行收集时,每个事件编码成一行,消息内的换行交给编码器转义。Nginx 要用 log_format 定义 JSON 对象并设置 escape=json 转义变量,再在 access_log 中选用该格式;PostgreSQL 15+ 使用 log_destination = 'jsonlog' 时还需启用 logging_collector。Nginx 日志模块 · PostgreSQL 日志配置

2. 级别统一用字符串表示

框架内部常用整数表示级别(如 Pino 里 60 表示 fatal),但不同框架的整数约定不同,跨语言环境极易混淆。统一输出字符串级别(info、error),并明确定义不同来源的映射,如将 WARN 映射到 warning。

接入观测云时,在 Pipeline 中将应用级别映射到 status,用一条 error 和一条 info 日志测试映射结果,再按级别筛选 [1]。

3. 时间戳用 ISO-8601 并统一时区

RFC 3339 是 ISO 8601 的互联网时间戳规范,支持 UTC 偏移和小数秒。下面是携带偏移的示例,实际保留的精度取决于时钟及采集和存储链路:

2026-08-25T12:34:56.123456789+08:00

建议统一记录 UTC 事件时间。若另有采集时间,两者应分别保留。UTC 能统一时区表示,服务器时钟偏差仍需单独排查。OpenTelemetry 日志数据模型

4. 记录日志来源信息

每条日志应能回答"它从哪来":保留服务、环境和需要的实例标识;代码位置可按排查需要开启,例如 Go slog 的 HandlerOptions.AddSource。以下是代码位置示例:

{"level": "DEBUG", "source": {"function": "main.main", "file": "app/main.go", "line": 30}, "msg": "调试信息"}

5. 带上构建版本或 commit hash

代码会重构,函数名和行号会变化——半年前的错误日志可能对不上现在的代码。在日志中加入应用版本号或 Git commit hash(必要时加上运行时版本),就能精确回溯到日志产生时的代码状态:

{"level": "ERROR", "msg": "意外错误", "build": {"version": "v2.3.1", "commit": "9b0695e1"}}

6. 按需记录异常堆栈

异常堆栈可以提供调用路径;一般业务拒绝可只记录错误码及必要上下文。需要按帧分析时输出结构化堆栈,也可将文本堆栈放进一个 JSON 字符串字段。若源端仍写纯文本多行堆栈,需配置采集器按事件首行合并,避免把每帧拆成独立日志 [1]。

7. 标准化上下文字段

不要把上下文拼接进消息字符串("用户 " + id + " 登录"),而要以键值对输出:

slog.Info("用户登录", slog.Int("user_id", 42))

框架的字段绑定能力(如 slog 的 With())可以让一组日志自动携带相同字段。全公司统一字段命名规范——用户 ID 固定叫 user_id,不要出现 user/uid/userID 混用;数值字段名带单位(duration_ms、response_bytes)。

集中检索时,字段名和类型保持一致,才能用相同条件比较各服务;仍需确认查询范围包含所需日志 [2]。

8. 用关联 ID 串联请求日志

一个请求会产生多条日志。在请求入口生成唯一 ID 并按约定透传,记录了相同 request_id 且已采集的日志可一起查询。已有链路埋点时,将当前上下文的 trace_id 写入日志,需要定位单次操作时再写 span_id。两者来自链路上下文,应用自定义的 request_id 不直接替代它们;观测云的日志关联字段见 APM FAQ [3]。

9. 对自定义对象做选择性输出

为自定义结构体实现日志输出控制方法(如 Go slog 的 LogValuer 接口),明确指定哪些字段允许进入日志:

func (u *User) LogValue() slog.Value {
    return slog.StringValue(u.ID) // 此输出路径只记录经过允许的 ID
}

通过该接口输出对象时,新字段不会自动进入日志。仍需检查原始消息、其他字段和堆栈,避免请求头、密码等内容从其他路径写入。Go slog 文档

总结

九条规则可归为三类:格式层面(JSON、字符串级别、ISO-8601)、溯源层面(来源、版本、堆栈)、关联层面(字段规范、关联 ID、字段控制)。检索前应拿正常、异常及多行堆栈样本检查这些约定是否一致。

常见问题(FAQ)

Q:开发环境也必须输出 JSON 吗?
不必。开发环境可用彩色易读格式提升阅读体验,生产环境切回 JSON——主流框架都支持按环境变量切换输出格式。

Q:老系统输出的是非结构化日志怎么办?
原文已有的字段可由 DataKit Pipeline 按规则提取;日志从未记录的请求 ID 或上下文则要在应用中补充 [4]。

Q:ISO-8601 和 Unix 时间戳选哪个?
两者都可用于日志。RFC 3339 带 UTC 偏移,方便阅读;Unix 时间戳便于程序处理,但要约定秒、毫秒或纳秒。解析时核对时区、单位和保留精度。


系列阅读:日志最佳实践十二条 | 什么是结构化日志

[1]: 观测云文档《日志采集》https://docs.guance.com/integrations/logging/
[2]: 观测云文档《日志查看器》https://docs.guance.com/logs/explorer/
[3]: 观测云文档《APM FAQ》https://docs.guance.com/en/application-performance-monitoring/faq/
[4]: 观测云文档《DataKit 日志采集综述》https://docs.guance.com/integrations/datakit-logging/

获取专属方案

联系我们

加入社区

微信扫码
加入官方交流群

立即体验

在线开通,按量计费,真正的云服务!

立即开始

选择观测云版本

代码托管平台