4. 日志格式化与序列化：JSON日志格式、MessagePack序列化、日志级别定义、日志元数据设计
日志这东西，光有内容不行，还得有个好皮囊。你想想看，如果每条日志都是自由文本，解析起来得有多痛苦？正则写到怀疑人生。所以，格式化和序列化是日志系统的地基。地基没打好，后面所有分析、告警、检索都是空中楼阁。
我个人习惯，在设计日志格式时，先想清楚三个问题：谁在看？机器还是人？传输效率重不重要？元数据够不够用？ 这一章，我们就来把这几个问题彻底聊透。
4.1 日志级别定义：从 DEBUG 到 FATAL
日志级别，说白了就是给日志贴个「严重程度」标签。别小看这个标签，它决定了你的告警规则、存储策略、甚至运维排班的优先级。
我见过不少项目，日志级别定义得乱七八糟，有的用数字，有的用字符串，还有的混着用。结果就是告警平台根本没法统一处理。所以，我建议你从一开始就定死一套标准。
下面是我在多个生产项目中验证过的级别定义，直接拿去用：
| 级别 | 数值 | 含义 | 典型场景 |
|---|---|---|---|
| TRACE | 0 | 最细粒度的追踪信息 | 函数调用链、变量值变化 |
| DEBUG | 10 | 调试信息，开发阶段使用 | SQL语句、请求参数 |
| INFO | 20 | 正常业务运行信息 | 服务启动、请求完成、用户登录 |
| WARN | 30 | 潜在问题，不影响当前运行 | 磁盘使用率超过80%、重试操作 |
| ERROR | 40 | 错误，但服务仍可继续 | 数据库连接失败、第三方接口超时 |
| FATAL | 50 | 致命错误，服务即将退出 | 内存溢出、配置加载失败 |
4.2 日志元数据设计：让每条日志都「有身份」
光有级别和消息还不够。想象一下，你收到一条 ERROR 日志，内容是「连接超时」。你怎么办？你得知道是哪个服务、哪个节点、哪个请求、什么时间出的问题。这些信息，就是元数据。
元数据设计的原则是：够用就好，别贪多。每多一个字段，序列化开销就多一分，传输带宽就多一分。我建议你至少包含以下字段：
- timestamp：时间戳，精确到毫秒，最好用 ISO 8601 格式
- level：日志级别，用字符串（如 "ERROR"）而不是数字，方便人类阅读
- service：服务名称，比如 "user-service"
- host：主机名或 IP，用于定位物理节点
- trace_id：追踪ID，用于串联一次请求的完整链路
- span_id：跨度ID，标识当前操作在链路中的位置
- message：日志正文，自由文本
嗯，这里要注意：trace_id 和 span_id 是分布式追踪的核心。没有它们，你根本没法把分散在不同机器上的日志串起来。我在做微服务排障时，经常靠这两个字段把几十条日志拼成一条完整的请求链路图。
4.3 JSON 日志格式：人类可读，机器友好
JSON 是目前最流行的日志格式。为什么？因为它结构清晰、解析方便、生态成熟。几乎所有的日志收集工具（Filebeat、Fluentd、Logstash）都原生支持 JSON。
一个标准的 JSON 日志长这样：
{
"timestamp": "2025-03-15T14:23:45.123Z",
"level": "ERROR",
"service": "order-service",
"host": "node-03",
"trace_id": "abc123def456",
"span_id": "span-001",
"message": "支付接口调用超时",
"extra": {
"order_id": "ORD-20250315-001",
"retry_count": 3,
"timeout_ms": 5000
}
}你看，extra 字段是个灵活扩展区。业务相关的上下文信息都放这里，不影响核心元数据的解析。我个人习惯把 extra 设计成 map[string]interface{}，这样不管什么业务都能往里塞。
但 JSON 有个硬伤：冗余字符太多。键名、引号、逗号、花括号，这些在 UDP 传输中都是实打实的带宽开销。你想想看，如果每秒产生 10 万条日志，每条多出 50 字节的冗余，那就是 5MB/s 的额外流量。对于内网来说可能还好，但如果是跨机房、跨云传输，这个成本就不可忽视了。
4.4 MessagePack 序列化：给日志「瘦身」
如果你对带宽敏感，或者日志量特别大，JSON 可能不是最优解。这时候，MessagePack 就派上用场了。
MessagePack 是一种二进制序列化格式。它和 JSON 的数据模型几乎一样（支持 map、array、string、number、bool、nil），但序列化后的体积更小，解析速度更快。
来看个对比：
| 对比项 | JSON | MessagePack |
|---|---|---|
| 数据格式 | 文本 | 二进制 |
| 体积（典型日志） | 约 200-300 字节 | 约 120-180 字节 |
| 解析速度 | 较慢（需解析字符串） | 较快（直接读取二进制） |
| 人类可读性 | 高 | 低（需工具转换） |
| 生态支持 | 几乎所有语言 | 主流语言都有库 |
MessagePack 的核心优势在于：它用更少的字节表达了同样的数据。比如 JSON 中的 "level": "ERROR" 需要 18 个字节，而 MessagePack 可以用一个字节表示字符串长度，再加上 5 个字节的 "ERROR"，总共才 7 个字节。省了一半多。
在 Go 语言中，使用 MessagePack 非常简单：
import "github.com/vmihailenco/msgpack/v5"
type LogEntry struct {
Timestamp string `msgpack:"ts"`
Level string `msgpack:"lvl"`
Service string `msgpack:"svc"`
Host string `msgpack:"host"`
TraceID string `msgpack:"trace"`
SpanID string `msgpack:"span"`
Message string `msgpack:"msg"`
Extra map[string]interface{} `msgpack:"ext,omitempty"`
}
// 序列化
entry := LogEntry{...}
bytes, err := msgpack.Marshal(entry)
// 反序列化
var decoded LogEntry
err = msgpack.Unmarshal(bytes, &decoded)你看，代码几乎和 JSON 一样简单。但要注意，MessagePack 的字段名可以缩写。我用 ts 代替 timestamp，lvl 代替 level，这样又能省几个字节。别小看这几个字节，积少成多。
4.5 知识体系总览
说了这么多，我们来画个图，把这一章的核心逻辑串起来。下面这张 SVG 图展示了日志从产生到传输的完整格式化链路：
4.6 如何选择：JSON 还是 MessagePack？
这个问题没有标准答案，得看你的场景。我列个决策树，你照着走就行：
- 日志量 < 1万条/秒：用 JSON。省心，调试方便，生态好。
- 日志量 1万-10万条/秒：用 MessagePack。带宽和解析速度的优势开始显现。
- 日志量 > 10万条/秒：MessagePack + 字段缩写。每个字节都得省。
- 跨网络传输（尤其是公网）：无脑 MessagePack。带宽就是钱。
- 需要人类直接阅读日志文件：JSON。或者 MessagePack 落地后，用工具转成 JSON 再查看。
好了，这一章的内容就到这里。日志格式化和序列化，说白了就是在「人类可读」和「机器高效」之间找平衡。你选 JSON 还是 MessagePack，取决于你的日志量、带宽和团队习惯。但不管选哪个，元数据一定要设计好，这是所有后续分析的基础。