得说句实在话：在Python项目里，日志这件事你早晚得认真对待。开发阶段print加满，看起来一切正常，等上了生产环境出故障，你才发现print出来的东西既没有时间也没有级别，连哪一行代码打出来的都可能对不上。这时候你需要的不是print，而是一套规范的日志体系。Python标准库里的logging模块足够强大，搞懂它之后，无论是爬虫脚本、数据分析任务，还是量化交易策略这类长期跑批的任务，日志就是你观察系统状态的"眼睛"。这篇文章我会把Python日志记录（Logging）从核心机制到生产级配置全部拆开讲，顺便把那些文档里不会写、但实战中容易踩的坑都给你指出来，适合正在从"print调试"转向系统化日志管理的开发者参考。
1. 项目重点与整体设计思路
1.1 为什么基于标准库logging而不是print
先聊点最基础但最容易被忽略的：为什么日志记录最终要落到logging模块上。不少初学者（包括刚工作的我）习惯全程print，觉得简单直接。但print本质上是往标准输出写字符串，它有四个绕不开的短板。
第一，print没有分级概念。开发时你恨不得把每个变量都打出来，但这些信息到生产环境可能是噪音。logging天然有DEBUG、INFO、WARNING、ERROR、CRITICAL五级，你可以通过一行配置切换整个项目的输出粒度，比如线上只输出WARNING以上，排查问题时再临时降到INFO。print做不到这种动态调整，除非你满屏写if。
第二，print的输出目标单一。它只能打到控制台，而生产环境里日志往往要落盘、要按天切割、要推送到集中采集平台。logging的handler机制把"输出到哪里"和"记录什么"解耦了，控制台加文件、按大小滚动、按日期切换，这些都是配置项的问题，而不是代码结构的问题。
第三，print拼装字符串代价高。一个高频执行的分支里，如果每次print都去做一次字符串拼接，性能损耗是实实在在的。logging允许你延迟格式化：logger.debug("当前用户: %s, 结果: %s", user, result)，只有当这条日志真的要被输出时，字符串拼接才会发生。
第四，print无法与上下文联动。你很难给print统一加上请求ID、时间戳、文件名、行号这些信息，除非每个print都手动拼一遍——那代码就没法看了。logging的Formatter可以统一格式化，配合Filter还能往日志里注入自定义字段，这是做链路追踪和统计分析的基础。
所以我说，print只是调试工具，logging才是工程日志的底子。这套判断放在爬虫、Web服务、数据处理脚本上都成立。
1.2 这套实践方案的适用场景与要解决的问题
我这套"最佳实践"不是纯理论推演，而是从实际项目里踩出来的。先说适用场景：任何运行时间超过10分钟、需要重复执行、或者部署到服务器上的Python程序，都应该立刻套用。具体来说，我针对的是三类高频场景。
一是爬虫任务。爬虫经常要跑几小时甚至几天，中间可能有请求失败、IP被封、解析异常。如果只靠print，跑挂了之后你想知道"挂在哪一步"都无从下手。带上时间戳和日志级别后，你可以按ERROR级别快速过滤出失败点。
二是数据分析与量化交易脚本。这类任务通常按策略批次跑，数据量大、运行周期长，而且经常依赖外部数据源。日志里记录每次调仓的触发条件、数据快照的更新时间、异常数据的行号，能让你回看整个决策链路。
三是Web服务和接口服务。这类场景下日志不仅要给人看，还要被日志采集系统消费，所以结构化输出（比如JSON格式）几乎是刚需，同时必须考虑日志文件的安全切割，避免磁盘被写满。
这套实践要解决的核心问题可以归纳成三个：第一，让日志有统一格式和级别，不依赖开发者个人习惯；第二，让日志可配置可切换，不同环境用不同策略；第三，让日志承载足够的上下文信息，出问题时能还原现场。
2. Logging模块核心机制剖析
2.1 四类核心组件的职责边界
logging模块不是一个大而全的怪兽，它由四类核心组件分工协作。理解这四者的边界，是整个最佳实践的地基。
Logger（记录器）是你代码里直接调用的对象。你调用logger.info("xxx")，Logger负责根据级别判断"这条日志要不要记录"，如果决定记录，就把LogRecord对象交给挂在自己身上的Handler们。Logger本身不关心日志最终去了哪里，它的职责是"裁决"。
Handler（处理器）负责"出口"。它决定了日志写到文件、打到控制台，还是通过HTTP发到远端采集服务。同一个Logger可以挂多个Handler，比如同时挂控制台和文件，这样开发时看终端、出问题时查文件。Handler内部还有自己的级别设置，也就是"接到日志后，达到什么级别才真正写入"。
Formatter（格式化器）负责"长什么样"。它把LogRecord里的时间、模块名、级别、消息内容拼成最终输出的字符串。Formatter只属于Handler，一个Handler可以配一个Formatter，不同Handler可以用完全不同的格式——文件里多带上下文，控制台里保持简洁。
Filter（过滤器）负责"准入控制"。它比级别过滤更灵活，可以自定义任意规则，比如只让某个模块的日志通过、给日志追加业务字段。Filter可以挂在Logger上，也可以挂在Handler上。挂在Logger上时，它会在日志产生源头过滤；挂在Handler上时，只在那个出口过滤。
我用一个类比帮你记住：Logger是写日记的人，Handler是投递员，Formatter是排版员，Filter是审查员。写日记的人决定哪些事值得写，投递员决定送到哪、要不要送，排版员决定最后印出来的字体和版面，审查员可以随时把某段内容毙掉。
2.2 日志级别与层级传播机制
logging的级别从低到高依次是DEBUG、INFO、WARNING、ERROR、CRITICAL。每个级别对应一个数字值，DEBUG是10，INFO是20，WARNING是30，ERROR是40，CRITICAL是50。判断是否记录日志时，核心逻辑是：LogRecord的有效级别 >= Logger的有效级别，这条日志才会被处理。Handler那边也有同样的级别比较，只有同时通过两边的门槛，日志才会真正落盘。
这里有个新手极容易忽略的传播机制。Logger对象是按名字组织的，名字带点号就表示层级关系。比如你写了logger = logging.getLogger("app.service.user")，它就自动成为logger = logging.getLogger("app.service")的子logger，而app.service又是logger = logging.getLogger("app")的子logger。默认情况下，一条日志在被Logger处理之后，如果Logger的propagate属性为True（默认就是True），这条日志会继续向上抛给父Logger，让父Logger的Handlers也处理一遍。
这个设计的本意是让"父级统一收口"：你可以在根Logger上挂一个文件Handler，所有子Logger打出来的日志最终都汇聚到这个文件里，不需要每个模块单独配Handler。但正是这个机制，催生了后面要讲的"日志重复输出"问题——子Logger自己挂了Handler，同时父Logger也挂了Handler，日志就会被打两遍。
有个细节值得单独提：根Logger（名字是空串）的默认级别是WARNING，而且默认没有Handler。如果你在代码里直接调logging.info("xxx")，用的就是根Logger，在没有任何配置的情况下，WARNING级别以下的日志会被直接丢弃，连报错都不会有。这就解释了为什么很多人写logging.info却什么都不输出——不是没打日志，是级别门槛挡住了。
2.3 为什么官方默认的Root Logger容易让人踩坑
围绕根Logger的坑，我见得太多，基本可以总结成三条。
第一条，默认级别是WARNING。很多新手第一次用logging.info("hello")，发现控制台什么都没打印，第一反应是"模块坏了"。其实模块没坏，只是默认级别把它拦了。解决方法是显示设置级别：logging.basicConfig(level=logging.INFO)。
第二条，初始化顺序影响很大。basicConfig只在"根Logger没有任何Handler"时才会生效。如果你先调了logging.info创建了一条日志，Python会顺手给根Logger挂一个lastResort处理器（只输出WARNING以上到stderr），之后你再调basicConfig挂文件Handler，会发现文件Handler根本加不上。这就是为什么很多人在交互式环境里反复试basicConfig，时灵时不灵。所以要么在程序入口最顶部就完成配置，要么彻底用dictConfig统一接管。
第三条，多模块混合使用时的风格割裂。有的模块用root logger直接打，有的模块自己getLogger("module")，有的模块又手动添加Handler，最后项目的日志输出路径五花八门，排查问题时特别痛苦。官方推荐的规范是：非入口模块一律用模块级logger = logging.getLogger(name)，不要在模块内部自行添加Handler，所有Handler的统一配置都交给入口处完成。这样职责清晰，日志的"出口"全局唯一。
3. 配置方案选型与实操要点
3.1 三种配置方式对比：basicConfig、dictConfig、代码配置
配置logging有三种主流姿势，我按推荐程度排个序。
第一种，basicConfig。它是为简单脚本准备的实用函数，一行代码就能完成"设置级别+挂控制台Handler+统一定制格式"三件套。优点是快，缺点是只对根Logger生效，而且只能在首次调用时生效。它适合那种跑一次就退出的工具脚本，比如数据清洗脚本、临时爬虫抓取。如果业务规模到了一二十个模块，basicConfig就不够看了。
第二种，dictConfig。这是我最推荐的生产级方案。它接受一个Python字典，把Logger、Handler、Formatter、Filter的结构全部声明式地描述出来。好处非常明显：整个日志体系变成了一份可读的配置，而不是散落在代码里的赋值语句；你可以把字典写成YAML或JSON文件，让运维同学不碰代码就能调整日志级别和输出路径；它还天然支持"禁用已有Logger""设置Logger的propagate属性"这类进阶操作。唯一的学习成本是你需要理解它的配置结构，但这份结构其实就是logging组件概念的直接映射。
第三种，纯代码配置。也就是手写logger = logging.getLogger()、handler = logging.FileHandler(...)、logger.addHandler(handler)这套流程。它最灵活，能塞入任意自定义逻辑，比如根据环境变量动态决定是否挂远端Handler。缺点是代码量偏多，而且很容易出现"配置分散"的问题——一个项目里不同模块各配各的，最终变成一团乱麻。我建议它只用来做顶层入口的动态补充，项目整体配置还是走dictConfig。
这三种方式的取舍，我用一个适用场景表来说清楚。
| 配置方式 | 优势 | 劣势 | 推荐场景 |
|---|---|---|---|
| basicConfig | 简单直接，零学习成本 | 只作用于根Logger，无法精细化控制 | 一次性脚本、快速验证 |
| dictConfig | 结构化强、易维护、可配置文件化 | 需要理解配置结构 | Web服务、长驻任务、多模块项目 |
| 代码配置 | 最灵活，可嵌业务逻辑 | 代码冗余、配置易分散 | 顶层入口的少量补充逻辑 |
3.2 一个可以直接复制的生产级dictConfig模板
先给一套我在项目里常用的配置骨架，再拆开解释关键项。
import logging.config LOGGING_CONFIG = { "version": 1, "disable_existing_loggers": False, "formatters": { "standard": { "format": "%(asctime)s [%(levelname)s] %(name)s: %(message)s" }, "detail": { "format": "%(asctime)s | %(levelname)s | %(name)s | %(filename)s:%(lineno)d | %(message)s" } }, "handlers": { "console": { "class": "logging.StreamHandler", "level": "DEBUG", "formatter": "standard", "stream": "ext://sys.stdout" }, "file_rotating": { "class": "logging.handlers.RotatingFileHandler", "level": "INFO", "formatter": "detail", "filename": "logs/app.log", "maxBytes": 10 * 1024 * 1024, "backupCount": 5, "encoding": "utf-8" }, "file_error": { "class": "logging.handlers.RotatingFileHandler", "level": "ERROR", "formatter": "detail", "filename": "logs/error.log", "maxBytes": 10 * 1024 * 1024, "backupCount": 5, "encoding": "utf-8" } }, "loggers": { "app": { "level": "DEBUG", "handlers": ["console", "file_rotating"], "propagate": False }, "app.error": { "level": "ERROR", "handlers": ["file_error"], "propagate": False } }, "root": { "level": "INFO", "handlers": ["console"] } } logging.config.dictConfig(LOGGING_CONFIG)这套配置里值得注意的细节有几个。
第一，handlers里的RotatingFileHandler按日志文件大小滚动切割，maxBytes设成10MB，backupCount设成5个备份。这样做的好处是日志文件不会无限膨胀占满磁盘，这是长时间跑批任务最怕的事故之一。如果你想要按日期切，可以直接听TimedRotatingFileHandler，加一个when="midnight"参数。
第二，日志级别是双层的。Logger的level和Handler的level都能过滤，它们的含义不同。Logger的level决定"日志产生时是否放行"，Handler的level决定"到达出口时是否放行"。实际调优时，我建议统一调Logger的level，Handler的level只做降级收窄用，比如上面error.log只接ERROR以上，避免把INFO日志全塞进错误文件里。
第三，encoding="utf-8"千万别漏。Windows上如果不设这个参数，日志里一旦有中文，很可能直接抛出UnicodeEncodeError，或者落盘文件变成乱码。这一步我吃过不少亏，每次配置模板都把这个参数默认拉上。
3.3 多模块项目的Logger命名与获取规范
logging.getLogger(name)的name参数，说简单也简单，说讲究也讲究。标准姿势是每个模块在顶部写：
import logging logger = logging.getLogger(__name__)这里用__name__的好处在于，Python的__name__天然就是你模块的完整限定名，比如app.service.user。这样Logger的层级自动和包结构对齐，你在日志里看到logger名字，就能直接定位到源码位置。
这种命名方式还有一个隐藏收益：它可以配合dictConfig里的loggers节点做"批量定向"。比如你在loggers里配置了"app"这个Logger，那么所有以"app."开头的子Logger都会继承它身上配置的Handler链——除非子Logger自己显式设置了propagate=False。也就是说，你在dictConfig里只需要配好顶级Logger，整个项目的日志输出策略就统一了。
但这里有个需要克制的地方：不要在业务模块里反复调用logging.getLogger("app.user")这种硬编码名字。硬编码名字会在团队协作时造成混乱，同一模块在不同团队拷贝时有差异，日志来源就难看了。统一走__name__，配合入口处的一套dictConfig，整个项目的日志就能保持整齐划一。
4. 实操过程与核心环节实现
4.1 从零到一：搭建一个项目级日志模块
说再多理论不如看一次实际操作。我挑一个典型的量化交易脚本项目，一步步把日志体系搭起来。
假设项目结构是这样：
quant_project/ ├── main.py ├── config.py ├── logging_config.py └── strategy/ ├── __init__.py ├── signal.py └── executor.py第一步，在logging_config.py里定义dictConfig配置（代码同上面3.2那套，路径换成项目相对路径），提供一个load_logging_config()函数，负责读取配置并调用dictConfig。
第二步，在main.py的入口函数最顶部初始化日志：
from logging_config import load_logging_config def main(): load_logging_config("config/logging.yaml") logger = logging.getLogger(__name__) logger.info("量化策略任务启动") # 业务逻辑...init在什么时候调非常关键，一定要放在任何业务模块import之后、但必须在第一次打日志之前。否则先打的日志会落到root的默认行为上，后面再切配置就晚了。
第三步，业务模块里只取logger，不配Handler：
# strategy/signal.py import logging logger = logging.getLogger(__name__) def generate_signal(data): logger.debug("开始生成信号, 数据行数: %s", len(data)) # 业务逻辑... logger.info("信号生成完成, 共 %s 个", len(signal_list))这套结构的核心思想是"配置和业务隔离"。业务代码里只负责调logger.info或logger.error，具体输出到控制台还是文件、用什么格式、切不切割，全部交给入口配置。哪天你想把日志接入集中采集平台，只需要改配置文件，业务代码一行不动。
4.2 异常与堆栈信息记录的规范用法
日志记录异常信息，是很多人容易写得不对的地方。用错了方法，日志里只有一行"程序出错了"，等于没记。记录异常有两个常用姿势，分别适用不同场景。
第一个姿势：logger.exception(e)。它本质上就是logger.error(msg, exc_info=True)，但它会在ERROR级别自动带上当前异常堆栈。它用在except语句块内部，记录的是"刚刚捕获到的那个异常"。这是我最常用的方式。
try: result = api_client.fetch_data(symbol) except RequestException as e: logger.exception("拉取 %s 行情失败: %s", symbol, e) raise第二姿势：logger.error(msg, exc_info=True)。如果你在异常处理的外层，上下文信息已经不完整，或者你想主动记录某个异常对象，可以用exc_info参数强制把堆栈打出来。注意，exc_info=True不是记录e本身，而是向处理器请求当前线程的异常堆栈信息。
还有个容易忽略的细节：在日志消息里不要用str(e)替代exc_info。str(e)只给了你异常描述，堆栈还是空的。出问题的时候，你不仅要看什么错，更要看在哪一行错的、调用链是什么样的。
我在实际项目里还有一个习惯，就是在except块里用logger.exception之后，再把关键的状态字段（比如策略名称、当前持仓、当前价格）用logger.info或logger.warning单独记一条。这样堆栈信息归堆栈信息，业务上下文归业务上下文，排查时不用从一大串堆栈里猜业务现场。
4.3 结构化日志：为采集和分析打底
说到日志的长期价值，不得不提结构化。传统文本日志人眼看得方便，但机器分析起来很吃力。现在主流的日志清洗链路（比如Loki、ELK、ClickHouse）都喜欢JSON格式，因为字段可以直接映射成索引，检索和聚合效率高得多。
好消息是，不引入任何第三方库，logging就能输出JSON。
import json import logging class JsonFormatter(logging.Formatter): def format(self, record): log_data = { "ts": self.formatTime(record, "%Y-%m-%d %H:%M:%S"), "level": record.levelname, "logger": record.name, "message": record.getMessage(), "module": record.module, "line": record.lineno, } if record.exc_info: log_data["exc_info"] = self.formatException(record.exc_info) # extra 字段合并 for key, value in record.__dict__.items(): if key not in log_data and not key.startswith("_"): log_data[key] = value return json.dumps(log_data, ensure_ascii=False)这个格式器有几个设计点。一是ensure_ascii=False，确保中文正常显示而不是被转成\uXXXX。二是把exception信息单独作为exc_info字段。三是把record.__dict__里的extra字段透传进来，这样你在代码里logger.info("...", extra={"request_id": "abc123"})，这个request_id就会出现在JSON里。
结构化日志最大的收益，是你能在日志采集平台上直接跑查询：按level=ERROR过滤、按logger=quant.strategy.signal过滤、按request_id聚合一次请求的全链路日志。这种能力在故障复盘时价值巨大。
实际项目里，如果日志量特别大，我建议把JSON格式Handler只挂在"采集出口"上，比如专门写一个文件或直接推Kafka，控制台则继续用人类可读的文本格式。这样开发和排障体验都不牺牲。
5. 常见问题与排查技巧实录
5.1 日志重复输出：到底是谁打印了两遍
日志重复输出是logging最经典的坑，我几乎在每个项目里都见到过。症状是：一条日志在控制台打印了两次，如果挂了多个Handler，可能在三四个地方各出现一次。
原因90%出在propagate上。看一个具体例子：
logger = logging.getLogger("app.service") handler = logging.StreamHandler() logger.addHandler(handler) logger.setLevel(logging.INFO) logger.info("hello") # 配置里又设置了 root 的 handler logging.basicConfig(level=logging.INFO)logger.info("hello")先被app.service自己的Handler处理一次，然后因为默认propagate=True，这条日志继续往上抛给root Logger，root上又有一组Handler，于是再处理一次，最终输出两遍。
排查这种问题时，不要瞎猜，按步骤来。第一步，打印logger的handler列表：logger.handlers，看看自己身上挂了几个Handler。第二步，检查propagate：logger.propagate。第三步，看root的Handler和级别。找到重复来源后，两条路可以走：要么在子Logger上设propagate=False，阻绝向上传播；要么只保留子Logger上的Handler，删掉root上多余的Handler。正规做法是"配置收口"——尽量只在一个层级的Logger上配置Handler，其他Logger只设级别。
我自己的项目管理规范是：除了入口配置，业务模块一律不手动addHandler。业务Logger基本只设propagate=True，把输出统一交给顶层Logger。这样从源头上就杜绝了重复输出。
5.2 日志丢失：配置了就是不输出
日志丢失的现象比重复更难查，因为涉及门级权限判断。我遇到过的典型场景是：子Logger级别配为"DEBUG"，但它把日志传播给了root，root的级别是WARNING，于是INFO级别的日志在root门口被拦截了，文件里什么都看不到。
排查这种问题，我的流程是四步。第一步，确认代码里调用的Logger是不是你配置的那个。第二步，检查Logger的level：logger.level和logger.getEffectiveLevel()。effectiveLevel会沿父链往上找，如果自己没有显式设置，就继承父Logger的。第三步，检查Handler的level。Logger放行了，Handler还有一道门。第四步，检查传播链上所有节点的级别。
还有一种低频但偶发的情况：程序入口调dictConfig之后，又有人手动调了basicConfig或者另建Logger并addHandler，把配置链打乱了。定位方法是在关键位置打logger.handlers、logging.root.handlers，看Handler列表是否符合预期。
这里我给一个调级的自查原则：输出不出来的日志，先改Logger的level；输出太多太杂的，先改Handler的level。大部分场景用这两条就能解决。
5.3 性能调优：别让日志拖慢业务
日志在业务眼里是"可丢弃的辅助成本"，所以性能问题不能忽略。我总结出三个常见性能负担点，以及对应的优化方案。
第一个负担点：不必要的字符串拼接。logging虽然做了延迟格式化，但前提是你传入的是参数而不是已经拼好的字符串。试比较：
# 不推荐：日志被丢弃前，字符串已经拼好了 logger.debug("用户 %s 的结果 %s" % (user, result)) # 推荐：延迟格式化 logger.debug("用户 %s 的结果 %s", user, result)第二个负担点：Debug级别日志在高频热路径上的判断成本。如果你有一段每秒执行几百次的代码，且需要打DEBUG日志，即使Logger级别是INFO导致日志不输出，函数调用参数本身和格式器判断仍有一点开销。这时候可以在打日志前加一层检查：
if logger.isEnabledFor(logging.DEBUG): logger.debug("debug detail: %s", expensive_compute())isEnabledFor避免了每次调用都去构造函数参数。如果参数本身需要昂贵计算，这层检查的收益非常明显。
第三个负担点：文件Handler的写入瓶颈。如果你每秒钟打上千条日志到同一文件，磁盘IO会成为瓶颈。优化方案包括：降低不需要的日志级别；使用RotatingFileHandler按大小切割避免单文件无限大；把日志写入和业务解耦，比如丢到一个异步队列里，由独立线程批量消费落盘。我在实际项目里最常用的是队列+独立线程方案，能让高并发场景下日志的写入开销基本不拖业务。
6. 最后再分享一点我自己的日志排查心得
做日志配置这么多年，我最大的体会是：日志配置一定要"趁早"，要在项目刚起步、代码量还不大的时候就定好规范，否则等几百个模块散落着各自的print和addHandler，再回头统一是一件非常痛苦的事。哪怕一开始只做最简单的basicConfig，也比没有强，因为至少有了统一的格式和时间戳。
还有一个实操小技巧。如果项目上了链路追踪，给每个请求分配一个request_id，你可以在入口过滤器里把request_id注入日志记录：
class RequestIdFilter(logging.Filter): def __init__(self, request_id): self.request_id = request_id def filter(self, record): record.request_id = self.request_id return True然后Formatter的格式串里加一个"%(request_id)s"字段。这样每条日志天然带上了请求标识，按request_id一筛，一次请求经过的所有模块日志都能串起来，排查问题效率直接翻倍。这个技巧在Web服务和异步任务里特别实用。
日志这件事，投入产出比其实很高。花半天时间把logging配置搭好，后续的每一天排查故障都在受益。希望这篇总结能让你少踩几个我踩过的坑。
