结构化日志

非结构化日志的局限

先看一条典型的传统日志:

2026-06-29 03:14:22 ERROR User 88291 failed to place order 7731 after 3 retries, payment gateway timeout

人类阅读没有问题.但在排障过程中,实际需要回答的是以下问题:

• "过去 1 小时内,所有支付超时的错误共有多少条?"
• "用户 88291 今天所有的操作日志,按时间排序"
• "哪个服务的订单失败率最高?"
• "这条错误对应的那次请求,其完整调用链路是什么?"

面对上述纯文本日志,这些问题都难以高效回答--因为信息嵌入在自然语言句子中.机器要回答"所有支付超时",需要用正则表达式匹配 "payment gateway timeout" 这个字符串;要按用户聚合,需要从 "User 88291" 中解析数字.一旦日志格式不统一(不同开发者写法各异),正则匹配将难以维护.非结构化日志的根本缺陷在于:其设计目标是人类阅读,而非机器查询.

结构化日志:将句子拆解为字段

结构化日志(Structured Logging)的做法:不再拼接自然语言句子,而是输出机器可直接解析的键值对,通常采用 JSON 格式.同一条日志改写为:

{
  "timestamp": "2026-06-29T03:14:22Z",
  "level": "error",
  "service": "order-service",
  "msg": "failed to place order",
  "user_id": "88291",
  "order_id": "7731",
  "retries": 3,
  "error": "payment_gateway_timeout",
  "trace_id": "a1b2c3d4e5f6"
}

上述问题现在全部转化为简单的字段过滤:

• "所有支付超时" → error = "payment_gateway_timeout"
• "用户 88291 的操作" → user_id = "88291"
• "按服务看失败率" → group by service
• "这次请求的完整链路" → 使用 trace_id 去追踪系统查询(详见下文)

日志等级:控制信息密度的第一道过滤

日志等级(Log Level)决定一条日志的重要程度,是控制噪声的第一道机制.常用等级从轻到重:

关键实践:生产环境的日志等级应当支持动态调整.日常运行时使用 INFO 级别,排查特定问题时临时切换至 DEBUG 获取详细数据,查完后恢复.这样既避免了日常被 DEBUG 日志充斥(同时也节省存储成本,详见第 05 篇),又能在需要时获取完整的调试信息.

字段规范:团队需要统一的字段命名标准

结构化日志的能力建立在字段名统一的基础上.如果服务 A 使用 user_id,服务 B 使用 userId,服务 C 使用 uid,那么"按用户聚合所有服务的日志"这一操作将无法实现.团队需要制定一份字段命名约定.以下为几乎必须具备的核心字段:

Trace ID:连接三大支柱的关键纽带

这是本篇与整个系列衔接的核心章节.回到第 01 篇的排障场景:通过指标发现"下单延迟异常",通过追踪定位到"延迟发生在支付服务".现在需要查看"支付服务中那一次具体请求的日志细节"--即找到那次特定请求在支付服务中产生的日志.

如何查找?如果每条日志都带有 Trace ID(同一次请求在所有服务间共享的唯一标识,其生成与传播机制将在第 06 篇详述),问题就变得简单:

[指标告警<br/>下单 P99 超过 2s] → [追踪定位<br/>延迟在支付服务<br/>trace_id=a1b2c3] → [日志归因<br/>过滤 trace_id=a1b2c3<br/>→ 获取该次请求的全部日志详情]

# 在日志系统中,一条查询即可拉出该次请求的完整日志序列:
trace_id = "a1b2c3"

→ order-service:  received order, calling payment
→ payment-service: calling third-party gateway
→ payment-service: gateway returned 429, retrying (1/3)
→ payment-service: gateway returned 429, retrying (2/3)
→ payment-service: success after 1823ms     ← 根因:第三方限流导致重试,拖慢了整体延迟

采样与成本:日志的取舍策略

第 01 篇指出日志"成本最高".具体来说,一个中等规模的系统每天产生TB 级别的日志是常见情况.全量存储并建立全量索引的成本非常可观(第 05 篇将看到这是 EFK 方案的主要痛点).因此需要有明确的取舍策略:

• 提高日志等级:生产环境关闭 DEBUG 级别,是最直接的减量手段
• 采样(Sampling):对高频,重复性日志(如健康检查,正常的 INFO 日志),仅保留一部分.但错误日志(ERROR)绝不能采样--它们数量稀少且信息密度极高,丢失一条即可能丢失关键线索
• 分级存储:近期日志存放在可快速查询的热存储中,历史日志归档至低成本的冷存储(对象存储)