logging模块

本节内容

1. 日志相关概念
2. logging模块简介
3. 使用logging提供的模块级别的函数记录日志
4. logging模块日志流处理流程
5. 使用logging四大组件实例
6. 参考文档

一、日志相关概念

1.日志的作用

简单来讲就是，我们通过记录和分析日志可以了解一个系统或软件程序运行情况是否正常，也可以在应用程序出现故障时快速定位问题。比如，做运维的同学，在接收到报警或各种问题反馈后，进行问题排查时通常都会先去看各种日志，大部分问题都可以在日志中找到答案。再比如，做开发的同学，可以通过IDE控制台上输出的各种日志进行程序调试。对于运维老司机或者有经验的开发人员，可以快速的通过日志定位到问题的根源。可见，日志的重要性不可小觑。日志的作用可以简单总结为以下3点：

• 程序调试
• 了解软件程序运行情况，是否正常
• 软件程序运行故障分析与问题定位

如果应用的日志信息足够详细和丰富，还可以用来做用户行为分析，如：分析用户的操作行为、类型洗好、地域分布以及其它更多的信息，由此可以实现改进业务、提高商业利益。

2.日志的等级

不同的应用程序所定义的日志等级可能会有所差别，分的详细点的会包含以下几个等级：

• DEBUG
• INFO
• NOTICE
• WARNING
• ERROR
• CRITICAL
• ALERT
• EMERGENCY

3.日志字段信息与日志格式

本节开始问题提到过，一条日志信息对应的是一个事件的发生，而一个事件通常需要包括以下几个内容：

• 事件发生时间
• 事件发生位置
• 事件的严重程度--日志级别
• 事件内容

二、logging模块简介

logging模块定义的函数和类为应用程序和库的开发实现了一个灵活的事件日志系统。logging模块是Python的一个标准库模块，由标准库模块提供日志记录API的关键好处是所有Python模块都可以使用这个日志记录功能。所以，你的应用日志可以将你自己的日志信息与来自第三方模块的信息整合起来。

1. logging模块的日志级别

logging模块默认定义了以下几个日志等级，它允许开发人员自定义其他日志级别，但是这是不被推荐的，尤其是在开发供别人使用的库时，因为这会导致日志级别的混乱。

2. logging模块的使用方式介绍

logging模块提供了两种记录日志的方式：

• 第一种方式是使用logging提供的模块级别的函数
• 第二种方式是使用Logging日志系统的四大组件

其实，logging所提供的模块级别的日志记录函数也是对logging日志系统相关类的封装而已。

logging模块定义的模块级别的常用函数

其中logging.basicConfig(**kwargs)函数用于指定“要记录的日志级别”、“日志格式”、“日志输出位置”、“日志文件的打开模式”等信息，其他几个都是用于记录各个级别日志的函数。

logging模块的四大组件

三、使用logging提供的模块级别的函数记录日志

回顾下前面提到的几个重要信息：

• 可以通过logging模块定义的模块级别的方法去完成简单的日志记录
• 只有级别大于或等于日志记录器指定级别的日志记录才会被输出，小于该级别的日志记录将会被丢弃。

1.最简单的日志输出

先来试着分别输出一条不同日志级别的日志记录：

import logging

logging.debug("This is a debug log.")
logging.info("This is a info log.")
logging.warning("This is a warning log.")
logging.error("This is a error log.")
logging.critical("This is a critical log.")

也可以这样写：

logging.log(logging.DEBUG, "This is a debug log.")
logging.log(logging.INFO, "This is a info log.")
logging.log(logging.WARNING, "This is a warning log.")
logging.log(logging.ERROR, "This is a error log.")
logging.log(logging.CRITICAL, "This is a critical log.")

输出结果：

WARNING:root:This is a warning log.
ERROR:root:This is a error log.
CRITICAL:root:This is a critical log.

2. 那么问题来了

问题1：为什么前面两条日志没有被打印出来？

这是因为logging模块提供的日志记录函数所使用的日志器设置的日志级别是WARNING，因此只有WARNING级别的日志记录以及大于它的ERROR和CRITICAL级别的日志记录被输出了，而小于它的DEBUG和INFO级别的日志记录被丢弃了。

问题2：打印出来的日志信息中各字段表示什么意思？为什么会这样输出？

上面输出结果中每行日志记录的各个字段含义分别是：

日志级别:日志器名称:日志内容

之所以会这样输出，是因为logging模块提供的日志记录函数所使用的日志器设置的日志格式默认是BASIC_FORMAT，其值为：

"%(levelname)s:%(name)s:%(message)s"

问题3：如果将日志记录输出到文件中，而不是打印到控制台？

因为在logging模块提供的日志记录函数所使用的日志器设置的处理器所指定的日志输出位置默认为:
sys.stderr。

问题4：我是怎么知道这些的？

查看这些日志记录函数的实现代码，可以发现：当我们没有提供任何配置信息的时候，这些函数都会去调用logging.basicConfig(**kwargs)方法，且不会向该方法传递任何参数。继续查看basicConfig()方法的代码就可以找到上面这些问题的答案了。

问题5：怎么修改这些默认设置呢？

其实很简单，在我们调用上面这些日志记录函数之前，手动调用一下basicConfig()方法，把我们想设置的内容以参数的形式传递进去就可以了。

3. logging.basicConfig()函数说明

该方法用于为logging日志系统做一些基本配置，方法定义如下：

logging.basicConfig(**kwargs)

该函数可接收的关键字参数如下：

4. logging模块定义的格式字符串字段

我们来列举一下logging模块中定义好的可以用于format格式字符串中字段有哪些：

5.经过配置的日志输出

先简单配置下日志器的日志级别

logging.basicConfig(level=logging.DEBUG)

logging.debug("This is a debug log.")
logging.info("This is a info log.")
logging.warning("This is a warning log.")
logging.error("This is a error log.")
logging.critical("This is a critical log.")

输出结果：

DEBUG:root:This is a debug log.
INFO:root:This is a info log.
WARNING:root:This is a warning log.
ERROR:root:This is a error log.
CRITICAL:root:This is a critical log.

所有等级的日志信息都被输出了，说明配置生效了。

在配置日志器日志级别的基础上，在配置下日志输出目标文件和日志格式

LOG_FORMAT = "%(asctime)s - %(levelname)s - %(message)s"
logging.basicConfig(filename='my.log', level=logging.DEBUG, format=LOG_FORMAT)

logging.debug("This is a debug log.")
logging.info("This is a info log.")
logging.warning("This is a warning log.")
logging.error("This is a error log.")
logging.critical("This is a critical log.")

此时会发现控制台中已经没有输出日志内容了，但是在python代码文件的相同目录下会生成一个名为'my.log'的日志文件，该文件中的内容为：

2017-05-08 14:29:53,783 - DEBUG - This is a debug log.
2017-05-08 14:29:53,784 - INFO - This is a info log.
2017-05-08 14:29:53,784 - WARNING - This is a warning log.
2017-05-08 14:29:53,784 - ERROR - This is a error log.
2017-05-08 14:29:53,784 - CRITICAL - This is a critical log.

在上面的基础上，我们再来设置下日期/时间格式

LOG_FORMAT = "%(asctime)s - %(levelname)s - %(message)s"
DATE_FORMAT = "%m/%d/%Y %H:%M:%S %p"

logging.basicConfig(filename='my.log', level=logging.DEBUG, format=LOG_FORMAT, datefmt=DATE_FORMAT)

logging.debug("This is a debug log.")
logging.info("This is a info log.")
logging.warning("This is a warning log.")
logging.error("This is a error log.")
logging.critical("This is a critical log.")

此时会在my.log日志文件中看到如下输出内容：

05/08/2017 14:29:04 PM - DEBUG - This is a debug log.
05/08/2017 14:29:04 PM - INFO - This is a info log.
05/08/2017 14:29:04 PM - WARNING - This is a warning log.
05/08/2017 14:29:04 PM - ERROR - This is a error log.
05/08/2017 14:29:04 PM - CRITICAL - This is a critical log.

掌握了上面的内容之后，已经能够满足我们平时开发中需要的日志记录功能。

四、logging模块日志流处理流程

在介绍logging模块的高级用法之前，很有必要对logging模块所包含的重要组件以及其工作流程做个全面、简要的介绍，这有助于我们更好的理解我们所写的代码（将会触发什么样的操作）。

1. logging日志模块四大组件

在介绍logging模块的日志流处理流程之前，我们先来介绍下logging模块的四大组件：

logging模块就是通过这些组件来完成日志处理的，上面所使用的logging模块级别的函数也是通过这些组件对应的类来实现的。

这些组件之间的关系描述：

• 日志器（logger）需要通过处理器（handler）将日志信息输出到目标位置，如：文件、sys.stdout、网络等；
• 不同的处理器（handler）可以将日志输出到不同的位置；
• 日志器（logger）可以设置多个处理器（handler）将同一条日志记录输出到不同的位置；
• 每个处理器（handler）都可以设置自己的过滤器（filter）实现日志过滤，从而只保留感兴趣的日志；
• 每个处理器（handler）都可以设置自己的格式器（formatter）实现同一条日志以不同的格式输出到不同的地方。

简单点说就是：日志器（logger）是入口，真正干活儿的是处理器（handler），处理器（handler）还可以通过过滤器（filter）和格式器（formatter）对要输出的日志内容做过滤和格式化等处理操作。

2. logging日志模块相关类及其常用方法介绍

下面介绍下与logging四大组件相关的类：Logger, Handler, Filter, Formatter。

Logger类

Logger对象有3个任务要做：

• 1）向应用程序代码暴露几个方法，使应用程序可以在运行时记录日志消息；
• 2）基于日志严重等级（默认的过滤设施）或filter对象来决定要对哪些日志进行后续处理；
• 3）将日志消息传送给所有感兴趣的日志handlers。

Logger对象最常用的方法分为两类：配置方法 和 消息发送方法

最常用的配置方法如下：

logger对象配置完成后，可以使用下面的方法来创建日志记录：

那么，怎样得到一个Logger对象呢？一种方式是通过Logger类的实例化方法创建一个Logger类的实例，但是我们通常都是用第二种方式--logging.getLogger()方法。

logging.getLogger()方法有一个可选参数name，该参数表示将要返回的日志器的名称标识，如果不提供该参数，则其值为'root'。若以相同的name参数值多次调用getLogger()方法，将会返回指向同一个logger对象的引用。

Handler类

Handler对象的作用是（基于日志消息的level）将消息分发到handler指定的位置（文件、网络、邮件等）。Logger对象可以通过addHandler()方法为自己添加0个或者更多个handler对象。比如，一个应用程序可能想要实现以下几个日志需求：

• 1）把所有日志都发送到一个日志文件中；
• 2）把所有严重级别大于等于error的日志发送到stdout（标准输出）；
• 3）把所有严重级别为critical的日志发送到一个email邮件地址。
  这种场景就需要3个不同的handlers，每个handler复杂发送一个特定严重级别的日志到一个特定的位置。

一个handler中只有非常少数的方法是需要应用开发人员去关心的。对于使用内建handler对象的应用开发人员来说，似乎唯一相关的handler方法就是下面这几个配置方法：

Formater类

Formatter类的构造方法定义如下：

Formater对象用于配置日志信息的最终顺序、结构和内容。与logging.Handler基类不同的是，应用代码可以直接实例化Formatter类。另外，如果你的应用程序需要一些特殊的处理行为，也可以实现一个Formatter的子类来完成。

logging.Formatter.__init__(fmt=None, datefmt=None, hljs-string">'%')

可见，该构造方法接收3个可选参数：

• fmt：指定消息格式化字符串，如果不指定该参数则默认使用message的原始值
• datefmt：指定日期格式字符串，如果不指定该参数则默认使用"%Y-%m-%d %H:%M:%S"
• style：Python 3.2新增的参数，可取值为 '%', '{'和 '$'，如果不指定该参数则默认使用'%'

Filter类

Filter可以被Handler和Logger用来做比level更细粒度的、更复杂的过滤功能。Filter是一个过滤器基类，它只允许某个logger层级下的日志事件通过过滤。该类定义如下：

class logging.Filter(name='')
    filter(record)

比如，一个filter实例化时传递的name参数值为'A.B'，那么该filter实例将只允许名称为类似如下规则的loggers产生的日志记录通过过滤：'A.B'，'A.B,C'，'A.B.C.D'，'A.B.D'，而名称为'A.BB', 'B.A.B'的loggers产生的日志则会被过滤掉。如果name的值为空字符串，则允许所有的日志事件通过过滤。

filter方法用于具体控制传递的record记录是否能通过过滤，如果该方法返回值为0表示不能通过过滤，返回值为非0表示可以通过过滤。

3. logging日志流处理流程

下面这个图描述了日志流的处理流程：

我们来描述下上面这个图的日志流处理流程：

• 1）（在用户代码中进行）日志记录函数调用，如：logger.info(...)，logger.debug(...)等；
• 2）判断要记录的日志级别是否满足日志器设置的级别要求（要记录的日志级别要大于或等于日志器设置的级别才算满足要求），如果不满足则该日志记录会被丢弃并终止后续的操作，如果满足则继续下一步操作；
• 3）根据日志记录函数调用时掺入的参数，创建一个日志记录（LogRecord类）对象；
• 4）判断日志记录器上设置的过滤器是否拒绝这条日志记录，如果日志记录器上的某个过滤器拒绝，则该日志记录会被丢弃并终止后续的操作，如果日志记录器上设置的过滤器不拒绝这条日志记录或者日志记录器上没有设置过滤器则继续下一步操作--将日志记录分别交给该日志器上添加的各个处理器；
• 5）判断要记录的日志级别是否满足处理器设置的级别要求（要记录的日志级别要大于或等于该处理器设置的日志级别才算满足要求），如果不满足记录将会被该处理器丢弃并终止后续的操作，如果满足则继续下一步操作；
• 6）判断该处理器上设置的过滤器是否拒绝这条日志记录，如果该处理器上的某个过滤器拒绝，则该日志记录会被当前处理器丢弃并终止后续的操作，如果当前处理器上设置的过滤器不拒绝这条日志记录或当前处理器上没有设置过滤器测继续下一步操作；
• 7）如果能到这一步，说明这条日志记录经过了层层关卡允许被输出了，此时当前处理器会根据自身被设置的格式器（如果没有设置则使用默认格式）将这条日志记录进行格式化，最后将格式化后的结果输出到指定位置（文件、网络、类文件的Stream等）；
• 8）如果日志器被设置了多个处理器的话，上面的第5-8步会执行多次；
• 9）这里才是完整流程的最后一步：判断该日志器输出的日志消息是否需要传递给上一级logger（之前提到过，日志器是有层级关系的）的处理器，如果propagate属性值为1则表示日志消息将会被输出到处理器指定的位置，同时还会被传递给parent日志器的handlers进行处理直到当前日志器的propagate属性为0停止，如果propagate值为0则表示不向parent日志器的handlers传递该消息，到此结束。

可见，一条日志信息要想被最终输出需要依次经过以下几次过滤：

• 日志器等级过滤；
• 日志器的过滤器过滤；
• 日志器的处理器等级过滤；
• 日志器的处理器的过滤器过滤；

五、使用logging四大组件实例

现在，我们对logging模块的重要组件及整个日志流处理流程都应该有了一个比较全面的了解，下面我们来看一个例子。

__author__ = 'Administrator'
import logging

#如果没有指定输入日志收集器就用默认的：root logger，root logger只收集warning及warning级别以上的日志
#如果日志输出日志处理器没有设置的话默认只处理warning及warning级别以上的日志

#要我的日志我做做住怎么办？我想把什么级别输出就输出什么，想把他输出到哪就到哪
myLogger = logging.Logger("sunny_log") #新建自己的日志输入收集器logger
myLogger.setLevel("DEBUG")

#日志输出到控制台
sh = logging.StreamHandler() #指定日志输出处理器 输出到控制台
shFormatter = logging.Formatter("%(asctime)s-%(levelname)s-%(filename)s-%(name)s-日志信息：%(message)s")
sh.setFormatter(shFormatter)
sh.setLevel("DEBUG") #设置日志输出处理器的级别
myLogger.addHandler(sh)#输入与输出对接 输入与输出对接

#日志输出到文件

fh = logging.FileHandler("log2.txt","a","utf-8") #指定日志输出处理器 输出到文件
#定义自己想要的日志格式
fhFormatter = logging.Formatter("%(asctime)s-%(levelname)s-%(filename)s-%(name)s-%(lineno)d-日志信息：%(message)s")
fh.setFormatter(fhFormatter) #设置日志格式
fh.setLevel("DEBUG") #设置日志级别
myLogger.addHandler(fh) #搭配日志收集器 输入与输出对接

def div(a,b):
try:
myLogger.debug("第一个参数：%d"%a)
myLogger.info("第二个参数：%d"%b)
result = a/b
except Exception as e:
myLogger.error("错误哦%s"%e)
raise e

div(2,3)
div("aa",1)

#如果没有指定输入日志收集器就用默认的：root logger，root logger只收集warning及warning级别以上的日志
#如果日志输出日志处理器没有设置的话默认只处理warning及warning级别以上的日志

#要我的日志我做做住怎么办？我想把什么级别输出就输出什么，想把他输出到哪就到哪
myLogger = logging.Logger("sunny_log") #新建自己的日志输入收集器logger
myLogger.setLevel("DEBUG")

#日志输出到控制台
sh = logging.StreamHandler() #指定日志输出处理器 输出到控制台
shFormatter = logging.Formatter("%(asctime)s-%(levelname)s-%(filename)s-%(name)s-日志信息：%(message)s")
sh.setFormatter(shFormatter)
sh.setLevel("DEBUG") #设置日志输出处理器的级别
myLogger.addHandler(sh)#输入与输出对接 输入与输出对接

#日志输出到文件

fh = logging.FileHandler("log2.txt","a","utf-8") #指定日志输出处理器 输出到文件
#定义自己想要的日志格式
fhFormatter = logging.Formatter("%(asctime)s-%(levelname)s-%(filename)s-%(name)s-%(lineno)d-日志信息：%(message)s")
fh.setFormatter(fhFormatter) #设置日志格式
fh.setLevel("DEBUG") #设置日志级别
myLogger.addHandler(fh) #搭配日志收集器 输入与输出对接

def div(a,b):
try:
myLogger.debug("第一个参数：%d"%a)
myLogger.info("第二个参数：%d"%b)
result = a/b
except Exception as e:
myLogger.error("错误哦%s"%e)
raise e

div(2,3)
div("aa",1)

参考文档

• https://docs.python.org/3.5/howto/logging.html
• https://docs.python.org/3.5/library/logging.config.html
• https://docs.python.org/3.5/howto/logging-cookbook.html