Python编程：标准库logging使用
一、 基础使用
1.1 logging使用场景
日志是什么？这个不用多解释。百分之九十的程序都需要提供日志功能。Python内置的logging模块，为我们提供了现成的高效好用的日志解决方案。但是，不是所有的场景都需要使用logging模块，下面是Python官方推荐的使用方法：
| 任务场景 | 最佳工具 |
|---|---|
| 普通情况下，在控制台显示输出 | print() |
| 报告正常程序操作过程中发生的事件 | logging.info()(或者更详细的logging.debug()) |
| 发出有关特定事件的警告 | warnings.warn()或者logging.warning() |
| 报告错误 | 弹出异常 |
| 在不引发异常的情况下报告错误 | logging.error(), logging.exception()或者logging.critical() |
logging模块定义了下表所示的日志级别，按事件严重程度由低到高排列（注意是全部大写！因为它们是常量。）：
| 级别 | 级别数值 | 使用时机 |
|---|---|---|
| DEBUG | 10 | 详细信息，常用于调试。 |
| INFO | 20 | 程序正常运行过程中产生的一些信息。 |
| WARNING | 30 | 警告用户，虽然程序还在正常工作，但有可能发生错误。 |
| ERROR | 40 | 由于更严重的问题，程序已不能执行一些功能了。 |
| CRITICAL | 50 | 严重错误，程序已不能继续运行。 |
默认级别是WARNING，表示只有WARING和比WARNING更严重的事件才会被记录到日志内，低级别的信息会被忽略。因此，默认情况下，DEBUG和INFO会被忽略，WARING、ERROR和CRITICAL会被记录。
有多种方法用来处理被跟踪的事件。最简单的方法就是把它们打印到终端控制台上。或者将它们写入一个磁盘文件内。
1.2 简单范例
在什么都不配置和设定的情况下，logging会简单地将日志打印在显示器上，如下例所示：
import logginglogging.warning('Watch out!') # 消息会被打印到控制台上
logging.info('I told you so') # 这行不会被打印，因为级别低于默认级别
如果，将上面的代码放在一个脚本里并运行，结果是：
WARNING:root:Watch out!
默认情况下，打印出来的内容包括日志级别、调用者和具体的日志信息。所有的这些内容都是可以自定义的，在后面我们会细说。
1.3 记录到文件内
要把日志输出到文件内，就不能使用上面的方法了，但是logging模块同样给我们提供了一个相对便捷的手段，那就是logging.basicConfig()方法。
重新进入解释器环境，执行下面的代码：
import logging
logging.basicConfig(filename='example.log',level=logging.DEBUG)
logging.debug('This message should go to the log file')
logging.info('So should this')
logging.warning('And this, too')
然后打开本地的example.log文件，可以看到下面的日志消息：
DEBUG:root:This message should go to the log fileINFO:root:So should thisWARNING:root:And this, too
我们通过level=logging.DEBUG参数，设定了日志记录的门槛。如果想在命令行调用时设置日志级别，可以使用下面的选项：
--log=INFO
可以通过下面的方法来获取用户输入的日志级别参数：
numeric_level = getattr(logging, loglevel.upper(), None)
if not isinstance(numeric_level, int):
raise ValueError('Invalid log level: %s' % loglevel)
logging.basicConfig(level=numeric_level, ...)
默认情况下，日志会不断的追加到文件的后面。如果你不想保存之前的日志，每次都清空文件，然后写入当前日志，则可以如下设置：
logging.basicConfig(filename='example.log', filemode='w', level=logging.DEBUG)
关键是将filemode设置为‘w’。
1.4 多模块中同时使用日志功能
如果你的程序包含多个文件（模块），下面是个如何在其中组织日志的例子
# myapp.py
import logging
import mylib
def main():
logging.basicConfig(filename='myapp.log', level=logging.INFO)
logging.info('Started')
mylib.do_something()
logging.info('Finished')
if __name__ == '__main__':
main()
# mylib.py
import logging
def do_something():
logging.info('Doing something')
运行myapp.py模块，你可以在myapp.log日志文件中看到下面的内容：
INFO:root:Started
INFO:root:Doing something
INFO:root:Finished
1.5 日志的变量数
在logging模块中通过百分符%方式的格式化控制，生成消息字符串，类同于字符串数据类型的格式化输出，但也有不同之处。
import logging
logging.warning('%s before you %s', 'Look', 'leap!')
结果：
WARNING:root:Look before you leap!
可以看到两个%s分别被‘Look’和‘leap！’替代了。
1.6 消息格式
要控制消息格式，获得更多的花样，可以提供format参数：
import logging
logging.basicConfig(format='%(levelname)s:%(message)s', level=logging.DEBUG)
logging.debug('This message should appear on the console')
logging.info('So should this')
logging.warning('And this, too')
输出结果：
DEBUG:This message should appear on the console
INFO:So should this
WARNING:And this, too
对于%(levelname)s这种东西，是logging模块内置的，可以被输出到日志中的对象，更多的内容在下面将会列举。
1.7 附加时间信息
要在日志内容中附加时间信息，可以在format字符串中添加%(asctime)s。
import logginglogging.basicConfig(format='%(asctime)s %(message)s')
logging.warning('is when this event was logged.')
输出结果：
2023-06-12 12:51:42,760 is when this event was logged.
默认情况下，时间的显示使用ISO8601格式。如果想做更深入的定制，可以提供datefmt参数，如下所示：
import logging
logging.basicConfig(format='%(asctime)s %(message)s', datefmt='%m/%d/%Y %I:%M:%S %p')
logging.warning('is when this event was logged.')
输出结果
062/12/2023 12:56:36 PM is when this event was logged.
datefmt参数的定制和time模块的time.strftime()一样！
二、 高级用法
如果只是简单地使用logging，那么使用上面介绍的方法就可以了，如果要深度定制logging，那么就需要对它有更深入的了解。下面的内容才是基本的logging模块的使用方法。
logging模块采用了模块化设计，主要包含四种组件：
Loggers：记录器，提供应用程序代码能直接使用的接口；
Handlers：处理器，将记录器产生的日志发送至目的地；
Filters：过滤器，提供更好的粒度控制，决定哪些日志会被输出；
Formatters：格式化器，设置日志内容的组成结构和消息字段。
2.1 日志流程图
日志事件信息在loggers和handlers中的逻辑流程如下图所示：
下面是同时向屏幕和文件进行日志输出的流程：
2.2 Loggers记录器
logging模块的日志功能是基于Logger类实现的。我们可以通过下面的方法获取一个Logger类的实例（建议以模块名命名logger实例）。
logger = logging.getLogger(__name__)
Logger是一个树形层级结构，在使用debug()，info()，warn()，error()，critical()等方法之前必须先创建一个Logger的实例，即创建一个记录器，如果没有显式的进行创建，则默认创建一个root logger，并应用默认的日志级别(WARN)，默认的处理器Handler(StreamHandler，即将日志信息打印在标准输出上)，和默认的格式化器Formatter，就像我们在前面举的那些例子一样。logger对象有三重功能。首先，提供应用程序调用的接口；其次，决定日志记录的级别；最后，将日志内容传递到相关联的handlers中。总结logger对象的用法，可以分成两类：配置和消息发送。
下面是最常用的配置方法：
Logger.setLevel()：设置日志记录级别
Logger.addHandler()和Logger.removeHandler()：为logger对象添加或删除handler处理器对象。
Logger.addFilter()和Logger.removeFilter()：为为logger对象添加或删除filter过滤器对象。
配置好logger对象后，就可以使用下面的方法创建日志消息了：
Logger.debug(), Logger.info(), Logger.warning(), Logger.error(), and Logger.critical()：创建对应级别的日志，但不一定会被记录。Logger.exception()：创建一个类似Logger.error()的日志消息。不同的是Logger.exception()保存有一个追踪栈。该方法只能在异常handler中调用。
Logger.log()：显式的创建一条日志，是前面几种方法的通用方法。
注意，getLogger()方法返回一个logger对象的引用，并以你提供的name参数命名，如果未提供名字，那么默认为‘root’。使用同样的name参数，多次调用getLogger()，将返回同样的logger对象。
2.3 Handlers处理器
Handlers对象是日志信息的处理器、分发器。它们将日志分发到不同的目的地。比如有时候我们希望将所有的日志都记录在本地文件内，将error及其以上级别的日志发送到标准输出stdout，将critical级别的日志以邮件的方法发送给管理员。这就需要同时有三个独立的handler，分别负责一个方向的日志处理。
logging模块使用较多的handlers有两个，StreamHandler和FileHandler。
StreamHandler
标准输出stdout（如显示器）分发器。
创建方法: sh = logging.StreamHandler(stream=None)
FileHandler
将日志保存到磁盘文件的处理器。
创建方法: fh = logging.FileHandler(filename, mode=‘a’, encoding=None, delay=False)
handlers对象有下面的方法：
setLevel()：和logger对象的一样，设置日志记录级别。那为什么要设置两层日志级别呢？logger对象的日志级别是全局性的，对所有handler都有效，相当于默认等级。而handlers的日志级别只对自己接收到的logger传来的日志有效，进行了更深一层的过滤。setFormatter()：设置当前handler对象使用的消息格式。
addFilter() 和 removeFilter()：配置或删除一个filter过滤对象
logging模块内置了下面的handler处理器，从字面上你就能看出它们的大概用途：
- StreamHandler
- FileHandler
- BaseRotatingHandler
- RotatingFileHandler
- TimedRotatingFileHandler
- SocketHandler
- DatagramHandler
- SMTPHandler
- SysLogHandler
- NTEventLogHandler
- HTTPHandler
- WatchedFileHandler
- QueueHandler
- NullHandler
2.4 Formatters
Formatter对象用来最终设置日志信息的顺序、结构和内容。其构造方法为：
ft = logging.Formatter.__init__(fmt=None, datefmt=None, style=’%’)
如果不指定datefmt，那么它默认是%Y-%m-%d %H:%M:%S样式的。
style参数默认为百分符%，这表示前面的fmt参数应该是一个%()s格式的字符串，而可以使用的logging内置的keys，如下表所示：
| 属性 | 格式 | 描述 |
|---|---|---|
| asctime | %(asctime)s | 日志产生的时间，默认格式为2003-07-08 16:49:45,896 |
| created | %(created)f | time.time()生成的日志创建时间戳 |
| filename | %(filename)s | 生成日志的程序名 |
| funcName | %(funcName)s | 调用日志的函数名 |
| levelname | %(levelname)s | 日志级别 (‘DEBUG’, ‘INFO’, ‘WARNING’, ‘ERROR’, ‘CRITICAL’) |
| levelno | %(levelno)s | 日志级别对应的数值 |
| lineno | %(lineno)d | 日志所针对的代码行号（如果可用的话） |
| module | %(module)s | 生成日志的模块名 |
| msecs | %(msecs)d | 日志生成时间的毫秒部分 |
| message | %(message)s | 具体的日志信息 |
| name | %(name)s | 日志调用者 |
| pathname | %(pathname)s | 生成日志的文件的完整路径 |
| process | %(process)d | 生成日志的进程ID（如果可用） |
| processName | %(processName)s | 进程名（如果可用） |
| thread | %(thread)d | 生成日志的线程ID（如果可用） |
| threadName | %(threadName)s | 线程名（如果可用） |
2.5 Filter过滤器
Handlers和Loggers可以使用Filters来完成比日志级别更复杂的过滤。比如我们定义了filter = logging.Filter(‘a.b.c’)，并将这个Filter添加到了一个Handler上，则使用该Handler的Logger中只有名字带a.b.c前缀的Logger才能输出其日志。
创建方法: filter = logging.Filter(name=‘’)
例如：
filter = logging.Filter('mylogger.child1.child2')
fh.addFilter(filter)
则只会输出下面格式的日志，注意其用户名：
2023-06-12 13:27:46,237 - mylogger.child1.child2 - DEBUG - logger1 debug message
2023-06-12 13:27:46,237 - mylogger.child1.child2 - DEBUG - logger1 debug message
2023-06-12 13:27:46,237 - mylogger.child1.child2 - DEBUG - logger1 debug message
2023-06-12 13:27:46,237 - mylogger.child1.child2 - DEBUG - logger1 debug message
2.6 配置日志模块
有三种配置logging的方法：
创建loggers、handlers和formatters，然后使用Python的代码调用上面介绍过的配置函数。
创建一个logging配置文件，然后使用fileConfig()方法读取它。
创建一个配置信息字典然后将它传递给dictConfig()方法。
下面的例子采用了第一种方法：
#simple_logging_module.py
import logging
# 创建logger记录器
logger = logging.getLogger('simple_example')
logger.setLevel(logging.DEBUG)
# 创建一个控制台处理器，并将日志级别设置为debug。
ch = logging.StreamHandler()
ch.setLevel(logging.DEBUG)
# 创建formatter格式化器
formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
# 将formatter添加到ch处理器
ch.setFormatter(formatter)
# 将ch添加到logger
logger.addHandler(ch)
# 然后就可以开始使用了！
logger.debug('debug message')
logger.info('info message')
logger.warn('warn message')
logger.error('error message')
logger.critical('critical message')
在命令行中运行上面的代码，输出结果如下：
$ python simple_logging_module.py
2023-06-13 13:20:26,967 - simple_example - DEBUG - debug message
2023-06-13 13:20:26,967 - simple_example - INFO - info message
2023-06-13 13:20:26,968 - simple_example - WARNING - warn message
2023-06-13 13:20:26,968 - simple_example - ERROR - error message
2023-06-13 13:20:26,968 - simple_example - CRITICAL - critical message
下面是使用第二种方法，logging配置文件的方式：
# simple_logging_config.py
import logging
import logging.config
logging.config.fileConfig('logging.conf') # 读取config文件
# 创建logger记录器
logger = logging.getLogger('simpleExample')
# 使用日志功能
logger.debug('debug message')
logger.info('info message')
ogger.warn('warn message')
logger.error('error message')
logger.critical('critical message')
其中的logging.conf配置文件内容如下：
[loggers]
keys=root,simpleExample
[handlers]
keys=consoleHandler
[formatters]
keys=simpleFormatter
[logger_root]
level=DEBUG
handlers=consoleHandler
[logger_simpleExample]
level=DEBUG
handlers=consoleHandler
qualname=simpleExample
propagate=0
[handler_consoleHandler]
class=StreamHandler
level=DEBUG
formatter=simpleFormatter
args=(sys.stdout,)
[formatter_simpleFormatter]
format=%(asctime)s - %(name)s - %(levelname)s - %(message)s
datefmt=
在命令行中执行代码，结果如下：
$ python simple_logging_config.py
2023-06-13 13:32:55,072 - simpleExample - DEBUG - debug message
2023-06-13 13:32:55,073 - simpleExample - INFO - info message
2023-06-13 13:32:55,073 - simpleExample - WARNING - warn message
2023-06-13 13:32:55,073 - simpleExample - ERROR - error message
2023-06-13 13:32:55,073 - simpleExample - CRITICAL - critical message
Python官方更推荐第三种新的配置方法，类字典形式的配置信息，因为Python的字典运用形式多样，操作灵活。比如，你可以通过JSON格式保存字典，或者YAML格式保存信息，然后读取成字典。当然，你也可以直接在Python代码里编写传统的带有配置信息的字典。一切都是基于键值对形式的就OK。
下面的例子就是基于YAML配置文件的日志。logging.conf.yaml配置文件内容如下：
version: 1
formatters:
simple:
format: '%(asctime)s - %(name)s - %(levelname)s - %(message)s'
handlers:
console:
class: logging.StreamHandler
level: DEBUG
formatter: simple
stream: ext://sys.stdout
loggers:
simpleExample:
level: DEBUG
handlers: [console]
propagate: no
root:
level: DEBUG
handlers: [console]
这里要先通过pip安装yaml模块：
pip install pyyaml
yaml模块的使用很简单，使用open()方法打开一个yaml文件对象，然后使用yaml的load()方法将文件内容读成一个Python的字典对象。最后我们根据这个字典对象，使用logging.conf的dictConfig()方法，获取配置信息。如下代码所示：
import logging
import logging.config
import yaml
# 通过yaml文件配置logging
f = open("logging.conf.yaml")
dic = yaml.load(f)
f.close()
logging.config.dictConfig(dic)
# 创建logger
logger = logging.getLogger('simpleExample')
# 输出日志
logger.debug('debug message')
logger.info('info message')
logger.warn('warn message')
logger.error('error message')
logger.critical('critical message')
输出结果：
2023-06-13 14:41:09,232 - simpleExample - DEBUG - debug message
2023-06-13 14:41:09,232 - simpleExample - INFO - info message
2023-06-13 14:41:09,232 - simpleExample - WARNING - warn message
2023-06-13 14:41:09,232 - simpleExample - ERROR - error message
2023-06-13 14:41:09,232 - simpleExample - CRITICAL - critical message
输出日志
logger.debug('debug message')
logger.info('info message')
logger.warn('warn message')
logger.error('error message')
logger.critical('critical message')
输出结果：
2023-06-13 14:41:09,232 - simpleExample - DEBUG - debug message
2023-06-13 14:41:09,232 - simpleExample - INFO - info message
2023-06-13 14:41:09,232 - simpleExample - WARNING - warn message
2023-06-13 14:41:09,232 - simpleExample - ERROR - error message
2023-06-13 14:41:09,232 - simpleExample - CRITICAL - critical message
