第4章 日志格式与规范设计

好，咱们直奔主题。这一章要聊的是日志格式和规范设计。你可能觉得这事没什么技术含量——不就是写几行日志吗？我以前也这么想。直到有一次，线上两个机房的日志格式不一致，排查问题时两边对不上，白白浪费了整整两天。从那以后，我定了一个规矩：日志格式必须先行。

4.1 为什么要统一格式？

两个机房写出来的日志，如果格式不统一，你就没法用脚本对比。你想想看，一个时间格式是"2024-01-15 10:30:00"，另一个是"2024/01/15 10:30:00.123"。字符串对比直接报错。这还算好的。

更隐蔽的问题是什么？同一个请求的追踪ID，一个机房叫"traceId"，另一个叫"requestId"。两边的测试脚本写死了字段名，拿到数据一跑，全是空的。嗯，这种坑我踩过不止一次。

统一格式的好处，说白了就是三点：

• 可解析：程序能直接读，不用写脏活累活去适配各种怪格式
• 可对比：两个机房的日志字段对齐，diff脚本一行搞定
• 可溯源：一眼看出这条日志是从哪个实例、哪个服务、哪个机房出来的

4.2 核心字段定义

在我做过的几个多活项目里，日志记录至少应该包含以下字段。我习惯用一个表格把它固定下来，避免开发人员自由发挥。

字段名	类型	说明	示例
timestamp	string	日志产生时间，带时区	2024-01-15T10:30:00.123+08:00
level	string	日志级别	INFO / WARN / ERROR
traceId	string	全链路追踪ID	a1b2c3d4-e5f6-7890-abcd-ef1234567890
spanId	string	当前节点ID	abc123
service	string	服务名	order-service
instance	string	实例ID	order-svc-v1-abcde
dc	string	机房标识	dc-1 / dc-2
msg	string	日志正文	用户下单成功, orderId=12345
extra	json	扩展属性，key-value形式	{"userId": "u_001", "amount": 99.9}

4.3 时间戳规范

时间戳不对齐，一致性测试根本没法做。我个人的建议是：

1. 统一用ISO 8601格式：比如 2024-01-15T10:30:00.123+08:00。这个格式可读性好，也能精确到毫秒
2. 必须带时区：多活场景下，不同机房可能在东八区、零时区。不带时区的时间戳，你拿过来直接用，偏差可能就是几个小时
3. 纳秒级精度：如果业务需要记录高并发下的事件顺序，建议用纳秒。我一般会用 2024-01-15T10:30:00.123456789+08:00

4.4 全链路追踪ID

这是多活场景下日志一致性的命门。如果没有统一的追踪ID，你根本不知道两个机房处理的到底是不是同一个请求。

我推荐的做法是：

• 追踪ID在网关或入口处生成，在整个请求链路中透传
• ID格式用UUID v4，比如 a1b2c3d4-e5f6-7890-abcd-ef1234567890
• 跨机房调用时，必须把traceId塞进HTTP头或消息队列的元数据里

你可能会问，为什么不直接用业务ID？业务ID有时会重复，比如退款单号截断了，两边对不上。UUID虽然长一点，但全局唯一，永不会撞。

4.5 日志级别与格式化

在实际项目中，日志级别不能乱用。我见过不少团队把ERROR当INFO用，导致真正的异常被淹没了。

多活场景下，我的建议是：

级别	使用场景	多活下的特殊要求
INFO	正常的业务流转	记录请求的入口和出口
WARN	非预期的但可处理的情况	记录跨机房数据不一致的预警
ERROR	需要人工介入的异常	必须包含traceId和机房标识

格式方面，我强烈推荐JSON格式。为什么？因为JSON是结构化的，程序解析起来最方便。举个例子：

{
  "timestamp": "2024-01-15T10:30:00.123456+08:00",
  "level": "INFO",
  "traceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "spanId": "span_001",
  "service": "order-service",
  "instance": "order-svc-v1-abcde",
  "dc": "dc-1",
  "msg": "用户下单成功",
  "extra": {
    "userId": "u_001",
    "orderId": "ord_12345",
    "amount": 99.9
  }
}

4.6 强制规范要成文化

我的习惯是：规范一定要用文档固定下来，并且写进CI中。如果某个服务的日志格式不对，直接阻断发布。

你可以做一个这样的检查脚本：

def validate_log_format(log_line):
    fields = ["timestamp", "level", "traceId", "service", "dc"]
    for f in fields:
        if f not in log_line:
            return False, f"缺少字段: {f}"
    return True, "格式正确"

把它挂在发布流水线里。只要你做到这一步，后面的一致性测试就好做多了。

知识结构总览

这一章的逻辑，我画了张图，方便你理解各个要点之间的关联。

这张图简单明了地展示了日志格式规范设计的核心。从中心节点出发，覆盖字段定义、时间戳、追踪ID、级别规范、格式化、规范成文化六个方向。这六个方向缺一不可，任何一个环节出问题，后续的一致性测试都会卡住。