structlog：Python 结构化日志的标准答案

structlog：Python 结构化日志的标准答案

日志这东西，每个项目都有。但日志量一旦上来，查阅就成了麻烦。传统日志是一大段文本，想从中提取关键信息，得靠正则表达式硬扒。结构化日志把日志变成键值对或 JSON，直接就能过滤和查询。

Python 生态里做结构化日志的库不少，structlog 是其中一个积淀很深的项目。4800 多 Star，从 2013 年就开始在生产环境使用，到现在已经跑了十几年。

核心思路：函数加字典

structlog 的设计很简单。日志生成被拆解成一系列函数调用，每个函数接收并返回字典。最终的字典再被渲染成 JSON、logfmt 或者带颜色的控制台文本。

这个设计有几个直接好处。一是日志数据本身变成了结构化对象，不再是纯字符串。二是每个处理步骤都可以自定义，想加字段、改格式、过滤内容，都是改一个函数的事。三是 API 依然保持熟悉，对习惯标准库 logging 的人来说上手很快。

README 上列了三个关键词：Simple、Powerful、Fast。简单是因为底层全是函数和字典；强大是因为这种设计留下了足够的扩展空间；快是因为它没有被老旧设计束缚，灵活性没有以性能为代价。

输出格式自由切换

structlog 内置支持三种输出格式。JSON 适合对接日志收集系统，比如 ELK 或 Grafana。logfmt 是一种紧凑的键值对格式，适合命令行查看。控制台输出则带颜色和高亮，本地开发时看着舒服。

如果你已经在用标准库的 logging 模块，也可以不让 structlog 直接输出，而是把处理好的日志字典转发给现有系统。迁移成本很低，不用推倒重来。

十几年生产验证

这个项目从 2013 年开始就在各种规模的生产环境里跑。期间 Python 生态经历了 asyncio、类型提示、上下文变量等新特性的引入，structlog 都及时跟进了。它的设计思路甚至影响到了其他语言生态的日志库实现。

作者 Hynek Schlawack 在 Python 社区很有名，维护过多个广泛使用的库。项目的可持续性不用太担心。

什么时候该用它

如果你正在写 Python 项目，日志还停留在字符串拼接的阶段，可以认真考虑一下 structlog。特别是以下场景：

日志需要被日志平台解析和索引
希望在日志里自动附加请求 ID、用户 ID 等上下文信息
想在开发和生产环境使用不同的日志格式
厌倦了大段日志文本里找关键信息的体验

安装很简单，pip 直接装。文档写得也很全，有从零开始的教程供新手入门。

一点局限

structlog 专注在日志的生成和格式化环节。它不负责日志的收集、存储和告警。你需要配合其他工具来完成完整的日志链路。但这不算缺点，专注做好一件事本身就是 Unix 哲学的体现。

总的来说，structlog 是一个经过时间检验的工具。它没有在日志这件事上搞过度设计，而是给了一个清晰、可扩展的结构化日志方案。对于想要升级日志系统的 Python 项目，这是个靠谱的选项。

清晰、可扩展的结构化日志方案。对于想要升级日志系统的 Python 项目，这是个靠谱的选项。