lesson24：Python的logging模块

你的电影很有趣2025-07-26 9:56

目录

前言

一、logging模块核心优势

二、基础组件与工作流程

三、配置方法全解析

[1. 基础配置（basicConfig）](#1. 基础配置（basicConfig）)

[2. 字典配置（dictConfig）](#2. 字典配置（dictConfig）)

[3. 文件配置（fileConfig）](#3. 文件配置（fileConfig）)

四、高级应用场景

[1. 日志轮转策略](#1. 日志轮转策略)

[2. 异常日志记录](#2. 异常日志记录)

[3. 结构化日志输出](#3. 结构化日志输出)

[4. 分布式系统日志](#4. 分布式系统日志)

五、生产环境最佳实践

[1. 日志级别使用规范](#1. 日志级别使用规范)

[2. 性能优化建议](#2. 性能优化建议)

[3. 安全注意事项](#3. 安全注意事项)

[4. 容器环境适配](#4. 容器环境适配)

六、常见问题解决方案

问题1：日志不输出

问题2：重复日志输出

问题3：中文乱码

七、扩展工具与生态

结语

前言

日志是软件开发中不可或缺的一环，它不仅能帮助开发者调试程序，还能在系统运行时提供关键的监控信息。Python标准库中的logging模块提供了灵活强大的日志功能，相比简单的print语句，它支持分级记录、多目标输出、格式定制等高级特性。本文将系统介绍logging模块的设计理念、核心组件和最佳实践，帮助你构建专业的日志系统。

一、logging模块核心优势

为什么要使用logging而不是print？这个问题在Stack Overflow上有超过100万次浏览，答案可以归结为四个核心优势：

分级日志系统：支持DEBUG/INFO/WARNING/ERROR/CRITICAL五个级别，可在生产环境中精准控制日志粒度。例如在开发时输出详细DEBUG信息，线上仅记录WARNING及以上级别。

多目标输出：可同时将日志写入控制台、文件、网络服务等多种目标。典型场景是本地开发时输出到控制台，生产环境同时写入文件和日志聚合服务。

结构化日志：支持JSON格式输出，便于日志分析工具（如ELK Stack）解析。相比无结构的文本日志，结构化日志可实现复杂的查询和统计分析。

线程安全设计：在多线程环境下无需额外同步措施，而print语句可能导致日志错乱。这对高并发服务至关重要。

二、基础组件与工作流程

logging模块采用模块化设计，主要包含四个核心组件：

  • Logger（日志器） ：应用程序直接交互的接口，通过logging.getLogger(name)获取。推荐使用模块名作为logger名称（__name__），便于追踪日志来源。

  • Handler（处理器） ：控制日志输出目标，如StreamHandler（控制台）、FileHandler（文件）、SMTPHandler（邮件）等。一个logger可添加多个handler实现多目标输出。

  • Formatter（格式化器）：定义日志格式，支持包含时间戳、日志级别、模块名、行号等元数据。

  • Filter（过滤器）：提供更细粒度的日志过滤，可基于日志级别、模块名、自定义条件等过滤日志。

工作流程示例：

python 复制代码 
import logging


# 获取logger实例
logger = logging.getLogger(__name__)
logger.setLevel(logging.DEBUG) # 设置logger级别


# 创建控制台handler
console_handler = logging.StreamHandler()
console_handler.setLevel(logging.INFO) # handler级别可高于logger


# 创建文件handler
file_handler = logging.FileHandler('app.log')
file_handler.setLevel(logging.DEBUG)


# 创建格式化器
formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
console_handler.setFormatter(formatter)
file_handler.setFormatter(formatter)


# 添加handler到logger
logger.addHandler(console_handler)
logger.addHandler(file_handler)


# 记录日志
logger.debug('调试信息，开发时使用') # 仅文件输出
logger.info('普通信息，确认程序正常运行') # 控制台和文件均输出

三、配置方法全解析

logging提供了三种主要配置方式，适用于不同场景：

1. 基础配置（basicConfig）

适合简单应用的快速配置，通过logging.basicConfig()函数设置：

python 复制代码 
import logging
from datetime import datetime


# 基础时间格式化示例
logging.basicConfig(
level=logging.INFO,
format='%(asctime)s [%(levelname)s] %(name)s:%(lineno)d - %(message)s',
datefmt='%Y-%m-%d %H:%M:%S',
handlers=[
logging.FileHandler(f'app_{datetime.now().strftime("%Y%m%d")}.log'),
logging.StreamHandler()
]
)


logger = logging.getLogger(__name__)
logger.info('应用启动')

关键参数：

  • level：设置根logger级别
  • format：日志格式字符串
  • datefmt：时间格式
  • handlers：指定处理器列表

2. 字典配置（dictConfig）

适合复杂配置和动态调整，支持JSON/YAML格式的配置文件：

python 复制代码 
import logging
from logging.config import dictConfig
import json


# 从JSON文件加载配置
with open('logging_config.json', 'r') as f:
config = json.load(f)


dictConfig(config)
logger = logging.getLogger('payment_service')
logger.info('支付处理开始')

典型的JSON配置文件：

bash 复制代码 
{
"version": 1,
"disable_existing_loggers": false,
"formatters": {
"detailed": {
"format": "%(asctime)s [%(process)d:%(thread)d] %(name)s:%(lineno)d - %(levelname)s - %(message)s"
},
"simple": {
"format": "%(levelname)s - %(message)s"
}
},
"handlers": {
"file": {
"class": "logging.handlers.RotatingFileHandler",
"formatter": "detailed",
"filename": "app.log",
"maxBytes": 10485760, # 10MB
"backupCount": 5,
"encoding": "utf-8"
},
"console": {
"class": "logging.StreamHandler",
"formatter": "simple",
"level": "INFO"
}
},
"loggers": {
"payment_service": {
"handlers": ["file", "console"],
"level": "DEBUG",
"propagate": false
}
},
"root": {
"handlers": ["console"],
"level": "WARNING"
}
}

3. 文件配置（fileConfig）

传统的INI格式配置，使用logging.config.fileConfig()加载：

python 复制代码 
[loggers]
keys=root,payment


[handlers]
keys=consoleHandler,fileHandler


[formatters]
keys=simpleFormatter,detailedFormatter


[logger_root]
level=WARNING
handlers=consoleHandler


[logger_payment]
level=DEBUG
handlers=consoleHandler,fileHandler
qualname=payment
propagate=0


[handler_consoleHandler]
class=StreamHandler
level=INFO
formatter=simpleFormatter
args=(sys.stdout,)


[handler_fileHandler]
class=handlers.RotatingFileHandler
level=DEBUG
formatter=detailedFormatter
args=('payment.log', 'a', 10485760, 5, 'utf-8')


[formatter_simpleFormatter]
format=%(levelname)s - %(message)s


[formatter_detailedFormatter]
format=%(asctime)s %(name)s:%(lineno)d - %(levelname)s - %(message)s
datefmt=%Y-%m-%d %H:%M:%S

四、高级应用场景

1. 日志轮转策略

当日志文件增长到一定大小或时间时自动切割，避免单个文件过大：

python 复制代码 
# 按大小轮转：每个文件10MB，最多保留5个备份
from logging.handlers import RotatingFileHandler
handler = RotatingFileHandler(
'app.log', 
maxBytes=10*1024*1024, # 10MB
backupCount=5,
encoding='utf-8'
)


# 按时间轮转：每天午夜创建新文件
from logging.handlers import TimedRotatingFileHandler
handler = TimedRotatingFileHandler(
'app.log',
when='midnight', # 可选值：S/秒, M/分, H/时, D/天, W0-W6/周, midnight/午夜
interval=1,
backupCount=30, # 保留30天日志
encoding='utf-8'
)

2. 异常日志记录

使用logger.exception()自动记录异常堆栈信息：

python 复制代码 
try:
result = 1 / 0
except ZeroDivisionError:
# 自动包含traceback信息
logger.error("除法运算失败", exc_info=True) # 显式指定exc_info
# 或更简洁的方式
logger.exception("除法运算失败") # 隐含exc_info=True

输出示例：

python 复制代码 
2023-11-15 14:30:00 mymodule:15 - ERROR - 除法运算失败
Traceback (most recent call last):
File "mymodule.py", line 13, in calculate
result = 1 / 0
ZeroDivisionError: division by zero

3. 结构化日志输出

使用python-json-logger库实现JSON格式日志：

python 复制代码 
pip install python-json-logger
python 复制代码 
from pythonjsonlogger import jsonlogger


logger = logging.getLogger(__name__)
handler = logging.StreamHandler()


formatter = jsonlogger.JsonFormatter(
'%(asctime)s %(name)s %(levelname)s %(message)s %(lineno)d',
rename_fields={"levelname": "level", "asctime": "timestamp"}
)
handler.setFormatter(formatter)
logger.addHandler(handler)


logger.info("用户登录", extra={"user_id": "12345", "ip": "192.168.1.1"})

输出JSON日志：

python 复制代码 
{
"timestamp": "2023-11-15 14:35:00",
"name": "__main__",
"level": "INFO",
"message": "用户登录",
"lineno": 15,
"user_id": "12345",
"ip": "192.168.1.1"
}

4. 分布式系统日志

在微服务架构中，可通过SocketHandler将日志发送到中央日志服务器：

python 复制代码 
# 客户端配置
import logging
from logging.handlers import SocketHandler


handler = SocketHandler('log-server.example.com', 9020)
logger = logging.getLogger('microservice')
logger.addHandler(handler)
logger.setLevel(logging.INFO)


logger.info("服务启动完成")

服务器端可使用logging.handlers.SocketServer接收并处理日志。

五、生产环境最佳实践

1. 日志级别使用规范

  • DEBUG：开发调试信息，包含变量值、函数调用参数等，生产环境默认关闭
  • INFO：关键业务流程节点，如"用户下单成功"、"数据同步完成"
  • WARNING：不影响主流程但需关注的异常情况，如"缓存命中率低于阈值"
  • ERROR：功能模块异常但不导致进程终止，如"第三方API调用失败"
  • CRITICAL：严重错误，可能导致系统崩溃，如"数据库连接池耗尽"

2. 性能优化建议

  • 避免日志风暴 ：高并发场景下控制DEBUG级别日志输出，可使用logger.isEnabledFor(logging.DEBUG)判断
  • 异步日志处理 ：使用concurrent-log-handler库实现异步文件写入
  • 批量日志处理：对高频日志（如每请求日志）进行采样或批量聚合
  • 合理设置缓冲区 ：FileHandler的delay=True参数延迟文件打开，buffering参数设置缓冲区大小

3. 安全注意事项

  • 敏感信息过滤：使用Filter移除日志中的密码、Token等敏感数据
  • 日志文件权限 ：确保日志文件权限设置为0o600，防止未授权访问
  • 防日志注入：对用户输入内容进行转义，特别是在构造日志消息时

敏感信息过滤示例：

python 复制代码 
class SensitiveDataFilter(logging.Filter):
def filter(self, record):
# 检查消息中是否包含敏感字段
sensitive_fields = ['password', 'token', 'credit_card']
msg = str(record.msg)
for field in sensitive_fields:
if field in msg.lower():
record.msg = "日志包含敏感信息，已过滤"
return True


logger.addFilter(SensitiveDataFilter())

4. 容器环境适配

在Docker/Kubernetes环境中，推荐配置：

  • 输出到标准输出（stdout/stderr），由容器引擎统一收集
  • 使用JSON格式便于日志聚合系统解析
  • 通过环境变量控制日志级别（如LOG_LEVEL=INFO）

Dockerfile示例：

python 复制代码 
ENV LOG_LEVEL=INFO
CMD ["python", "app.py"]

应用中读取环境变量：

python 复制代码 
import os
import logging


log_level = os.environ.get('LOG_LEVEL', 'INFO').upper()
logger.setLevel(log_level)

六、常见问题解决方案

问题1：日志不输出

排查步骤：

  1. 检查logger是否设置了正确级别（默认WARNING）
  2. 确认logger已添加处理器（未添加handler会导致日志丢失）
  3. 检查处理器级别是否高于日志级别（如handler级别INFO会过滤DEBUG日志）
  4. 验证propagate属性是否正确设置（默认True会向上传播）

问题2：重复日志输出

常见原因：

  • 同一logger添加了多个相同处理器
  • 子logger和根logger都配置了处理器（propagate=True导致重复）
  • 模块被多次导入导致logger重复配置

解决方案：

python 复制代码 
# 配置前先清空已有处理器
if logger.hasHandlers():
logger.handlers = []
# 添加新处理器
logger.addHandler(handler)
# 或设置propagate=False
logger.propagate = False

问题3：中文乱码

解决方案：

  • 在FileHandler中显式指定encoding='utf-8'
  • 确保格式化器处理中文正常
  • 避免在日志消息中混合不同编码的字符串
bash 复制代码 
handler = logging.FileHandler('app.log', encoding='utf-8')

七、扩展工具与生态

logging模块有丰富的第三方扩展库，可满足特定需求：

  • structlog：提供更优雅的结构化日志API，支持上下文绑定
  • loguru：简化日志配置，开箱即用的现代化日志库
  • Sentry：错误跟踪服务，可与logging无缝集成
  • ELK Stack：Elasticsearch+Logstash+Kibana实现日志集中管理
  • Promtail+Loki：轻量级日志聚合方案，特别适合Kubernetes环境

loguru使用示例：

python 复制代码 
from loguru import logger


# 一行配置完成所有设置
logger.add("file_{time}.log", rotation="10 MB", level="INFO", encoding="utf-8")


logger.debug("调试信息")
logger.info("用户{user}登录成功", user="张三") # 支持格式化参数
try:
1 / 0
except ZeroDivisionError:
logger.exception("发生错误") # 自动记录异常

结语

logging模块作为Python标准库的重要组成部分，提供了企业级的日志解决方案。通过合理配置和最佳实践，它能成为系统监控、问题排查和用户行为分析的强大工具。无论是小型脚本还是大型分布式系统，掌握logging模块都能显著提升应用的可维护性和可靠性。

建议所有Python开发者将日志系统设计纳入项目初期规划，而非后期补丁。一个精心设计的日志系统，往往是区分业余和专业项目的关键标志之一。

相关推荐
慢慢沉3 分钟前
Lua（数据库访问）
开发语言·数据库·lua
WJ.Polar5 分钟前
Python柱状图
python·信息可视化
GISer_Jing6 分钟前
50道JavaScript基础面试题：从基础到进阶
开发语言·javascript·ecmascript
Python涛哥7 分钟前
PHP框架之Laravel框架教程：1. laravel搭建
开发语言·php·laravel
一百天成为python专家1 小时前
数据可视化
开发语言·人工智能·python·机器学习·信息可视化·numpy
武子康4 小时前
Java-82 深入浅出 MySQL 内部架构：服务层、存储引擎与文件系统全覆盖
java·开发语言·数据库·学习·mysql·spring·微服务
倒悬于世4 小时前
开源的语音合成大模型-Cosyvoice使用介绍
人工智能·python·语音识别
惜.己5 小时前
pytest中使用skip跳过某个函数
开发语言·python·测试工具·pytest
姜暮儿5 小时前
C++ 性能优化
开发语言·c++
啊呦.超能力6 小时前
QT开发---多线程编程
开发语言·qt
热门推荐
01Qwen3-Coder 快速上手教程 | Qwen Code + Claude Code02全球最强模型Grok4，国内已可免费使用！（附教程）03vue数据变化但页面不变04KGG转MP3工具|非KGM文件|解密音频05【2025.7.18】更新vscode后所有.vue文件template标签后报红的临时解决办法，Vue - Official 插件3.0.2导致06干翻 Typora！MilkUp：完全免费的桌面端 Markdown 编辑器！07这次领先Cursor！体验了Trae 2.0 SOLO 模式，超酷！08ChatGPT Agent 完全使用指南：2025年7月最新功能详解09Cursor Claude 模型无法使用的解决方法10Claude Code用不了？来试下Qwen3-Coder加持的Qwen Code吧