Python logging 模組功能強大、無第三方依賴、支援多目標輸出(文件、控制台、Syslog、HTTP、Email、Socket)、層級過濾、格式化、多進程安全、字典配置(dictConfig)、結構化日誌(JSON)等企業級特性。本文從零構建完整認知體系。
logger = logging.getLogger(name)。FileHandler, StreamHandler, RotatingFileHandler, SMTPHandler, HTTPHandler 等)。%-style、{}-style、$-style。流程:Logger → (級別過濾) → Filter → Handler → (級別過濾) → Formatter → 輸出目標。
| 級別 | 數值 | 使用場景 |
|---|---|---|
NOTSET | 0 | 繼承父 Logger 級別 |
DEBUG | 10 | 診斷細節,開發調試 |
INFO | 20 | 關鍵業務節點,審計追蹤 |
WARNING | 30 | 潛在問題,如配置缺失、重試 |
ERROR | 40 | 功能失效,需人工介入 |
CRITICAL | 50 | 系統崩潰、數據損失 |
設置 logger.setLevel(INFO) 則 DEBUG 被忽略;handler.setLevel(WARNING) 則該 Handler 僅處理 ≥ WARNING。
basicConfig 一鍵配置
import logging, os
logging.basicConfig(
filename=os.path.join(os.getcwd(), "app.log"),
level=logging.DEBUG,
format="%(asctime)s | %(levelname)-8s | %(name)s | %(message)s",
datefmt="%Y-%m-%d %H:%M:%S",
filemode="a" # 'w' 覆蓋
)
logging.debug("調試信息")
logging.info("服務啟動")
logging.warning("配置項缺失,使用默認值")
輸出:
2024-05-20 10:30:15 | DEBUG | root | 調試信息
2024-05-20 10:30:15 | INFO | root | 服務啟動
2024-05-20 10:30:15 | WARNING | root | 配置項缺失,使用默認值
root = logging.getLogger() # 根 logger
app = logging.getLogger("myapp") # 子 logger
db = logging.getLogger("myapp.db") # 孫 logger
myapp.db 繼承 myapp 設置。propagate=True(預設)向上傳遞至父 Handler;設 False 斷開。getLogger 返回同一實例(單例模式)。dictConfig / YAML / fileConfig
import logging.config
import yaml
with open("logging.yaml") as f:
config = yaml.safe_load(f)
logging.config.dictConfig(config)
logging.yaml 範例:
version: 1
disable_existing_loggers: false
formatters:
standard:
format: "%(asctime)s | %(levelname)-8s | %(name)s | %(message)s"
datefmt: "%Y-%m-%d %H:%M:%S"
json:
class: pythonjsonlogger.jsonlogger.JsonFormatter
format: "%(asctime)s %(levelname)s %(name)s %(message)s"
handlers:
console:
class: logging.StreamHandler
level: INFO
formatter: standard
stream: ext://sys.stdout
file:
class: logging.handlers.RotatingFileHandler
level: DEBUG
formatter: json
filename: logs/app.json.log
maxBytes: 10485760
backupCount: 10
encoding: utf-8
error_file:
class: logging.handlers.RotatingFileHandler
level: ERROR
formatter: json
filename: logs/error.json.log
maxBytes: 10485760
backupCount: 30
loggers:
myapp:
level: DEBUG
handlers: [console, file, error_file]
propagate: false
root:
level: WARNING
handlers: [console]
優點:環境隔離、熱重載、結構化 JSON 便於 ELK/Splunk 接入。
| Handler | 用途 | 關鍵參數 |
|---|---|---|
RotatingFileHandler | 按大小滾動 | maxBytes, backupCount |
TimedRotatingFileHandler | 按時間滾動 | when=midnight, interval, backupCount |
SMTPHandler | 郵件告警 | mailhost, fromaddr, toaddrs, subject |
HTTPHandler | 推送到日誌平台 | host, url, method=POST |
SysLogHandler | 系統日誌 | address=/dev/log |
QueueHandler/QueueListener | 多進程安全非阻塞 | queue=multiprocessing.Queue() |
logger = logging.getLogger(__name__)
logger.debug("用戶 %s 登入", user_id) # 參數化延遲格式化
logger.info("訂單 %s 創建", order_id)
logger.warning("庫存不足: %s", sku)
logger.error("支付失敗", exc_info=True) # 自動附加堆疊跟蹤
logger.critical("數據庫連接池耗盡")
logger.log(logging.INFO, "自定義級別")
logger.exception("異常上下文") # 僅在 except 塊中使用,等同 error+exc_info
LoggerAdapter / Filter
class ContextFilter(logging.Filter):
def filter(self, record):
record.request_id = getattr(request_context, "request_id", "N/A")
record.user_id = getattr(user_context, "user_id", "anonymous")
return True
logger.addFilter(ContextFilter())
# 格式化串可用 %(request_id)s %(user_id)s
try:
risky_operation()
except Exception:
logger.exception("Operation failed") # 自動記錄 traceback
# 或
logger.error("Operation failed", exc_info=True)
import atexit
logging.shutdown() # 刷新所有 handler,關閉文件
atexit.register(logging.shutdown)
dictConfig + YAML 管理配置,環境變數覆蓋敏感信息。timestamp, level, logger, message, trace_id, span_id。all.log (DEBUG+), error.log (ERROR+)。QueueHandler + 單獨 Listener 進程寫入。trace_id,實現分佈式追蹤。