一、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 有助于優化日志系統的性能。