日志输出怎么规范？

wen 实用脚本 2026-06-05 44

日志输出怎么规范？从混乱到可观测的实战指南

📚 文章目录导读

为什么日志规范是技术债的隐形杀手？
日志分级原则：什么该记，什么不该记？
日志格式的黄金标准：结构化与可解析性
关键字段设计：让日志自己会说话
常见反模式：90%团队踩过的坑
实战案例：从Python/Java/Golang看最佳实践
问答环节：关于日志规范的5个高频问题

为什么日志规范是技术债的隐形杀手？

凌晨2点,线上告警响起，你打开日志系统，发现满屏是：

日志输出怎么规范？

[INFO] 请求进来了
[ERROR] 出错了
[INFO] 处理完成

没有请求ID、没有参数、没有堆栈——你根本不知道哪个接口出了问题，这就是日志混乱带来的灾难。

规范日志输出的核心意义在于：

故障排查效率：30秒定位问题 vs 30分钟大海捞针
系统可观测性：日志、指标、链路追踪三支柱的基石
合规与审计：GDPR等法规要求日志不可篡改且可追溯

我的观点：日志规范不是形式主义，而是线上生存的必备技能，如果你还在用 print("debug")，这篇文章就是为你写的。

日志分级原则：什么该记，什么不该记？

1 五级模型（参考Syslog标准）

级别	使用场景	示例
ERROR	需要立即处理的故障（数据库连不上、空指针）	`数据库连接池耗尽`
WARN	可能演变为错误的情况（磁盘使用率>80%）	`查询耗时>5s，建议检查索引`
INFO	关键业务里程碑（用户注册成功、订单生成）	`订单 #12345 已支付成功`
DEBUG	开发/测试环境细节（函数入参、循环变量）	`用户ID=1001的缓存命中`
TRACE	单次请求的完整调用链（生产环境慎用）	`开始执行方法A` -> `方法A耗时12ms`

2 核心原则

线上环境默认只输出WARN及以上（避免磁盘爆炸）
INFO日志必须可被人工阅读且无重复（不要每循环一次写一条INFO）
ERROR日志必须包含堆栈跟踪（logger.error("消息", exception)）

日志格式的黄金标准：结构化与可解析性

1 不可解析的“文本垃圾”

2025-04-01 12:00:00 [ERROR] 订单创建失败，异常：空指针

❌ 无法用ELK、Splunk等工具自动提取字段
❌ 无法按“订单ID”聚合日志

2 结构化日志（推荐JSON格式）

{
  "timestamp": "2025-04-01T12:00:00.123Z",
  "level": "ERROR",
  "service": "order-service",
  "traceId": "a1b2c3d4",
  "userId": "u-10086",
  "message": "订单创建失败",
  "error": {
    "type": "NullPointerException",
    "stacktrace": "at com.example.OrderService.create(OrderService.java:56)"
  },
  "extra": {
    "orderId": "ORD-20250401-001",
    "amount": 99.99
  }
}

为什么必须结构化？

机器可读：日志系统能自动索引所有字段
灵活查询：字段:值 语法直接定位问题（如 error.type:NullPointerException）
降低存储：仅保留有意义的字段，避免冗余文本

实践建议：使用日志库的自定义格式（如 Logback 的 LogstashEncoder，Python 的 python-json-logger）

关键字段设计：让日志自己会说话

1 必选字段（少一个都算不规范）

字段	说明	示例
`timestamp`	ISO 8601格式，带时区	`2025-04-01T12:00:00.123+08:00`
`level`	日志级别	`ERROR`、`INFO`
`service`	微服务/应用名称	`payment-service`
`traceId`	全链路追踪ID	`a1b2c3d4e5f6`
`message`	人类可读的描述	`用户登录失败：账号不存在`

2 推荐字段（根据业务场景选择）

userId：方便按用户维度排查问题
requestId：HTTP请求唯一标识（从请求头透传）
duration：接口/方法耗时（ms）
extra：自定义上下文（如订单金额、商品ID）

常见反模式：90%团队踩过的坑

❌ 反模式1：日志包含用户敏感信息

log.info("用户登录成功：密码={}", password); // 禁止！

✅ 正确做法：脱敏处理，如 password=******

❌ 反模式2：循环内写大量INFO日志

for item in items:
    logging.info(f"正在处理第{i}条数据") # 如果items有10万条，硬盘直接爆炸

✅ 正确做法：每隔N条输出一次，或仅在DEBUG级别输出

❌ 反模式3：ERROR日志不传异常对象

log.error("订单处理失败"); // 不会打印堆栈！

✅ 正确做法：log.error("订单处理失败", exception);

❌ 反模式4：日志字符串拼接改用占位符

log.info("用户ID：" + userId + "，操作：" + action); // 高CPU开销+低可读性

✅ 正确做法：log.info("用户ID={}，操作={}", userId, action);

实战案例：从Python/Java/Golang看最佳实践

1 Python示例（logging + python-json-logger）

import logging
from pythonjsonlogger import jsonlogger
logger = logging.getLogger("order-service")
handler = logging.StreamHandler()
formatter = jsonlogger.JsonFormatter(
    fmt="%(timestamp)s %(level)s %(name)s %(message)s"
)
handler.setFormatter(formatter)
logger.addHandler(handler)
# 使用
logger.info("订单创建", extra={"orderId": "ORD-001", "userId": "u-10086"})

2 Java示例（Logback + LogstashEncoder）

<!-- logback-spring.xml -->
<appender name="JSON" class="ch.qos.logback.core.ConsoleAppender">
    <encoder class="net.logstash.logback.encoder.LogstashEncoder">
        <includeCallerData>true</includeCallerData>
    </encoder>
</appender>

3 Golang示例（slog + JSON格式）

import "log/slog"
slog.Info("order created", 
    "orderId", "ORD-001",
    "amount", 99.99,
    "user", slog.Group("user", "id", "u-10086"),
)

共性原则：

使用结构化日志库
避免字符串拼接
始终传入异常/上下文

问答环节：关于日志规范的5个高频问题

Q1：开发环境需要遵循生产环境规范吗？

A：建议统一规范，开发时就用结构化日志，上线后直接配置级别过滤（DEBUG -> WARN），避免重复修改。

Q2：日志文件太大怎么办？每天几十GB。

A：三步解决：

分级别存储：ERROR单独文件，INFO单独文件
设置滚动策略：按大小（如100MB）或时间（每天）滚动
日志压缩：使用gzip压缩旧日志，存储成本降80%

Q3：日志里要不要打印SQL语句？

A：仅在DEBUG级别打印，且脱敏参数（如 select * from users where id = ?），线上推荐用数据库审计日志替代。

Q4：多微服务环境下，traceId如何传递？

A：使用OpenTelemetry标准，通过HTTP头（如 X-Request-Id）或RPC元数据传递，Java用Spring Cloud Sleuth，Go用OpenTelemetry SDK。

Q5：日志可以被篡改吗？如何保证合规性？

A：使用不可变日志存储（如阿里云日志服务、Elasticsearch只读索引），或引入日志审计链（区块链方案），对于金融级系统，推荐多副本异地备份。

规范日志，从明天早上的第一个print开始

日志规范不是一次性的架构决策,而是每天编码时的肌肉记忆，从今天起：

禁用 System.out.println 和 console.log
使用JSON格式输出关键字段
ERROR日志永远带异常对象
定期用日志工具（如ELK、Graylog）审视你的日志质量

行动清单：

[ ] 检查项目是否存在 log.info("字符串"+变量) 的写法
[ ] 为所有ERROR日志补充堆栈
[ ] 在请求入口生成traceId并透传
[ ] 编写日志规范文档并同步团队

当你的日志系统在任何故障发生后都能30秒内给出答案,你会感谢今天开始规范的自己。