一、Python logging 模块的层次结构

Python 的 logging 模块提供了一个灵活的日志系统，适用于各种规模的应用程序。其核心设计基于层次化的命名系统，使得日志记录可以按照组织结构进行管理和配置。

1. Logger（日志器）

• 定义：Logger 是日志记录的核心对象，用于生成日志消息。
• 命名：每个 Logger 都有一个名称，通常使用点（.）分隔的字符串来表示层次结构，例如 'app'、'app.module'、'app.module.submodule'。
• 层次结构：Logger 名称中的点表示层级关系。例如，'app.module' 是 'app' 的子 Logger，'app.module.submodule' 又是 'app.module' 的子 Logger。

2. Handler（处理器）

• 定义：Handler 负责将日志消息发送到特定的目的地，如控制台、文件、网络等。
• 类型：常用的 Handler 包括 StreamHandler（输出到控制台）、FileHandler（输出到文件）、SMTPHandler（发送邮件）等。
• 配置：每个 Handler 可以独立配置其日志级别、格式化器等属性。

3. Filter（过滤器）

• 定义：Filter 提供了更细粒度的控制，用于决定哪些日志消息可以通过特定的 Handler 或 Logger。
• 用途：可以基于日志属性（如模块名、线程名等）过滤日志消息。

4. Root Logger（根日志器）

• 定义：Root Logger 是层次结构中的顶级 Logger，其名称为空字符串（''）。
• 作用：所有未显式设置父 Logger 的 Logger 都是根 Logger 的子 Logger。根 Logger 通常配置全局的 Handler 和 Formatter，以确保所有日志消息都有一个默认的处理方式。

5. Logger 的层次关系示意图

根 Logger ('')
├── app
│   ├── app.module
│   │   └── app.module.submodule
│   └── app.other_module
└── another_app└── another_app.module

在上述层次结构中：

• 'app.module.submodule' 是 'app.module' 的子 Logger。
• 'app.module' 是 'app' 的子 Logger。
• 'app' 和 'another_app' 都是根 Logger 的直接子 Logger。

6. 日志消息的传播

当一个 Logger 记录一条日志消息时，消息会首先被当前 Logger 关联的 Handler 处理，然后根据 propagate 属性决定是否将消息传递给父 Logger 进行进一步处理。这种传播机制允许日志消息在层次结构中逐级传递，直到根 Logger。

二、logger.propagate 属性的解释

logger.propagate 是 Python logging 模块中 Logger 对象的一个布尔属性，用于控制日志消息在 Logger 层次结构中的传播行为。理解和合理配置 propagate 对于避免重复日志输出和实现定制化日志处理至关重要。

1. logger.propagate 的基本概念

• 默认值：True
• 作用：
  • propagate=True：日志消息会在当前 Logger 的 Handler 处理完后，继续传递给父 Logger 的 Handler 进行处理。
  • propagate=False：日志消息只由当前 Logger 的 Handler 处理，不会传递给父 Logger。

2. 具体行为示例

假设有以下 Logger 层次结构：

根 Logger ('')
└── app└── app.module

配置：

• 根 Logger 配置了一个 StreamHandler，格式为 ROOT: %(levelname)s: %(message)s
• app Logger 配置了一个 StreamHandler，格式为 APP: %(levelname)s: %(message)s
• app.module Logger 配置了一个 StreamHandler，格式为 MODULE: %(levelname)s: %(message)s

示例代码：

import logging# 配置根 Logger
root_logger = logging.getLogger()
root_handler = logging.StreamHandler()
root_handler.setFormatter(logging.Formatter('ROOT: %(levelname)s: %(message)s'))
root_logger.addHandler(root_handler)
root_logger.setLevel(logging.DEBUG)# 配置 'app' Logger
app_logger = logging.getLogger('app')
app_handler = logging.StreamHandler()
app_handler.setFormatter(logging.Formatter('APP: %(levelname)s: %(message)s'))
app_logger.addHandler(app_handler)
app_logger.setLevel(logging.DEBUG)# 配置 'app.module' Logger
module_logger = logging.getLogger('app.module')
module_handler = logging.StreamHandler()
module_handler.setFormatter(logging.Formatter('MODULE: %(levelname)s: %(message)s'))
module_logger.addHandler(module_handler)
module_logger.setLevel(logging.DEBUG)print("=== propagate=True ===")
module_logger.propagate = True
module_logger.debug('This is a debug message with propagate=True.')print("\n=== propagate=False ===")
module_logger.propagate = False
module_logger.debug('This is a debug message with propagate=False.')

预期输出：

=== propagate=True ===
MODULE: DEBUG: This is a debug message with propagate=True.
APP: DEBUG: This is a debug message with propagate=True.
ROOT: DEBUG: This is a debug message with propagate=True.=== propagate=False ===
MODULE: DEBUG: This is a debug message with propagate=False.

解释：

1. propagate=True（默认）：

   • 日志消息首先由 app.module Logger 关联的 module_handler 处理，输出 "MODULE: DEBUG: This is a debug message with propagate=True."
   • 然后，消息传递给父 Logger app，由 app_handler 处理，输出 "APP: DEBUG: This is a debug message with propagate=True."
   • 最后，消息继续传递给根 Logger，由 root_handler 处理，输出 "ROOT: DEBUG: This is a debug message with propagate=True."

2. propagate=False：

   • 日志消息仅由 app.module Logger 关联的 module_handler 处理，输出 "MODULE: DEBUG: This is a debug message with propagate=False."
   • 消息不会传递给父 Logger app 或根 Logger。

3. 使用场景

• 避免重复日志输出：
  在多层次 Logger 配置中，如果不适当设置 propagate，可能导致同一条日志消息被多个 Handler 重复处理。例如，日志同时被子 Logger 和父 Logger 的 Handler 输出。通过将子 Logger 的 propagate 设置为 False，可以避免这种情况。

• 定制化日志处理：
  有时希望特定 Logger 的日志消息只由其自身的 Handler 处理，而不受父 Logger 的影响。此时，可以将该 Logger 的 propagate 设置为 False，实现独立的日志处理逻辑。

4. 综合示例：结合层次结构和 logger.propagate

假设有以下应用场景：

• 根 Logger：记录所有 WARNING 及以上级别的日志到文件 app.log
• app.module Logger：记录所有 DEBUG 及以上级别的日志到控制台，并且不希望这些日志再传递给根 Logger

配置代码：

import logging# 定义日志器
root_logger = logging.getLogger()
root_logger.setLevel(logging.WARNING)
file_handler = logging.FileHandler('app.log')
file_formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
file_handler.setFormatter(file_formatter)
root_logger.addHandler(file_handler)app_module_logger = logging.getLogger('app.module')
app_module_logger.setLevel(logging.DEBUG)
console_handler = logging.StreamHandler()
console_formatter = logging.Formatter('%(name)s - %(levelname)s - %(message)s')
console_handler.setFormatter(console_formatter)
app_module_logger.addHandler(console_handler)
app_module_logger.propagate = False  # 禁止传播到根 Logger# 日志记录
app_module_logger.debug('Debug message from app.module.')  # 仅输出到控制台
app_module_logger.warning('Warning message from app.module.')  # 输出到控制台和文件（由于 propagate=False，不会输出到文件）root_logger.warning('Warning message from root logger.')  # 仅输出到文件

预期行为：

• "Debug message from app.module." 仅显示在控制台，因为它的级别是 DEBUG，且 propagate=False，不会传递到根 Logger。
• "Warning message from app.module." 显示在控制台，并记录到 app.log 文件中，因为它的级别是 WARNING，app_module_logger 有独立的 Handler，并且 propagate=False 允许它独立记录。
• "Warning message from root logger." 仅记录到 app.log 文件中，由根 Logger 处理。

文件 app.log 内容（示例）：

2024-04-27 12:34:56,789 - root - WARNING - Warning message from root logger.

控制台输出：

app.module - DEBUG - Debug message from app.module.
app.module - WARNING - Warning message from app.module.

5. 注意事项

• 配置顺序：确保在配置 Logger、Handler 和 Formatter 时，按照正确的顺序进行，以避免配置错误或遗漏。
• 避免 Handler 重复：如果 Logger 的 propagate 为 True，并且父 Logger 也有相同的 Handler，可能导致日志消息被重复处理。使用 propagate=False 可有效避免此类问题。
• 性能考虑：虽然 propagate 对性能的影响较小，但在高频率的日志记录场景中，过多的传播可能会带来一定的开销。合理配置 propagate 有助于优化日志系统的性能。