python模块 — 日志记录模块logging_logging.formatter

logging是Python内置的日志记录模块，用于在程序中实现灵活的日志功能。使用logging模块可以记录错误、异常、警告和其他关键信息，以便于诊断和调试应用程序。

logging模块提供了以下主要组件：

1. Logger（日志器）：用于创建或获取一个用于发送日志记录消息的Logger对象。我们可以在不同的模块中定义和使用Logger对象来记录日志。

2. Handler（处理器）：用于指定将如何处理和输出日志消息。Handler可以将日志消息写入文件、控制台、网络等不同的目标。logging模块提供了多种常用的处理器，如StreamHandler（输出到控制台）、FileHandler（输出到文件）和SocketHandler（输出到网络套接字）。

3. Formatter（格式化器）：用于定义日志消息的显示格式。Formatter的默认格式包括时间戳、日志级别、日志名称和消息内容等信息。我们可以根据需求自定义格式。

4. Level（级别）：用于指定日志记录的级别，包括DEBUG、INFO、WARNING、ERROR和CRITICAL。我们可以根据需要设置不同级别的日志来控制日志的详细程度。

使用logging模块时，可以按照以下步骤编写日志记录代码：

1. 创建或获取一个Logger对象。
2. 设置Logger的日志级别。
3. 创建一个Handler（可以是StreamHandler、FileHandler等）。
4. 设置Handler的日志级别和格式化器。
5. 将Handler添加到Logger中。
6. 使用Logger对象记录日志消息。

下面是一个将日志写入文件的简单示例：

import logging
 
# 创建或获取一个 logger
logger = logging.getLogger('example_logger')
 
# 设置 logger 的日志级别为 DEBUG
logger.setLevel(logging.DEBUG)
 
# 创建一个输出到文件的处理器，并设置其日志级别为 DEBUG
file_handler = logging.FileHandler('log_file.log')
file_handler.setLevel(logging.DEBUG)
 
# 创建一个格式化器，并将其绑定到处理器
formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
file_handler.setFormatter(formatter)
 
# 将处理器添加到 logger
logger.addHandler(file_handler)
 
# 记录不同级别的日志消息
logger.debug('This is a DEBUG message')
logger.info('This is an INFO message')
logger.warning('This is a WARNING message')
logger.error('This is an ERROR message')
logger.critical('This is a CRITICAL message')

在这个示例中，我们创建了一个名为`example_logger`的日志对象，并设置其日志级别为DEBUG。然后，我们创建了一个输出到文件的处理器`file_handler`，并设置其日志级别为DEBUG。我们还创建了一个格式化器`formatter`，并将其绑定到处理器。接下来，我们将处理器添加到日志对象中，并指定日志将写入到名为`log_file.log`的文件中。最后，我们使用不同级别的日志消息记录了日志。

当我们运行这段代码时，日志消息将被写入到`log_file.log`文件中，每条消息都包括时间戳、日志对象名、日志级别和消息内容，并且消息的显示与日志级别设置的过滤关系相符。通过这个示例，我们展示了如何将日志消息写入到文件中，并记录不同级别的日志消息。

此外，logging模块还支持日志的过滤、添加额外的上下文信息、捕获和处理异常等高级功能。通过灵活的配置，我们可以根据需要在应用程序中实现强大的日志记录功能。

1、Logger（日志记录器）

日志记录器对象（Logger）是 Python 标准库中 logging 模块的主要组件之一，用于记录和处理应用程序中产生的日志信息。它允许开发人员在应用程序中指定不同级别的日志消息，如调试信息、错误信息或警告信息，并将这些消息输出到所需的位置，例如控制台、文件或其他目标。

创建一个日志记录器对象：

logger = logging.getLogger('my_logger')

日志记录器对象具有以下常用属性和方法：

属性：

• logger.name：返回记录器对象的名称。
• logger.level：返回记录器对象的日志级别。

方法：

• logger.setLevel(level)：设置记录器对象的日志级别。
• logger.addHandler(handler)：将处理器对象添加到记录器对象。
• logger.debug(msg, *args, **kwargs)：记录 DEBUG 级别的日志消息。
• logger.info(msg, *args, **kwargs)：记录 INFO 级别的日志消息。
• logger.warning(msg, *args, **kwargs)：记录 WARNING 级别的日志消息。
• logger.error(msg, *args, **kwargs)：记录 ERROR 级别的日志消息。
• logger.critical(msg, *args, **kwargs)：记录 CRITICAL 级别的日志消息。

需要注意的是，日志记录器对象可以通过多次设置处理器和格式化器，实现将日志消息输出到多个目标，并且每个目标可以有不同的格式和级别设置，以满足不同的需求。

注意 永远 不要直接实例化记录器，应当通过模块级别的函数。这是因为通过直接实例化记录器可能会导致不必要的重复记录器创建，从而影响日志记录的一致性和性能。正确的做法是使用 logging 模块提供的 logging.getLogger() 函数来获取记录器对象。这样可以确保我们始终获取到相同名称的记录器对象，避免重复创建，并保持一致的日志记录。

2、Handler（日志处理器）

Handler（处理器）是用来指定日志消息该如何处理的组件。它负责接收Logger对象传递过来的日志消息，并将其输出到特定的目标，例如文件、控制台、网络等。

Logger 对象可以通过addHandler()方法添加多个handler对象。举个例子，一个应用可以将所有的日志消息发送至日志文件，所有的错误级别（error）及以上的日志消息发送至标准输出，所有的严重级别（critical）日志消息发送至某个电子邮箱。在这个例子中需要三个独立的处理器，每一个负责将特定级别的消息发送至特定的位置。

以下是一些常见的Handler处理器：

• StreamHandler： 从 Handler 继承而来，将日志消息输出到流对象（例如控制台）。
• FileHandler：从 StreamHandler 继承而来，将日志消息写入到文件中。
• RotatingFileHandler： 从 FileHandler 继承而来，当日志文件达到一定大小后，会自动切割日志文件，生成新的日志文件。
• TimedRotatingFileHandler：从 FileHandler 继承而来，按照时间周期来切割日志文件，例如每天生成一个新的日志文件。
• SocketHandler：从 Handler 继承而来，通过网络将日志消息发送到远程服务器。
• SMTPHandler：从 Handler 继承而来，通过邮件将日志消息发送给指定的收件人。

创建一个FileHandler日志处理器对象：

handler = logging.FileHandler('app.log')

日志处理器对象具有以下常用属性和方法：

属性：

• baseFilename：获取或设置FileHandler处理器对象的基础文件名。
• mode：获取或设置FileHandler处理器对象的文件打开模式。
• encoding：获取或设置FileHandler处理器对象的文件编码方式。

方法：

• setFormatter(formatter)：将指定的格式化器对象设置给FileHandler处理器对象。
• setLevel(level)：将指定的日志级别设置给FileHandler处理器对象。
• flush()：刷新FileHandler处理器对象的文件缓冲区，将缓冲区中的内容写入到文件中。
• close()：关闭FileHandler处理器对象，释放资源并关闭文件。

3、Level（日志级别）

日志级别（Log Level）是一个表示日志消息严重程度的标识符，帮助我们对日志进行分类和过滤。Python的logging模块定义了多个日志级别，可以根据需要选择适当的级别来记录日志。

下面列出了logging模块中定义的日志级别（从最低到最高）：

1. DEBUG（调试级别）：详细的信息，主要用于调试和诊断。
2. INFO（信息级别）：确认程序按预期运行。
3. WARNING（警告级别）：表示可能发生的异常或错误。
4. ERROR（错误级别）：表明发生错误，但不影响程序的继续运行。
5. CRITICAL（严重级别）：表示严重错误，可能导致程序无法继续运行。

通常，可以根据应用程序的需求选择适当的日志级别。例如，在开发和调试阶段，可以使用DEBUG级别来记录详细的调试信息，而在生产环境中，可以使用WARNING级别或更高级别来记录重要的警告和错误信息。

设置logger的日志级别：

logger.setLevel(logging.INFO)

设置handler的日志级别：

handler.setLevel(logging.INFO)

4、Formatter（日志格式）

Formatter（日志格式）用于定义日志消息的输出格式。在Python的logging模块中，我们可以通过设置Formatter来自定义日志消息的格式，包括日期、时间、级别、消息内容等。

常用的日志格式字符串中的占位符有：

• %(asctime)s：日志的时间，以可读形式呈现。
• %(levelname)s：日志级别。
• %(message)s：日志消息内容。
• %(name)s：日志记录器的名称。

设置日志格式：

formatter = logging.Formatter('%(asctime)s - %(levelname)s - %(message)s')

将Formatter添加到处理器中：

handler.setFormatter(formatter)

5、logging.config（日志记录配置）

`logging.config`是Python中日志模块`logging`提供的一个用于配置日志系统的模块。可以使用配置文件或者字典的形式对日志系统的行为进行配置，包括日志级别、输出格式、输出目标等。这样可以灵活地管理和控制程序中的日志输出。

`logging.config`模块中包含了一些函数，最常用的是`dictConfig()`和`fileConfig()`。

（1）dictConfig(config)：

这个函数用于从一个字典配置中来配置日志系统。可以使用一个字典来配置日志系统的各个方面，包括handlers、formatters、loggers等。示例:

import logging
import logging.config
 
log_config = {
    'version': 1,
    'handlers': {
        'file_handler': {
            'class': 'logging.FileHandler',
            'filename': 'app.log',
            'formatter': 'my_formatter'
        },
    },
    'loggers': {
        'my_logger': {
            'handlers': ['file_handler'],
            'level': 'INFO'
        }
    },
    'formatters': {
        'my_formatter': {
            'format': '%(asctime)s - %(name)s - %(levelname)s - %(message)s'
        }
    }
}
 
logging.config.dictConfig(log_config)
 
logger = logging.getLogger('my_logger')
logger.info('This is a log message')

（2）fileConfig(fname, defaults=None, disable_existing_loggers=True)：

这个函数用于从一个配置文件中来配置日志系统。可以使用一个配置文件来配置日志系统的各个方面，常见的配置文件格式为INI格式。示例：

import logging
import logging.config
 
logging.config.fileConfig('logging.conf')
 
logger = logging.getLogger('my_logger')
logger.info('This is a log message')

总之，`logging.config`模块为Python的日志系统提供了配置的灵活性和可扩展性，可以根据需要使用不同的配置方式来管理程序的日志输出。

---

reference：

logging --- Python 的日志记录工具 — Python 3.8.18 文档