直接根据我日常写代码、维护服务的经验把Python日志这块一次性说透。日志这玩意儿平时写代码的时候总觉得是小事出问题的时候才想起来当初没好好弄。但等你真的去维护一个跑了几百天的服务或者半夜三点被叫起来排查一个偶发问题就会发现日志写得规不规范直接决定了你是十分钟定位问题还是折腾到天亮。这篇东西我不打算给你抄官方文档那些你随时能查到。我想聊的是在生产环境里怎么把logging这个标准库用好用出真正扛得住事的配置以及那些文档里不会写、踩过坑才知道的细节。这篇内容适合谁看自己写脚本、写小工具但想让日志更规整的开发者项目从单文件脚本长成多模块服务、开始觉得日志乱成一团的团队以及看过不少最佳实践文章但真正上手配置时依然不知道该听谁的读者。我会从设计思路讲起逐步拆解配置、格式化、常见坑以及排查手段尽量让你读完能直接照着抄一套属于自己的日志方案。1. 先把日志这件事想清楚你究竟在记录什么很多人写日志的第一反应是把程序运行的事记下来这个想法没错但太模糊了。在实际动手配置之前我建议你先花几分钟想清楚一个问题日志文档在你这个项目里是给谁看的要在什么场景下派上用场。1.1 日志的本质是可回放的事故现场你可以把日志想象成飞机上的黑匣子它不是用来记录飞机正常飞行有多平稳的而是为了在出事之后能让调查人员凭借这些记录还原出事故发生前后到底发生了什么。代码里的日志也是同一个道理。print()打出来的东西是给你开发时看个热闹的而logging记录的内容是留着将来程序出问题、你需要快速定位时做现场分析的。所以这就引出了第一个原则日志记录的不应该是程序做了什么而应该是程序在什么状态、什么上下文下做了什么关键决策以及这个决策的结果是什么。同样是记录一条用户请求print(user login success)和logger.info(user login success, user_id%s, ip%s, cost_ms%d, ...)完全是两个层次的信息量。有一个很实在的检验标准如果你把日志拿到手里能不能凭它还原出程序的执行路径比如一个请求进来经过哪些函数中间的判断分支走了哪条最终返回了什么。如果答案是能的你的日志结构就是健康的。1.2 五个日志级别别上来就一刀切Python 的logging模块提供了五个标准级别从低到高分别是DEBUG、INFO、WARNING、ERROR、CRITICAL。很多项目的日志配置就失败在级别使用混乱上——要么全打INFO要么该用WARNING的地方用了ERROR导致后期过滤问题非常痛苦。我个人的使用习惯是这样的你可以参考DEBUG开发诊断用。变量值、函数入参、中间计算结果、分支选择依据。这些日志只对开发阶段有价值生产环境默认关掉。INFO记录关键业务节点。一个请求进来、处理完成、退出系统、定时任务跑完一轮。这些日志让人能看出系统今天都干了什么但不能太频繁否则就是噪音。WARNING程序能继续跑但这事情值得被留意。例如重试了三次才连上数据库、接口响应时间超过警戒线、缓存命中率下降。它代表一种亚健康状态。ERROR程序某个功能因为异常没能完成但主进程还活着。比如某个用户请求处理失败、消息队列消费出错被跳过需要有人来关注和修复。CRITICAL整个系统或核心模块已经无法正常工作比如数据库彻底连接不上、配置加载失败、无法写入文件。这才是真正需要立即处理的事。切记级别不是越高越好。如果你在代码里把正常的业务流转都记成ERROR第一日志量会爆炸第二告警会频繁触发到最后没人真的去看ERROR日志了真正的问题反而被淹没——这就是狼来了效应。1.3 该记录什么不该记录什么既然日志是事故现场就要搞清楚事故现场需要哪些证据。以最常见的 Web 服务为例一条高质量的日志通常应该包含以下要素时间戳精确到毫秒带上时区日志级别产生这条日志的模块、函数名最好是完整的代码位置文件 行号请求上下文request_id、user_id、session_id 等信息方便把零散日志串成一条完整的处理链路关键业务参数但不能是密码、token 等敏感信息执行结果如耗时、返回状态码异常时的完整堆栈traceback而不是只记一行出错了反过来什么东西不要记呢最有代表性的是这三类第一敏感信息绝对不要记入日志。我在实际项目里见过有人在日志里打出了用户的完整手机号和身份证号这不仅是隐私问题更是合规风险。密码、令牌、Cookie、支付信息任何凭证性质的数据都不能进日志。如果你确实需要记录某个标识做脱敏处理比如手机号只保留前3后4位。第二过于高频的循环日志不要记。比如在一个每秒执行很多次的核心循环里每次迭代都打一条INFO或DEBUG日志对性能的影响是实实在在的而且日志文件会疯狂膨胀最后把磁盘写满。第三无上下文信息的裸日志不要记。例如业务代码里孤零零的一句logger.error(query failed)——哪个 query哪张表什么参数没有上下文这条日志基本没用。2. 把基础配置写对Logger、Handler、Formatter 的关系搞清楚了日志是给谁看的、记什么内容之后接下来就要看怎么配置了。很多新手第一次接触logging的配置会觉得头大因为它的概念不少Logger、Handler、Formatter、Filter、Level它们之间的关系其实可以用一个流水线的类比来讲清楚。2.1 一个生产环境可用的基础配置模板先给出一份我平时最常用、也是我给团队定的标准基础配置你可以直接抄走。这份配置用的是dictConfig方式比在代码里一行行setLevel要清晰得多也方便后续修改。import logging import logging.config import sys LOGGING_CONFIG { version: 1, disable_existing_loggers: False, formatters: { standard: { format: %(asctime)s [%(levelname)s] %(name)s (%(filename)s:%(lineno)d) - %(message)s, datefmt: %Y-%m-%d %H:%M:%S %z }, verbose: { format: %(asctime)s [%(levelname)s] %(processName)s %(threadName)s %(name)s (%(filename)s:%(lineno)d) - %(message)s, datefmt: %Y-%m-%d %H:%M:%S %z } }, handlers: { console: { class: logging.StreamHandler, level: DEBUG, formatter: standard, stream: ext://sys.stdout }, file: { class: logging.handlers.RotatingFileHandler, level: INFO, formatter: verbose, filename: app.log, maxBytes: 10485760, # 10MB backupCount: 5, encoding: utf-8 } }, loggers: { : { # root logger handlers: [console, file], level: DEBUG, propagate: False }, # 第三方库的日志级别单独控制避免刷屏 urllib3: { handlers: [console], level: WARNING, propagate: False }, requests: { handlers: [console], level: WARNING, propagate: False } } } logging.config.dictConfig(LOGGING_CONFIG)这份配置里有几个点值得单独拿出来讲因为它们就是最常见的坑。2.2 Handler 的正确姿势Console 与 File 并存我喜欢把日志同时输出到控制台和文件但这两者的级别通常不一样。控制台用DEBUG方便本地开发和调试时看到尽可能多的细节文件用INFO避免生产环境下过量的DEBUG日志把磁盘撑爆。这里有个细节如果是在生产环境跑容器我一般会把控制台 Handler 的级别设为INFO因为容器环境下日志采集通常是直接读标准输出的文件反而不重要。所以你的部署方式决定了文件日志值不值得写。文件这块我强烈推荐用RotatingFileHandler而不是简单的FileHandler。RotatingFileHandler能按大小自动切割避免单个日志文件无限膨胀。上面配置里的maxBytes设为 10MBbackupCount设为 5也就是说日志总量最多控制在 60MB 左右这对绝大多数小型服务来说足够了。如果你的日志量特别大比如每一秒都有几百条日志那就要考虑TimedRotatingFileHandler按时间切割或者直接把日志输出到标准输出交给容器日志管理方案去统一处理。再补充一个很多人忽略的细节StreamHandler默认的输出流是sys.stderr不是sys.stdout。如果你的服务是把标准输出用于业务数据输出、标准错误用于诊断信息的那就得在配置里显式指定stream: ext://sys.stdout。否则你会发现自己明明在print业务结果却被混在一大堆日志里。2.3 Formatter 格式设计一个字段都不要浪费日志格式看起来是个小事但选对字段能大幅提升定位问题的效率。我看过太多项目用的格式是这样的%(levelname)s: %(message)s。这种格式在单机小脚本里够用但只要项目稍微大一点就真的不够看了。一个好的日志格式应该能让你回答四个问题这条日志是什么时候发生的什么级别发生在哪个模块哪个函数当时在干什么所以我的标准格式里包含了时间戳、级别、Logger 名称%(name)s通常就是模块名、代码位置文件名和行号再加上消息本身。进程名和线程名我一般放在verbose格式里只有在排查并发问题或者多进程问题时才会用到。这里有一个很实用的小技巧%(lineno)d一定要加上。有了行号你在日志里看到一条ERROR就能直接跳转到出错的代码行而不用在几百行的函数里来回找。这个字段的成本极低但回报极高。时间戳的时区问题也值得一提。默认的asctime获取的是本地时间如果宿主机时区没有正确配置你看到的日志时间和真实时间就对不上。我的习惯是在datefmt里显式加上%z时区偏移量同时建议服务器统一设为 UTC 时间。团队协作时日志时间统一用 UTC比各看各的本地时间要省去无数扯皮。3. 生产级技巧上下文信息、结构化与自定义异常处理基础配置做好之后你的日志系统已经能用了。但要说它是生产级最佳实践还差得远。接下来这几个进阶技巧才是让日志真正在关键时刻帮你一把的关键。3.1 用 Filter 实现请求上下文串联这是我最推荐的进阶操作。我给你描述一个场景一个接口在处理某个用户的请求时内部调用了数据库、调用了外部 API、还做了一些计算在某一步抛了异常。如果你的日志里每条消息都是孤立的你要怎么定位这个请求到底是哪一步出了问题你只能靠时间去猜或者去别的日志里碰运气。解决办法是给每条日志打上request_id。具体做法是利用logging.Filter。Filter可以往日志的LogRecord对象上动态附加字段你只需要在每次请求进来的时候生成一个request_id然后把它附加到当前线程的所有后续日志上之后无论是INFO还是ERROR所有日志都会带上同一个request_id按它一过滤整个请求的生命周期就串起来了。举个用threading.local实现的简单例子import logging import threading import uuid # 用 threading.local 保存当前线程的 request_id _local threading.local() def set_request_id(request_id: str): _local.request_id request_id class RequestIdFilter(logging.Filter): def filter(self, record: logging.LogRecord) - bool: # 从线程局部存储中取出 request_id附加到日志记录上 record.request_id getattr(_local, request_id, -) return True # 在 formatter 中加入 %(request_id)s # 在 handler 上添加 filter handler logging.StreamHandler() handler.addFilter(RequestIdFilter())在实际的 Web 框架里你通常会在中间件层调用set_request_id在请求结束或异常时再清掉。这样每条日志都带上了request_id排查问题时一条grep request_idxxx就能把整个调用链路拉出来。如果你用的是 Python 3.7还可以用contextvars替代threading.local它在异步场景下更可靠能正确地在不同的Task之间隔离上下文。3.2 使用 Logging Adapter 或 Formatter 提升日志信息量除了Filter还有一个工具叫LoggerAdapter它可以在调用logger.info()的时候自动附加额外字段。比如你有一个服务每条日志都想带上环境名称dev、prod和服务版本号用LoggerAdapter就很方便logger logging.getLogger(my_service) logger logging.LoggerAdapter(logger, {env: prod, version: 1.3.0})以后每次logger.info(user register success)输出的消息里都会自动带上envprod和version1.3.0不需要每次手写。这个技巧在跑多个环境、多个版本的服务时尤其有用日志里带上环境信息能避免在测试环境的日志里排查生产问题这种尴尬。另外从 Python 3.2 开始logging还支持在setLogRecordFactory里自定义LogRecord构造逻辑可以为所有日志统一附加自定义字段。但说实话日常项目中用Filter或LoggerAdapter就够用了setLogRecordFactory更适合写框架或准备长期演进的底层库。3.3 异常写进日志的正确姿势有异常处理的代码里很多人会这么写try: result do_something() except Exception as e: logger.error(f出错了: {e})问题在哪第一f-string 里直接塞e只能拿到异常的消息字符串拿不到完整的堆栈。第二就算你已经有了异常对象如果不用exc_infoTrue堆栈信息也不会被记录进来。正确的写法有两种。如果你只是想记录但没有重新抛出的需求try: result do_something() except Exception: logger.exception(业务处理失败请检查)logger.exception()是logger.error(..., exc_infoTrue)的简写它会自动带上当前异常栈。如果你是在捕获后还要继续处理或者需要不同级别也可以写为try: result do_something() except Exception: logger.error(业务处理失败请检查, exc_infoTrue)加了exc_infoTrue之后日志消息后面会跟着完整的 Traceback包括异常发生位置、调用链以及每次调用的代码行号。这才是事故现场应有的完整证据。没有堆栈的异常日志基本等于什么都没写。4. 常见坑与排查技巧我踩过的那些坑再好的配置也会在实际使用中踩到一些意想不到的坑。我把自己在项目和团队里遇到过的、以及网上很多人问过的高频问题整理在这里都是拿钱买来的教训。4.1 日志重复输出的根源很多人在部署后发现自己每条日志出现两遍甚至三遍第一反应是代码里多创建了几个handler。但根子往往在层级 Logger 的传播机制上。logging模块里Logger 默认有一个propagateTrue属性意思是当前 Logger 处理完日志后会把这条日志继续传播给父级 Logger直到 root logger。如果你在上面代码里设置了 root logger 的 handler又在子模块通过logging.getLogger(__name__)创建了自己的 Logger并且给这个 Logger 也单独加了 handler那么一条日志就会被子 Logger 的 handler 和 root logger 的 handler 各打一遍造成重复。解决方式有三选一子 Logger 上设置propagateFalse切断传播或者只给子 Logger 配 handler不配 root或者统一只用 root 配置子 Logger 只负责指定级别。我个人的习惯是业务模块的子 Logger 一律设置propagateFalse并显式指定自己的 handler避免各种意外的层级继承。4.2 Handler 泄漏与内存问题另一个不太常见但影响很大的坑是FileHandler打开的文件句柄泄漏。如果你在循环里反复创建同一个 name 的 Logger或者每次请求都新建 handler时间一长系统会报 Too many open files。这通常出现在有人图省事在函数内部调用logging.basicConfig()或动态addHandler的场景里。正确做法是全部 Logger 和 Handler 的配置都放到应用启动阶段做一次之后代码里只用getLogger()去取已有的实例绝不要运行时反复添加 Handler。4.3 性能优化异步日志默认的FileHandler是同步写入磁盘的。在高并发场景下如果日志量很大写日志本身会成为瓶颈拖慢业务接口的响应速度。有一个解决办法是用QueueHandler和QueueListener做异步日志业务线程只负责把日志放入内存队列后台独立线程负责把队列中的日志写入文件。这样业务线程不会被磁盘 I/O 阻塞。需要注意的是异步日志带来的问题是如果进程在日志还没来得及写完时崩溃这部分日志会丢失。对于严格需要持久化的审计类日志谨慎使用异步方案对于一般业务日志这是性价比极高的优化。4.4 排查定位从日志反推问题最后聊一聊有了日志之后怎么用它快速定位问题。我的排查套路通常分三步第一步根据请求线索在日志平台或文件里找到相关日志。有了request_id之后这一步就是一条grep request_idxxx的事。第二步按时间线把日志读一遍重现程序当时的执行路径。看关键节点的日志级别和消息内容判断是哪一步偏离了预期。第三步针对异常错误看完整堆栈定位到具体代码行。如果有上下文信息参数值、函数调用入参基本能快速判断是数据问题、环境问题还是逻辑问题。有个实用技巧排查问题的时候临时把某个模块的日志级别调到DEBUG拿到细节之后迅速恢复。配置可以通过环境变量控制比如LOG_LEVELDEBUG python main.py避免为了调试去改代码。5. 一套完整的实践指南从零搭建你自己的日志体系说了一大堆我来把这些经验浓缩一下吧。如果你是从零开始给一个新项目配置日志体系照着这个流程走基本不会出大错。5.1 按项目类型选择切入方案不同规模的项目日志体系的复杂度应该不同单文件脚本、爬虫、自动化任务basicConfig配一个RotatingFileHandlerINFO级别够用就行。中小型服务Web API、微服务dictConfig统一配置console RotatingFileHandler带上request_id过滤器。大型分布式服务配置维度上会增加更多考虑比如日志集中采集、结构化 JSON 日志、链路追踪标识等。这时日志输出目标通常是标准输出交给日志采集系统去统一处理。5.2 给出我常用的完整 dictConfig 示例这一段是我在多个实际项目中总结出的一个通用配置模板适合中小型 Python Web 服务直接参考。import logging.config LOGGING_CONFIG { version: 1, disable_existing_loggers: False, formatters: { json: { class: pythonjsonlogger.jsonlogger.JsonFormatter, format: %(asctime)s %(levelname)s %(name)s %(filename)s %(lineno)d %(message)s %(request_id)s }, plain: { format: %(asctime)s [%(levelname)s] %(name)s (%(filename)s:%(lineno)d) request_id%(request_id)s - %(message)s, datefmt: %Y-%m-%d %H:%M:%S %z } }, handlers: { console: { class: logging.StreamHandler, level: INFO, formatter: plain, stream: ext://sys.stdout }, json_file: { class: logging.handlers.RotatingFileHandler, level: INFO, formatter: json, filename: app.json.log, maxBytes: 10485760, backupCount: 5, encoding: utf-8 } }, filters: { request_id: { (): your_module.RequestIdFilter } }, loggers: { : { handlers: [console, json_file], level: INFO, propagate: False, filters: [request_id] } } } logging.config.dictConfig(LOGGING_CONFIG)这个配置里用到了 JSON 格式化日志的写法。在容器和微服务环境下JSON 日志是标配因为日志平台直接按字段解析、聚合、搜索比解析纯文本要高效得多。pythonjsonlogger是一个第三方库但接口很稳定用了很多年没有出过问题。如果你对依赖第三方库比较谨慎也可以自己写一个Formatter子类来输出 JSON 格式核心其实就是把LogRecord的字段收集起来json.dumps一下。5.3 一处配置与实际验证步骤配置写好之后一定要验证别等上线了才发现日志根本没生效。验证步骤很简单但也容易漏先在本地调起应用观察控制台输出是否正常。接着造一条测试日志确认文件日志正确追加。再次确认切割是否生效可以临时把maxBytes调成很小的值比如 1024 字节打出超出这个大小的日志量看看文件是否按预期轮转并且旧文件还保留在目录里。最后确认日志里的时间、时区、request_id 等字段都符合预期。还有一个很容易忽略的验证点确认异常日志的堆栈是否完整。故意在代码里抛个异常用logger.exception捕获然后打开日志文件看看有没有完整的Traceback。我在实际项目中还有一个习惯新服务上线第一周会格外留意日志内容本身的质量。看看哪些日志是噪音、哪些关键步骤没有记录、哪些日志缺上下文。日志体系是动态演进的东西不是配好就一劳永逸的。我在实际使用中发现Python 日志这件事最难的部分往往不是技术配置而是在写业务代码的那一瞬间愿不愿意多花几秒钟把日志写得更完整。一个带着完整上下文的INFO日志比十个事后补的ERROR日志更能救命。每次写日志前你都不妨问自己一句话如果三个月后的我拿到这条日志能不能一眼看懂当时发生了什么如果能这条日志就是合格的。