让日志真正可用：Python 服务的结构化记录与故障定位

线上服务出问题时，最先被打开的通常不是代码，而是日志。可惜很多项目的日志只有“请求失败”或一串难以检索的字符串，真正排查时还要靠猜。把日志做成稳定、可检索的结构，往往比增加更多日志行更有效。

一、先固定字段，再补充描述

建议每条关键日志至少包含时间、级别、服务名、请求标识和事件名称。请求标识要从入口生成，并沿着函数调用和下游请求传递。这样一次请求跨越多个模块时，可以用同一个 trace_id 串起完整路径。业务对象的编号可以记录，但密码、令牌和完整身份证号等敏感信息不应写入日志。

在 Python 中，可以把字段放到 extra 中，统一由 Formatter 输出。对于多进程或容器环境，优先使用 JSON 格式，每行一条记录，方便 Loki、OpenSearch 或云日志服务直接解析。开发环境可以保留人类可读格式，生产环境则应保证字段名稳定，避免同一含义出现 userId、user_id、uid 三种写法。

二、让异常日志回答“发生了什么”

捕获异常时不要只写“调用失败”。至少补充操作名称、目标服务、重试次数和耗时。外部依赖失败时，还要区分超时、连接失败、对方返回 4xx 和 5xx，因为处理策略并不相同。堆栈信息应保留在 error 级别日志中，同时用一条简洁的业务提示告诉调用方发生了什么。

三、给日志加上可执行的观测规则

日志本身不是监控。可以围绕稳定字段建立三类规则：错误率突然升高时告警，某个 trace_id 的请求耗时超过预算时自动关联上下游，重试次数达到上限时生成待处理事件。规则上线前先用一段真实样本验证查询条件，避免字段虽然存在却无法聚合。

最后，定期检查日志量和保留周期。高频成功日志可以采样，失败日志和关键状态变更应完整保留；对不同环境设置不同级别，既能控制成本，也能让真正有价值的信息更容易被看到。结构化日志的目标不是记录一切，而是让下一次故障定位有明确的入口。