大多数项目的日志是这样演化的：初期只有几行 print，调试时随手加几条，上线后怕出问题又加几条，最后日志量膨胀到每天几个 GB，真正需要排查问题时却在海量日志里找不到关键信息。日志的膨胀和质量的下降是同步发生的——写得多不代表写得好，很可能恰恰相反。
非结构化日志的三个致命问题
问题一：可搜索性差。 非结构化日志是给人读的文本，不是给程序处理的数据。当你需要查找"过去一周内所有支付失败的请求"时，面对的是一行行格式不统一的文本：有的是 Payment failed for user 123，有的是 Error processing payment: timeout，有的是 支付失败 userId=123 reason=timeout。写 grep 正则需要覆盖所有变体，而且无法保证没有遗漏。
更糟糕的是，同一个事件在不同位置可能被记录为不同格式。A 模块写 order_id=456，B 模块写 orderId=456，C 模块写 order:456。这不是故意制造混乱，而是不同开发者在不同时间独立添加的日志，没有统一规范。当模块数量超过十个时，格式统一性就不可能靠人的自觉来维持了。
问题二：上下文丢失。 一条日志 Operation failed 包含了什么信息？有一个操作失败了。但什么操作？哪个用户的？什么时候？什么参数？什么错误？这些上下文全都没有。不是开发者不想加，而是在写日志的当下觉得"这一看就知道是什么操作"，三个月后看日志的人却完全不知道。
上下文丢失的另一个表现是：关联信息分散在不同日志行中。请求 A 的入口日志在第一行，错误日志在第一百行，中间夹着其他请求的日志。要还原请求 A 的完整链路，需要手动从海量日志中挑出相关行。这不是"不方便"，在严重故障时这是"不可能"——当每秒产生几千行日志时，人工关联已经不可行。
问题三：无法自动分析。 非结构化日志只能做全文搜索，无法做聚合分析。"过去一小时的错误率是多少？""哪些 API 端点的响应时间超过了两秒？""哪种错误类型出现最频繁？"这些问题的答案就在日志里，但非结构化的格式让自动提取变得极其困难。需要为每种查询写定制的正则，而正则的脆弱性意味着任何格式变化都可能导致分析结果不准确。
结构化日志的核心要素
结构化日志的核心理念是：每条日志都是一个有明确字段定义的数据记录，而不是一段自由文本。这意味着日志可以被程序可靠地解析、索引、查询和分析。
一条结构化日志至少应该包含以下字段：
时间戳（timestamp）：精确到毫秒。这不是可选的——没有时间戳的日志几乎没用。时间戳应该是 UTC 或者明确标注时区，避免跨时区部署时的混乱。
日志级别（level）：DEBUG / INFO / WARN / ERROR / FATAL。级别的定义要明确：DEBUG 只在开发时用，INFO 记录正常业务事件，WARN 记录可恢复的异常，ERROR 记录需要关注的失败，FATAL 记录导致服务不可用的严重错误。模糊的级别定义比没有级别更糟糕，因为会导致信息被错误过滤。
事件类型（event）：这条日志描述的是什么事件？不是"发生了一个错误"，而是具体的 payment_failed、request_timeout、cache_miss。事件类型应该是枚举值，而不是自由文本。每个事件类型对应一种已知的系统行为，未知的事件类型意味着有未预期的行为需要关注。
请求标识（request_id / trace_id）：用于关联同一请求的所有日志。在分布式系统中，一个用户请求可能经过多个服务，trace_id 是跨服务追踪的线索。没有 trace_id，分布式系统的日志几乎不可能关联。
上下文字段（context）：与事件相关的关键数据。支付失败需要记录 user_id、order_id、error_code、amount。请求超时需要记录 endpoint、timeout_ms、retry_count。上下文字段的选取原则是：排查问题时一定会问的信息。如果排查"支付失败"时第一个问题是"哪个用户"，那 user_id 就是必填字段。
从非结构化到结构化的迁移
不需要一步到位。以下是一个渐进式迁移策略：
第一阶段：JSON 格式化。 把现有的文本日志改为 JSON 输出。这一步不改日志内容，只改格式。原来写 logger.info(f"Payment failed for user {user_id}")，改为 logger.info("payment_failed", user_id=user_id)，框架自动输出为 JSON。这一步的收益是日志可以被 jq、Elasticsearch 等工具直接处理。
第二阶段：统一事件类型。 为每个模块定义事件类型枚举。不再用自由文本描述事件，而是从预定义列表中选择。这一步的收益是日志可以被精确搜索和过滤——查所有 payment_failed 事件只需要一个查询条件。
第三阶段：补充上下文字段。 审查每个事件类型，确保记录了排查问题所需的全部字段。这一步需要站在运维的角度思考："如果这个事件在生产环境发生，我需要什么信息才能定位问题？"缺什么补什么。这一步的收益是问题排查不再需要"登录服务器看代码"来理解日志含义。
第四阶段：引入 trace_id。 在请求入口生成唯一标识，传递到整个调用链。这需要各服务配合，但在分布式系统中是必须的。这一步的收益是可以追踪一个请求的完整路径。
第五阶段：建立日志质量门。 在 CI 中检查日志语句是否符合规范：是否使用了结构化格式、是否包含必要字段、事件类型是否在枚举中。不合规的日志在代码审查阶段就被拦截。这一步的收益是防止日志质量退化。
日志级别的正确使用
日志级别是最常被误用的设计。常见错误：
用 ERROR 记录预期内的异常。 比如用户输入不合法、第三方 API 限流返回 429、缓存未命中需要回源。这些是已知的、可恢复的情况，不应该用 ERROR。滥用 ERROR 会导致真正的错误被淹没在噪声中，监控告警也频繁误报。
正确的做法：预期内的异常用 WARN，只有需要人工介入的意外情况才用 ERROR。判断标准是"这条日志是否需要有人立即查看"。如果不需要，它不应该是 ERROR。
用 DEBUG 记录所有细节。 DEBUG 日志的初衷是帮助开发调试，但如果 DEBUG 日志包含大量数据（如完整的请求/响应体、大数组内容），在生产环境打开 DEBUG 时会产生海量输出，影响性能和存储。
正确的做法：DEBUG 只记录调试逻辑所需的最小信息。大数据量的内容使用 TRACE 级别（如果框架支持），或者根本不记录——需要时可以通过专门的调试接口获取。
INFO 日志要么太多要么太少。 太多：每个函数入口出口都记一条 INFO，日志量爆炸。太少：只有服务启动和停止的日志，出问题时完全没有线索。
正确的做法：INFO 记录业务关键事件——请求处理完成、状态变更、定时任务执行、外部调用结果。判断标准是"如果这条日志缺失，是否影响对系统运行状态的理解"。
日志的量与质的权衡
日志量和日志质量是反相关的。日志量越大，单条日志的平均价值越低，因为有用的信息被噪声稀释了。
一个实用的策略是分层日志：
- 业务层日志：记录业务事件和关键指标，量小但价值高。这是运维和产品团队日常关注的日志。
- 技术层日志：记录技术细节（接口调用、缓存命中、队列消费），量中等，排查技术问题时使用。
- 调试层日志：记录详细执行过程，量大，只在开发调试时开启。
三层日志的输出可以由级别控制：业务层对应 INFO，技术层对应 DEBUG，调试层对应 TRACE。生产环境通常只输出业务层日志；需要排查技术问题时临时开启技术层；调试层只在开发环境使用。
日志不是唯一的可观测性手段
日志、指标（metrics）、追踪（traces）是可观测性的三大支柱。把所有可观测性需求都压到日志上，会导致日志承担过多职责：
- 用日志统计 QPS → 应该用指标
- 用日志追踪请求链路 → 应该用分布式追踪
- 用日志监控系统健康 → 应该用健康检查和告警
日志的优势是记录事件详情——具体发生了什么、上下文是什么。指标的优势是聚合和趋势——过去一小时的 QPS 变化、P99 延迟走势。追踪的优势是关联和定位——一个慢请求卡在哪一步。
各司其职，不要让日志越俎代庖。当你发现自己写日志是为了"之后用 awk 统计"时，说明这个信息应该是一个指标而不是一条日志。
总结
日志不是垃圾桶——不该什么都往里扔；日志是档案——每条记录都应该有明确的用途和结构。从非结构化到结构化不是格式升级，而是管理理念的转变：日志不再是"出了问题再看的文本"，而是"系统行为的结构化数据"。
关键原则：每条日志都有明确的事件类型、必要的上下文字段、准确的级别、和可关联的请求标识。做到这四点，日志就从"需要大海捞针的文本堆"变成了"可精确查询的数据源"。排查问题的时间从小时级降到分钟级，不是因为人变聪明了，是因为日志终于变得可搜索了。
日志的隐私与合规考量
在设计日志系统时，隐私和合规是容易被忽视但至关重要的维度。
敏感信息的脱敏。日志中不应该记录密码、信用卡号、身份证号等敏感信息。但开发者经常无意中把敏感信息写进日志：比如记录完整的请求体（里面可能包含密码）、记录数据库查询结果（里面可能有用户隐私）。解决方案是在日志框架层统一脱敏，而不是依赖开发者每次手动过滤。
日志的保留周期。不同类型的日志有不同的保留价值。业务日志（如订单创建）可能需要保留多年用于审计；调试日志可能只需要保留几天。不区分日志类型的"一刀切"保留策略，要么浪费存储空间，要么在需要时找不到关键日志。
日志的访问控制。不是所有人都应该能访问所有日志。运维团队需要技术日志；业务团队需要业务日志；安全团队需要安全相关日志。日志的访问权限应该与岗位职责匹配，避免敏感信息泄露。
日志与告警的边界
日志和告警是两个不同的系统，但有紧密的联系。经常被混淆的两种用法：
用日志代替告警。在日志里标记某些事件为"需要关注"，然后人工监控日志。这种做法的问题是实时性差、容易遗漏、无法做聚合分析。正确做法是把需要实时关注的事件推送到告警系统，告警系统负责通知、聚合、静默、升级等逻辑。
用告警代替日志。每个异常都发一条告警，导致告警泛滥，真正重要的告警被淹没。正确做法是日志记录所有异常，告警系统基于日志做聚合和阈值判断——比如"同一错误5分钟内超过10次才告警"。
日志是数据源，告警是决策系统。日志负责记录，告警负责判断。不要让一个系统承担两个职责。
日志的测试与质量保证
日志也是代码的一部分，需要测试。但大多数项目的日志测试是缺失的。
日志输出测试。单元测试中验证关键路径是否输出了预期的日志。比如，"支付失败"场景应该输出payment_failed事件，包含user_id、order_id、error_code字段。这种测试确保日志的内容符合预期。
日志格式测试。确保所有日志都符合结构化格式，没有遗漏必要字段。这可以在CI中自动化检查。
日志级别测试。确保日志级别使用正确，没有用ERROR记录预期内的异常，没有用INFO记录无关紧要的信息。这个检查可以结合代码审查进行。
日志性能测试。在高负载场景下测试日志系统的性能，确保日志写入不会成为瓶颈。特别是同步日志写入，可能阻塞业务线程。
日志系统演进的阶段性
从"随手写print"到"结构化日志体系"是一个演进过程，不可能一蹴而就。
第一阶段：日志存在。先有日志，不管格式。这个阶段的目标是确保关键路径有日志输出，出问题时至少有东西可查。
第二阶段：日志可查。日志输出到文件或服务，可以用grep或搜索工具查找。这个阶段的目标是减少"登录服务器看日志"的依赖。
第三阶段：日志结构化。统一日志格式，引入事件类型、字段定义。这个阶段的目标是让日志可以被程序处理，而不仅是人阅读。
第四阶段：日志关联化。引入trace_id，可以追踪一个请求的完整链路。这个阶段的目标是解决分布式系统中的问题定位难题。
第五阶段：日志产品化。日志有质量门、有测试、有监控。这个阶段的目标是把日志当作一个正式的系统资产来维护，而不是事后补救的手段。
大多数团队停留在第二阶段或第三阶段。向下一阶段演进需要投入，但收益也是显著的——每前进一步，问题排查的时间就减少一个数量级。
实践中的日志规范模板
以下是一个可以参考的日志规范模板，可以根据项目实际情况调整：
# 日志规范
日志格式: JSON
必填字段:
- timestamp: ISO8601格式，UTC
- level: DEBUG/INFO/WARN/ERROR/FATAL
- event: 事件类型，从预定义列表中选择
- request_id: 请求唯一标识
事件类型规范:
- 模块前缀: 如 payment_, user_, api_
- 动作后缀: 如 _created, _failed, _completed
- 示例: payment_created, payment_failed, api_timeout
敏感字段脱敏列表:
- password
- credit_card_number
- id_card_number
- access_token
保留周期:
- 业务日志: 365天
- 技术日志: 30天
- 调试日志: 7天
这个模板不是标准答案，而是起点。重要的是团队有共识、规范被文档化、执行有检查机制。
日志的真正价值
写到最后，我想强调一点：日志的价值不在于"写了多少"，而在于"出了问题能不能快速定位"。
一个每天产生10GB日志的系统，可能在出问题时一无所获；一个每天只产生100MB日志的系统，可能在几分钟内定位到问题根因。区别不在于日志量，而在于日志的质量。
好的日志系统是"平时看不见，出事能救命"。平时它安静地记录，不占用过多资源，不制造噪声。出问题时，它能在几分钟内帮你找到关键线索，而不是让你在海量日志中大海捞针。
这才是日志系统的真正价值——不是为了记录而记录，而是为了在需要时能回答问题。结构化日志的所有设计原则，都是围绕这个目标展开的。