--- title: logging 日志记录工具 description: 全面介绍了Python标准库logging模块的用法,包括理论知识和代码示例 keywords: - Python - logging - 日志 tags: - Python/标准库 - 技术/程序语言 author: 7Wate date: 2023-10-20 --- ## 简介 **logging 模块是 Python 标准库里提供的日志功能组件,它是在开发过程中实现日志记录的推荐方式。**logging 模块主要包含四个组件:Logger、Handler、Filter 和 Formatter。通过它们的协作可以快速实现对日志的控制和处理。 ## 组件 ### Logger **Logger 是日志模块中最基本的组件,它负责生成和分类日志。**在应用代码中,我们可以通过 getLogger 方法获取 Logger 对象,主要有两种获取方式: ```python import logging # 1. 不指定 Logger 名称,返回 root Logger logger1 = logging.getLogger() # 2. 指定名称获取 Logger logger2 = logging.getLogger('test') ``` ### Handler **Handler 用于指定 Logger 生成的日志消息应发送到哪个目标输出**,常用的 Handler 有两种: - **StreamHandler**:输出到流,如 sys.stdout、sys.stderr - **FileHandler**:输出到文件 我们可以通过 Logger 对象的 addHandler 方法将 Handler 与 Logger 关联起来: ```python logger = logging.getLogger('test') # 创建一个 Handler,用于写入日志文件 fh = logging.FileHandler('test.log') # 给 logger 添加 Handler logger.addHandler(fh) ``` ### Filter **Filter 用于提供复杂的日志过滤功能,可以用来过滤 INFO、DEBUG 等不同级别的日志。**根据需求,我们可以通过 logger.addFilter 将过滤器加到 logger 或者 handler 里。 ```python # 只记录 ERROR 及以上级别的日志 class ErrorFilter(logging.Filter): def filter(self, record): return record.levelno >= logging.ERROR logger.addFilter(ErrorFilter()) ``` ### Formatter **Formatter 用于控制日志信息的最终输出格式。**我们可以指定日志不同部分的显示格式,如时间、代码位置、日志消息等。 ```python # 指定日志格式 formatter = logging.Formatter('[%(levelname)s] %(asctime)s - %(message)s') handler.setFormatter(formatter) ``` ## 基础配置 我们可以通过字典或文件的方式配置 logging 模块。 ### dictConfig 配置 ```python import logging.config config_dict = { 'version': 1, 'formatters': { 'simple': { 'format': '[%(levelname)s] %(asctime)s - %(message)s' } }, 'handlers': { 'console': { 'class': 'logging.StreamHandler', 'level': 'DEBUG', 'formatter': 'simple' }, 'file': { 'class': 'logging.FileHandler', 'filename': 'test.log', 'formatter': 'simple' } }, 'root': { 'level': 'DEBUG', 'handlers': ['console', 'file'] } } logging.config.dictConfig(config_dict) ``` ### fileConfig 配置 将配置字典写入 json 或 yaml 文件,通过 fileConfig 函数加载: ```python import logging.config logging.config.fileConfig('config.yaml') ``` ### 配置参数 logging 模块的配置参数较多,主要包括以下方面: | 参数 | 说明 | | :----------------------- | :--------------------------------------- | | version | 配置字典的版本,目前为 1 | | disable_existing_loggers | 是否禁用已存在的其他日志器,默认 False | | formatters | 定义日志信息的格式化样式 | | filters | 定义过滤日志信息的过滤器 | | handlers | 定义日志的处理方法以及目标位置 | | loggers | 定义具体的日志器并绑定处理器和过滤器 | | root | 根日志器配置,其配置会应用到所有日志器上 | loggers 配置参数: | 参数 | 说明 | | :-------- | :--------------------------- | | level | 日志器接收的日志级别 | | handlers | 绑定的日志处理器 | | filters | 绑定的日志过滤器 | | propagate | 是否传递给父日志器,默认 True | handlers 常用参数: | 参数 | 说明 | | :-------- | :------------------------------------------- | | class | 指定处理器类,如 FileHandler、StreamHandler 等 | | level | 处理器的日志级别 | | formatter | 用于格式化日志的 Formatter | | args | 处理器初始化参数,如文件名等 | formatters 参数: | 参数 | 说明 | | :------ | :--------------------- | | format | 指定日志输出格式的模板 | | datefmt | 格式化时间的格式字符串 | | style | 输出样式,如 '{' 和 '$' 等 | ## 模块用法 ```mermaid graph TB START(开始)-->Choose_Logger[选择Logger] Choose_Logger-->|内置Logger|Use_Builtin[使用Python内置Logger] Choose_Logger-->|自定义Logger|Define_Logger[定义自定义Logger] Define_Logger-->Set_Level[设置日志级别
如DEBUG,INFO等] Define_Logger-->Create_Handler[创建Handler
如FileHandler,
StreamHandler等] Set_Level-->Create_Handler Create_Handler-->Set_Format[设置日志格式] Set_Format-->Add_Handler[添加Handler到Logger] Use_Builtin-->Set_Level Use_Builtin-->Create_Handler Add_Handler--> USE[使用Logger记录日志] USE-->END(结束) ``` ### 日志级别 logging 模块总共定义了 6 个级别的日志,按照严重程度从低到高排列如下: | 级别 | 数值 | 说明 | | :------- | :--- | :------------------------------------------------- | | DEBUG | 10 | 最详细的调试信息 | | INFO | 20 | 确认一切运行正常 | | WARNING | 30 | 表示出现异常,但尚未影响程序运行 | | ERROR | 40 | 由于更严重的问题,程序的某些功能已经不能正常运行了 | | CRITICAL | 50 | 严重错误,程序可能无法继续运行 | 在代码中记录日志时,我们可以根据需要的日志级别选择合适的函数,比如: ```python import logging logging.debug('detailed debug info') logging.info('program running info') logging.warning('warning occurred') logging.error('error occurred') logging.critical('critical error') ``` 日志级别可用于控制日志的输出粒度,通过设置级别参数可以只输出大于或等于该级别的日志。 ### 日志输出 logging 模块支持通过多种 Handler 将日志输出到不同的位置,常见的有两种: #### 输出到控制台 ```python import logging # create logger logger = logging.getLogger('simple_example') logger.setLevel(logging.DEBUG) # create console handler and set level to debug ch = logging.StreamHandler() ch.setLevel(logging.DEBUG) # create formatter formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s') # add formatter to ch ch.setFormatter(formatter) # add ch to logger logger.addHandler(ch) # 'application' code logger.debug('debug message') logger.info('info message') logger.warning('warn message') logger.error('error message') logger.critical('critical message') ``` #### 输出到文件 ```python import logging # 创建 logger logger = logging.getLogger('simple_example') logger.setLevel(logging.DEBUG) # 创建一个向文件输出的 handler fh = logging.FileHandler('test.log') fh.setLevel(logging.DEBUG) # 创建 formatter formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s') # 添加 formatter 到 fh fh.setFormatter(formatter) # 添加 fh 到 logger logger.addHandler(fh) # 日志输出 logger.debug('debug message') logger.info('info message') logger.warning('warn message') logger.error('error message') logger.critical('critical message') ``` 此外,还可以通过 SocketHandler 进行网络日志,通过 MemoryHandler 将日志输出到内存等。 ### 日志格式化 logging 模块允许自定义日志的输出格式,方便阅读和分析。主要通过 Formatter 实现。 ```python # 自定义格式 # 2023-02-28 15:50:07,431 - myapp.utils - INFO - User signed in successfully [in /path/to/utils.py:456] formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s [in %(pathname)s:%(lineno)d]') handler.setFormatter(formatter) ``` Formatter 使用的格式字符串类似于 C 语言的 printf 格式,可以包含以下字段: | 字段 | 说明 | | :-------- | :---------------------------------------------- | | asctime | 日志事件发生时间,如 2023-02-28 15:49:23,895 | | levelname | 日志级别的文本表示,如 INFO、ERROR 等 | | levelno | 日志级别的数值,如 20、40 等 | | message | 日志消息文本 | | pathname | 调用日志输出函数的源代码文件路径 | | filename | pathname 的文件名部分 | | module | 文件名的模块名部分 | | funcName | 调用日志输出函数的函数名 | | lineno | 调用日志输出函数的源代码行号 | | thread | 线程 ID | | process | 进程 ID | ### 日志高级功能 #### 日志回滚 通过 RotatingFileHandler 可以实现日志文件回滚,即当日志文件达到一定大小时自动生成新文件。 ```python handler = RotatingFileHandler('test.log', maxBytes=1024, backupCount=5) ``` #### 日志分割 它可以设置最大字节数和备份文件的数量,超过这些限制之后就会生成新的日志文件。通过 TimedRotatingFileHandler 可以实现日志文件按时间分割。 ```python handler = TimedRotatingFileHandler('test.log', when='D', interval=1) ``` 通过 when 参数可以设置按日、周、月等时间间隔进行切割,interval 参数设置时间间隔大小。 ## 最佳实践 ### 根据应用场景配置 Logging 模块 不同的 Python 应用场景需要不同的日志方案: - 小型命令行程序:直接输出到 stdout - 大型项目:输出到日志文件,同时进行错误提醒、日志分割等 - 分布式系统:实现集中式日志,结合 ELK 等日志分析系统 选择合适的 logging 功能组合。 ### 与项目架构相结合 logging 模块要与项目的架构设计相结合,比如: - 对 Django 项目进行专门的 Logging 设置 - 对 Flask 项目使用 dictsConfig 进行配置 - 对于大型项目,创建一个 log.py 统一处理日志 ### 可选的日志收集工具 可以结合日志收集系统,实现可视化分析,如 ELK(ElasticSearch + Logstash + Kibana) 组合。 ### 日志的性能优化 - 通过配置只记录必要的日志级别,不记录无用日志 - 将调试日志单独记录到一个文件 - 避免频繁字符串拼接,使用参数化格式 - 控制日志文件大小和滚动频率 ## 实战练习 ### 标准日志模块的配置示范 ```python # log_config.py import logging import logging.config # 日志配置字典 config_dict = { # 版本配置 'version': 1, # 配置日志格式化器 'formatters': { # 简单日志格式 'simple': { 'format': '[%(asctime)s] [%(levelname)s] %(message)s' }, # 复杂日志格式 'complex': { 'format': '[%(asctime)s] [%(levelname)s] [%(name)s] [%(filename)s %(funcName)s %(lineno)d] %(message)s' } }, # 配置日志处理器 'handlers': { # 控制台日志 'console': { 'class': 'logging.StreamHandler', 'level': 'DEBUG', 'formatter': 'simple' }, # 文件日志 'file': { 'class': 'logging.FileHandler', 'filename': 'app.log', 'mode': 'a', 'formatter': 'complex' } }, # 配置日志器 'loggers': { # 应用日志器 'app': { 'handlers': ['console', 'file'], 'level': 'DEBUG', } } } if __name__ == '__main__': # 加载配置字典 logging.config.dictConfig(config_dict) # 获取日志器并输出日志 logger = logging.getLogger('app') logger.debug('This is a debug message') ``` 以上实现了一个标准的日志配置,输出到控制台和文件,并使用不同的格式器,包含日志实践中的常见操作。 ### 小型项目中添加日志 以一个小型的 Web 项目为例: ```python import logging # 创建日志器 logger = logging.getLogger('myweb') # 创建控制台处理器并设置级别 ch = logging.StreamHandler() ch.setLevel(logging.INFO) # 添加格式器 formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s') ch.setFormatter(formatter) # 将处理器添加到日志器 logger.addHandler(ch) # 记录一条日志 logger.info('Starting myweb server...') ``` 代码中创建日志器、添加处理器、设置格式后,就可以在项目代码任何地方使用 logger.info、logger.debug 等记录日志,从而方便地添加日志功能。 ### 尝试优化项目日志的性能 优化日志性能的常见做法: - 通过配置文件配置日志,不要在代码里反复配置 - 设置生产环境只记录必要的日志级别,如 WARNING 以上 - ERROR 日志单独记录到文件,便于定位问题 - DEBUG 日志可以使用内存 Handler,避免 IO 消耗 - 使用异步日志,避免影响程序性能 - 合理设置日志滚动策略,避免文件过大 ## 扩展学习 ### 其他日志框架的比较 (Loguru、log4j 等) logging 模块作为标准库,用法简单,但需要自行处理诸如异步、日志分割等额外功能。一些第三方日志库如 loguru、log4j 等提供了更多实用功能的封装,可以根据需求选择。 ### 分布式系统日志收集方案 在分布式系统中,可以通过将日志发送到消息队列如 Kafka,然后由 Logstash 收集存储到 ElasticSearch 中,最后结合 Kibana 进行日志分析和可视化。也可以直接使用 ELK 提供的 Filebeat 代替 Logstash 从日志文件中收集日志。