3、结构化日志入门：什么是结构化日志、与文本日志对比、JSON格式优势

好，咱们今天聊点实在的。

你写 Go 后端，肯定打过日志。最常见的做法是什么？fmt.Println 或者 log.Printf 对吧？然后日志长这样：

2025/01/15 14:23:10 User login success: user_id=12345, ip=192.168.1.1

看着还行？嗯，我当年也觉得还行。直到有一次线上出问题，我对着几万行这种日志，用 grep 和 awk 扒拉了整整一个下午……那感觉，真不想再体验第二次。

什么是结构化日志？

说白了，结构化日志就是把日志从「一段话」变成「一堆键值对」。每条日志不再是自然语言，而是一个结构化的数据对象。

举个例子，上面那条日志，用结构化方式写出来就是：

{
  "time": "2025-01-15T14:23:10+08:00",
  "level": "info",
  "module": "auth",
  "event": "user_login",
  "user_id": 12345,
  "ip": "192.168.1.1",
  "message": "User login success"
}

看到了吗？每个字段都有明确的含义。机器能读懂，人也看得懂。

核心要点：结构化日志的本质是「数据化」，不是「文本化」。每条日志都是一个可解析的数据记录。

文本日志 vs 结构化日志

咱们来做个对比。我直接列个表，你一看就明白。

对比维度 文本日志 结构化日志
可读性 人眼直接看还行 需要格式化工具，但更清晰
机器解析 难！正则写到崩溃 天然支持，直接解析 JSON
查询效率 grep 硬搜，慢且不准 按字段过滤，快准狠
扩展性 加字段就得改格式 直接加键值对，不影响旧数据
对接工具 需要写解析器 ELK、Datadog 原生支持
调试体验 看日志像看小说 看日志像查数据库

你想想看，如果你要查「所有 user_id 为 12345 的登录失败记录」，文本日志你得写个正则：

grep "login failed" app.log | grep "user_id=12345"

这还算简单的。要是字段顺序变了、中间多了空格、或者有人用了 tab 而不是空格……你的正则就废了。我在项目中遇到过这种坑，排查了半小时才发现是日志格式不统一导致的。

而结构化日志呢？一行查询搞定：

jq 'select(.event == "login_failed" and .user_id == 12345)' app.log

或者直接扔到 Elasticsearch 里，点几下鼠标就出来了。

为什么 JSON 格式是主流？

你可能会问：结构化日志一定要用 JSON 吗？不一定。也可以用 XML、Protocol Buffers、甚至自定义格式。但为什么大家都选 JSON？

我个人习惯用 JSON，原因有三：

  1. 语言无关——几乎所有编程语言都有 JSON 解析库，Go 标准库自带 encoding/json，开箱即用。
  2. 人类可读——JSON 虽然比纯文本啰嗦一点，但结构清晰，缩进好了之后一眼就能看出层级关系。
  3. 生态成熟——从日志采集（Filebeat、Fluentd）到存储（Elasticsearch）到可视化（Kibana、Grafana），全线支持 JSON。

小提示：Go 里用 logrus 或 zap 输出 JSON 日志，只需要一行配置。后面章节我会手把手带你搭。

JSON 格式的优势，具体好在哪？

咱们再深入一点。JSON 日志到底能帮你解决哪些实际问题？

第一，字段可索引。 每个字段都是一个独立的 key，你可以按任意维度聚合。比如统计「今天每个接口的请求量」：

jq 'select(.level == "info" and .event == "http_request") | .endpoint' app.log | sort | uniq -c

文本日志？你得先解析出 endpoint 字段，再统计。麻烦不麻烦？

第二，类型安全。 JSON 支持数字、布尔值、数组、嵌套对象。你的 user_id 是整数就是整数，is_paid_user 是布尔就是布尔。文本日志里全是字符串，你还得自己转类型。

第三，上下文丰富。 你可以把请求 ID、用户 ID、耗时、错误堆栈全部塞进一条日志里，而且结构清晰。比如：

{
  "time": "2025-01-15T14:23:10+08:00",
  "level": "error",
  "trace_id": "abc-123-def",
  "service": "order-service",
  "request": {
    "method": "POST",
    "path": "/api/orders",
    "body": {"product_id": 42, "quantity": 1}
  },
  "error": {
    "type": "database_timeout",
    "message": "connection pool exhausted",
    "stack": "goroutine 1 [running]:\n..."
  }
}

你看，一条日志就把整个请求的上下文全记录下来了。排查问题的时候，你不需要翻十几条分散的日志，一条就够了。

注意：JSON 日志也不是没有代价。每条日志的体积会比纯文本大 30%-50%。如果你的日志量级在每天 TB 级别，需要考虑压缩和采样策略。不过对于大多数中小团队来说，这个成本完全可以接受。

什么时候不该用结构化日志？

嗯，这里要客观一点。结构化日志不是银弹。

我曾经在一个极早期的原型项目里，硬上了全套结构化日志。结果项目三天就改需求了，日志格式全废。说白了，如果你的项目还在「快速试错」阶段，日志只是用来简单调试，那 fmt.Println 完全够用。

但一旦你的系统开始有多个服务、需要排查线上问题、或者要对接监控告警——我建议你立刻切换到结构化日志。越早切换，成本越低。

小结

这一节咱们聊了：

  • 结构化日志就是把日志变成键值对数据
  • 和文本日志比，它更利于机器解析、查询、扩展
  • JSON 是当前最主流的结构化日志格式，生态好、易用性强

下一节，我会带你用 Go 的 zap 库，从零搭一个生产级的结构化日志系统。到时候你会看到，写结构化日志其实就几行代码的事。

公众号:蓝海资料掘金营，微信deep3321

← 上一章 📖 返回目录 下一章 →