logging模块

顾名思义，logging模块是用来管理日志的。

logging模块包含四个部分：

• Loggers expose the interface that application code directly uses. 记录器，暴露应用程序代码能直接使用的接口。
• Handlers send the log records (created by loggers) to the appropriate destination. 处理器，将logger产生的日志记录发送到合适的地方。
• Filters provide a finer grained facility for determining which log records to output. 过滤器，提供更细粒度的日志过滤方式，可以决定输出哪些日志记录。
• Formatters specify the layout of log records in the final output. 格式化器，指定日志记录最终的输出布局。

>>> import logging
>>> dir(logging)
['BASIC_FORMAT', 'BufferingFormatter', 'CRITICAL', 'DEBUG', 'ERROR', 'FATAL', 'FileHandler', 'Filter', 'Filterer', 'Formatter', 'Handler', 'INFO', 'LogRecord', 'Logger', 'LoggerAdapter', 'Manager', 'NOTSET', 'NullHandler', 'PercentStyle', 'PlaceHolder', 'RootLogger', 'StrFormatStyle', 'StreamHandler', 'StringTemplateStyle', 'Template', 'WARN', 'WARNING', '_STYLES', '_StderrHandler', '__all__', '__author__', '__builtins__', '__cached__', '__date__', '__doc__', '__file__', '__loader__', '__name__', '__package__', '__path__', '__spec__', '__status__', '__version__', '_acquireLock', '_addHandlerRef', '_checkLevel', '_defaultFormatter', '_defaultLastResort', '_handlerList', '_handlers', '_levelToName', '_lock', '_logRecordFactory', '_loggerClass', '_nameToLevel', '_releaseLock', '_removeHandlerRef', '_showwarning', '_srcfile', '_startTime', '_warnings_showwarning', 'addLevelName', 'atexit', 'basicConfig', 'captureWarnings', 'collections', 'critical', 'currentframe', 'debug', 'disable', 'error', 'exception', 'fatal', 'getLevelName', 'getLogRecordFactory', 'getLogger', 'getLoggerClass', 'info', 'io', 'lastResort', 'log', 'logMultiprocessing', 'logProcesses', 'logThreads', 'makeLogRecord', 'os', 'raiseExceptions', 'root', 'setLogRecordFactory', 'setLoggerClass', 'shutdown', 'sys', 'threading', 'time', 'traceback', 'warn', 'warning', 'warnings', 'weakref']

默认的日志格式：

LOGLEVEL:LOGGERNAME:msg

>>> import logging

>>> logging.critical('this is critical msg')
CRITICAL:root:this is critical msg

>>> logging.error('this is error msg')
ERROR:root:this is error msg

>>> logging.warning('this is warning msg')
WARNING:root:this is warning msg

>>> logging.info('this is info msg')

>>> logging.debug('this is debug msg')

Logger Objects

Logger.setLevel(lvl)：设置日志级别。

Sets the threshold for this logger to lvl. Logging messages which are less severe than lvl will be ignored. When a logger is created, the level is set to NOTSET (which causes all messages to be processed when the logger is the root logger, or delegation to the parent when the logger is a non-root logger). Note that the root logger is created with level WARNING.

The term ‘delegation to the parent’ means that if a logger has a level of NOTSET, its chain of ancestor loggers is traversed until either an ancestor with a level other than NOTSET is found, or the root is reached.

If an ancestor is found with a level other than NOTSET, then that ancestor’s level is treated as the effective level of the logger where the ancestor search began, and is used to determine how a logging event is handled.

If the root is reached, and it has a level of NOTSET, then all messages will be processed. Otherwise, the root’s level will be used as the effective level.

Logger是一个树形层级结构，在使用接口debug，info，warn，error，critical之前必须创建Logger实例，即创建一个记录器。如果没有显式地进行创建，则默认创建一个root logger，root logger的默认级别为WARNING，默认的处理器为StreamHandler，以及使用默认的日志格式。

Logging Levels，日志级别：

Logger.addFilter(filt)：添加指定的Filter。

Adds the specified filter filt to this logger.

Logger.addHandler(hdlr)：添加指定的Handler。

Adds the specified handler hdlr to this logger.

Handler Objects

Handler.setLevel(lvl)：为handler设置日志级别。

Sets the threshold for this handler to lvl. Logging messages which are less severe than lvl will be ignored. When a handler is created, the level is set to NOTSET (which causes all messages to be processed).

Three of the handlers (StreamHandler, FileHandler and NullHandler) are actually defined in the logging module itself.

Handler.setFormatter(form)：为handler设置formatter。

Sets the Formatter for this handler to form.

Handler.addFilter(filt)：为handler添加指定的Filter。

Adds the specified filter filt to this handler.

Formatter Objects

They are responsible for converting a LogRecord to (usually) a string which can be interpreted by either a human or an external system.

The base Formatter allows a formatting string to be specified. If none is supplied, the default value of '%(message)s' is used, which just includes the message in the logging call.

logging.Formatter(fmt=None, datefmt=None, style='%')

Returns a new instance of the Formatter class. The instance is initialized with a format string for the message as a whole, as well as a format string for the date/time portion of a message. If no fmt is specified, '%(message)s' is used. If no datefmt is specified, the ISO8601 date format is used.

The style parameter can be one of ‘%’, ‘{‘ or ‘$’ and determines how the format string will be merged with its data: using one of %-formatting, str.format() or string.Template.

fmt：表示消息的格式化字符串，如果没有指定，默认使用 '%(message)s'。
datefmt：表示时间字符串，如果没有指定，默认使用 ISO8601。

Filter Objects

Filters can be used by Handlers and Loggers for more sophisticated filtering than is provided by levels. The base filter class only allows events which are below a certain point in the logger hierarchy.

For example, a filter initialized with ‘A.B’ will allow events logged by loggers ‘A.B’, ‘A.B.C’, ‘A.B.C.D’, ‘A.B.D’ etc. but not ‘A.BB’, ‘B.A.B’ etc. If initialized with the empty string, all events are passed.

Handlers和Loggers可以使用Filters来完成比日志级别更复杂的过滤。Filter基类只允许logger树中特定层次以下的事件。

logging.Filter(name='')：返回（创建）一个Filter类的实例，如果不指定名字，则允许所有event。

Returns an instance of the Filter class. If name is specified, it names a logger which, together with its children, will have its events allowed through the filter. If name is the empty string, allows every event.

Module-Level Functions

logging.getLogger(name=None)：返回（创建）一个指定的名字的logger。

Return a logger with the specified name or, if name is None, return a logger which is the root logger of the hierarchy. If specified, the name is typically a dot-separated hierarchical name like ‘a’, ‘a.b’ or ‘a.b.c.d’. Choice of these names is entirely up to the developer who is using logging.

All calls to this function with a given name return the same logger instance. This means that logger instances never need to be passed between different parts of an application.

默认的logger为root logger，logger为树形结构，下层可以继承上层的设置。

一个Logger实例可以新增多个Handler和Filter，一个Handler可以新增多个Fomatter或多个Filter，而且日志级别将会继承。

logging.basicConfig(**kwargs)：使用基本日志配置方式。

Does basic configuration for the logging system by creating a StreamHandler with a default Formatter and adding it to the root logger. The functions debug(), info(), warning(), error() and critical() will call basicConfig() automatically if no handlers are defined for the root logger.

This function does nothing if the root logger already has handlers configured for it.

Note：This function should be called from the main thread before other threads are started.

支持以下关键字参数：

filename：表示使用指定名称的FileHandler（指定日志文件的位置），而不是默认的StreamHandler。
filemode：指定打开日志文件的模式，默认为'a'。
format：指定日志格式。
datefmt：指定时间格式。
level：指定日志输出级别（root logger的日志级别）。
steam：使用指定的steam初始化StreamHandler。这个参数不能与filename参数同时存在，如果同时存在，会报ValueError异常。

logging.basicConfig(level=logging.DEBUG,
                    filename='',
                    filemode='',
                    format='',
                    datefmt=''
)

示例，这里没有使用basicConfig：

# vim logger.py
#encoding: utf-8

import logging

# create logger
logger_name = "example"
logger = logging.getLogger(logger_name)
logger.setLevel(logging.DEBUG)

# create file handler
log_path = "./log.log"
fh = logging.FileHandler(log_path)
fh.setLevel(logging.WARNING)

# create formatter
fmt = "%(asctime)-15s %(levelname)s %(filename)s %(lineno)d %(process)d %(message)s"
datefmt = "%a %d %b %Y %H:%M:%S"
formatter = logging.Formatter(fmt, datefmt)

# add formatter to handler and add handler to logger
fh.setFormatter(formatter)
logger.addHandler(fh)

# print log info
logger.debug('debug message')
logger.info('info message')
logger.warn('warn message')
logger.error('error message')
logger.critical('critical message')

# python3 logger.py | cat log.log
Sun 22 Oct 2017 20:54:49 WARNING logger.py 27 15980 warn message
Sun 22 Oct 2017 20:54:49 ERROR logger.py 28 15980 error message
Sun 22 Oct 2017 20:54:49 CRITICAL logger.py 29 15980 critical message

参考：
https://docs.python.org/3/library/logging.html
https://docs.python.org/3/library/logging.handlers.html
https://docs.python.org/3/library/logging.config.html