Python 日志记录最佳实践与高级配置指南

配置文件管理

使用配置文件管理日志记录器配置是一种更为清晰和易于维护的方式。虽然可以使用 fileConfig，但在现代 Python 开发中，推荐使用 dictConfig 进行编程式配置，因为它更加灵活且无需依赖外部 .conf 文件。

import logging.config

LOGGING_CONFIG = {
    'version': 1,
    'disable_existing_loggers': False,
    'formatters': {
        'default': {
            'format': '%(asctime)s - %(name)s - %(levelname)s - %(message)s'
        },
        'json': {
            '()': 'pythonjsonlogger.jsonlogger.JsonFormatter',
            'fmt': '%(asctime)s %(name)s %(levelname)s %(message)s'
        }
    },
    'handlers': {
        'console': {
            'class': 'logging.StreamHandler',
            'level': 'INFO',
            'formatter': 'default',
            'stream': 'ext://sys.stdout'
        },
        'file': {
            'class': 'logging.handlers.RotatingFileHandler',
            'level': 'DEBUG',
            'formatter': 'default',
            'filename': 'app.log',
            'maxBytes': 10485760,  # 10MB
            'backupCount': 5
        }
    },
    'root': {
        'level': 'DEBUG',
        'handlers': ['console', 'file']
    }
}

logging.config.dictConfig(LOGGING_CONFIG)
logger = logging.getLogger(__name__)

日志过滤器

日志过滤器可以根据特定的条件来过滤和记录日志信息。以下是一个过滤器的简单示例，仅允许特定类型的消息通过：

class InfoFilter(logging.Filter):
    def filter(self, record):
        return record.levelno == logging.INFO

logger = logging.getLogger('filtered_app')
handler = logging.StreamHandler()
handler.addFilter(InfoFilter())
handler.setFormatter(logging.Formatter('%(message)s'))
logger.addHandler(handler)
logger.setLevel(logging.DEBUG)

logger.debug('This will be filtered out')
logger.info('This will appear in output')
logger.warning('This will be filtered out')

日志旋转

日志旋转是管理日志文件大小和数量的重要工具，防止日志文件无限增长占用磁盘空间。

from logging.handlers import RotatingFileHandler, TimedRotatingFileHandler

# 基于大小的旋转
size_handler = RotatingFileHandler('app.log', maxBytes=10000, backupCount=5)

# 基于时间的旋转 (每天凌晨 0 点切割)
time_handler = TimedRotatingFileHandler('app.log', when='midnight', interval=1, backupCount=7)

5. 结构化日志与上下文信息

在现代微服务架构中，结构化日志（如 JSON 格式）比纯文本更易被日志聚合系统（如 ELK Stack）解析。此外，在 Web 应用中，将请求 ID 注入日志上下文有助于追踪整个请求链路。

结构化日志示例

import json
import logging

class JsonFormatter(logging.Formatter):
    def format(self, record):
        log_record = {
            'timestamp': self.formatTime(record),
            'level': record.levelname,
            'logger': record.name,
            'message': record.getMessage(),
            'extra': getattr(record, 'extra_data', {})
        }
        return json.dumps(log_record, ensure_ascii=False)

logger = logging.getLogger('structured')
handler = logging.StreamHandler()
handler.setFormatter(JsonFormatter())
logger.addHandler(handler)
logger.setLevel(logging.INFO)

record = logger.makeRecord(logger.name, logging.INFO, '', 0, 'User login', (), None)
record.extra_data = {'user_id': 12345, 'ip': '192.168.1.1'}
logger.handle(record)

线程安全与性能

日志操作本身是线程安全的，但在高并发场景下，频繁的 I/O 操作可能成为瓶颈。建议在生产环境中使用异步日志处理（如 QueueHandler 和 QueueListener），将日志写入任务放入队列，由后台线程异步处理，从而减少主线程阻塞。

6. 最佳实践总结

1. 避免敏感信息：切勿在日志中记录密码、Token 或用户隐私数据。
2. 选择合适的级别：不要滥用 DEBUG 级别，生产环境通常设置为 INFO 或 WARNING。
3. 控制日志量：使用日志旋转限制文件大小，定期清理旧日志。
4. 统一格式：团队内部应约定统一的日志格式规范，便于自动化解析。
5. 关注性能：避免在循环中进行复杂的字符串拼接操作，可使用占位符 %s 延迟计算。

优雅地处理日志对于应用程序的健康运行至关重要。logging 模块为开发者提供了多种方法来记录和管理日志信息。从基础的配置到高级的处理器、过滤器以及结构化日志，全面掌握这些技巧将显著提升系统的可维护性和可观测性。