Python日志记录：从基础到生产环境实践

1. 为什么Python日志记录如此重要？

在Python开发中，日志记录(Logging)经常被新手开发者低估其重要性。我见过太多项目在初期快速开发阶段直接使用print()语句输出调试信息，等到项目进入生产环境后才发现无法有效追踪问题。一个典型的反模式是：当系统出现异常时，开发团队不得不临时添加大量print语句，然后重新部署——这种事后补救的方式既低效又危险。

日志系统与print语句的本质区别在于：

• 日志具有分级能力（DEBUG/INFO/WARNING/ERROR/CRITICAL）
• 可以同时输出到多个目的地（控制台/文件/网络等）
• 支持灵活的格式化和过滤
• 能够记录发生时间、模块名、线程等上下文信息

以电商系统为例，当用户支付失败时：

python复制# 反例 - 使用print
print("支付失败！订单ID:12345") 

# 正例 - 使用logging
logger.error("支付失败！订单ID:%s 错误码:%s", order_id, error_code,
            extra={'user': current_user, 'payment_gateway': 'alipay'})

后者不仅能记录更多上下文信息，还能通过日志级别控制是否输出，甚至可以通过日志分析系统自动触发告警。

2. Python logging模块的核心架构

Python的logging模块采用了经典的"记录器(Logger)-处理器(Handler)-过滤器(Filter)-格式化器(Formatter)"架构。理解这个架构是掌握高级日志配置的关键。

2.1 组件关系图解

code复制[Logger] -> [Filter] -> [Handler] -> [Formatter] -> [输出目标]
   ↑
[LogRecord]

2.2 各组件职责详解

记录器(Logger)：

• 应用程序的直接接口
• 具有层级结构（如"a.b"是"a"的子记录器）
• 实现日志级别过滤（低于设置级别的消息会被忽略）

处理器(Handler)：

• 决定日志的去向（文件/邮件/HTTP等）
• 可以单独设置级别和格式
• 常见的内置处理器：
  • StreamHandler：输出到流（默认stderr）
  • FileHandler：输出到文件
  • RotatingFileHandler：大小回滚文件
  • TimedRotatingFileHandler：时间回滚文件
  • SMTPHandler：发送邮件
  • SysLogHandler：发送到syslog

格式化器(Formatter)：

• 控制日志输出的最终格式
• 使用%(name)s等占位符：

  python复制formatter = logging.Formatter(
      '%(asctime)s - %(name)s - %(levelname)s - %(message)s')
  

过滤器(Filter)：

• 提供比日志级别更精细的控制
• 可以基于任何条件过滤日志
• 示例：只记录包含特定关键字的日志

3. 生产环境日志配置方案

3.1 基础配置模板

python复制import logging
import logging.config

LOGGING_CONFIG = {
    'version': 1,
    'disable_existing_loggers': False,
    'formatters': {
        'standard': {
            'format': '%(asctime)s [%(levelname)s] %(name)s: %(message)s',
            'datefmt': '%Y-%m-%d %H:%M:%S'
        },
    },
    'handlers': {
        'console': {
            'class': 'logging.StreamHandler',
            'formatter': 'standard',
            'level': 'INFO',
            'stream': 'ext://sys.stdout'
        },
        'error_file': {
            'class': 'logging.handlers.RotatingFileHandler',
            'formatter': 'standard',
            'filename': 'error.log',
            'maxBytes': 10485760,  # 10MB
            'backupCount': 5,
            'level': 'ERROR'
        },
        'debug_file': {
            'class': 'logging.handlers.TimedRotatingFileHandler',
            'formatter': 'standard',
            'filename': 'debug.log',
            'when': 'midnight',
            'backupCount': 7,
            'level': 'DEBUG'
        }
    },
    'loggers': {
        '': {  # root logger
            'handlers': ['console', 'error_file', 'debug_file'],
            'level': 'DEBUG',
        },
        'my_app': {
            'handlers': ['console'],
            'level': 'INFO',
            'propagate': False
        }
    }
}

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

3.2 多环境配置策略

开发环境：

• 控制台输出DEBUG级别
• 简单文件日志
• 彩色日志输出（使用colorlog库）

测试环境：

• 文件日志+控制台
• 增加请求ID等上下文
• 考虑使用JSON格式便于分析

生产环境：

• 禁止控制台输出DEBUG
• 结构化日志（JSON格式）
• 日志聚合系统（ELK/Splunk等）
• 敏感信息过滤

3.3 日志文件管理实践

1. 滚动策略选择：

   • 按大小滚动：适合高频率日志
   • 按时间滚动：适合需要按天分析的场景
   • 混合策略：同时限制单个文件大小和保留天数

2. 日志文件命名规范：

   code复制/var/log/myapp/
   ├── app.log       # 当前日志
   ├── app.log.1     # 第一次滚动
   ├── app.log.2.gz  # 压缩的旧日志
   └── archive/
       ├── app-2023-01-01.log.gz
       └── app-2023-01-02.log.gz
   

3. 日志清理策略：

   • 基于时间的保留（保留最近7天）
   • 基于空间的保留（不超过10GB）
   • 重要日志永久归档

4. 高级日志技巧与性能优化

4.1 上下文丰富化技巧

基础方法：

python复制logger.info("User %s purchased item %s", user_id, item_id)

使用extra参数：

python复制logger.info("Purchase completed", 
           extra={'user': user_id, 'item': item_id, 'price': amount})

过滤器添加上下文：

python复制class ContextFilter(logging.Filter):
    def filter(self, record):
        record.ip = get_current_ip()
        record.request_id = get_request_id()
        return True

logger.addFilter(ContextFilter())

结构化日志（JSON格式）：

python复制import json
from pythonjsonlogger import jsonlogger

formatter = jsonlogger.JsonFormatter(
    '%(asctime)s %(levelname)s %(name)s %(message)s %(ip)s %(request_id)s')

4.2 性能优化要点

1. 避免昂贵的字符串操作：

   python复制# 反例 - 无论是否记录都会执行字符串格式化
   logger.debug("Data: %s", expensive_serialization(data))
   
   # 正例 - 先检查级别
   if logger.isEnabledFor(logging.DEBUG):
       logger.debug("Data: %s", expensive_serialization(data))
   

2. 异步日志处理：

   python复制from concurrent.futures import ThreadPoolExecutor
   
   class AsyncLogHandler(logging.Handler):
       def __init__(self, handler):
           super().__init__()
           self._handler = handler
           self._executor = ThreadPoolExecutor(max_workers=1)
       
       def emit(self, record):
           self._executor.submit(self._handler.emit, record)
   
   file_handler = logging.FileHandler('app.log')
   async_handler = AsyncLogHandler(file_handler)
   logger.addHandler(async_handler)
   

3. 批量写入优化：

   python复制class BufferedHandler(logging.Handler):
       def __init__(self, capacity=1000):
           super().__init__()
           self.buffer = []
           self.capacity = capacity
       
       def emit(self, record):
           self.buffer.append(self.format(record))
           if len(self.buffer) >= self.capacity:
               self.flush()
       
       def flush(self):
           with open('app.log', 'a') as f:
               f.write('\n'.join(self.buffer))
           self.buffer = []
   

4.3 分布式系统日志追踪

在微服务架构中，一个请求可能经过多个服务，为保持日志的连贯性：

1. 传递请求ID：

   python复制# 使用中间件生成和传递请求ID
   class RequestIdMiddleware:
       def __init__(self, get_response):
           self.get_response = get_response
       
       def __call__(self, request):
           request_id = request.headers.get('X-Request-ID') or str(uuid.uuid4())
           logging_filter = RequestIdFilter(request_id)
           logger.addFilter(logging_filter)
           
           response = self.get_response(request)
           response['X-Request-ID'] = request_id
           return response
   

2. 统一日志格式：

   code复制2023-01-01 12:00:00 [INFO] serviceA: Start processing request_id=abc123
   2023-01-01 12:00:01 [INFO] serviceB: Received request request_id=abc123
   2023-01-01 12:00:02 [INFO] serviceA: Completed processing request_id=abc123
   

3. 使用OpenTelemetry等工具：

   python复制from opentelemetry import trace
   from opentelemetry.sdk.trace import TracerProvider
   
   trace.set_tracer_provider(TracerProvider())
   tracer = trace.get_tracer(__name__)
   
   with tracer.start_as_current_span("service-operation"):
       logger.info("Operation started")
       # 业务逻辑
       logger.info("Operation completed")
   

5. 常见问题与解决方案

5.1 日志不显示问题排查

1. 检查日志级别链：

   • 记录器本身的级别
   • 处理器的级别
   • 父记录器的级别

2. 检查propagate设置：

   python复制logger.propagate = False  # 会阻止向父记录器传递
   

3. 检查过滤器：

   python复制for handler in logger.handlers:
       for filter in handler.filters:
           print(filter)
   

5.2 日志文件权限问题

典型错误：

code复制PermissionError: [Errno 13] Permission denied: '/var/log/app.log'

解决方案：

1. 使用专用日志用户：

   bash复制sudo useradd -r -s /bin/false applogger
   sudo chown applogger /var/log/myapp/
   

2. 应用程序启动时切换用户：

   python复制import os, pwd
   
   def drop_privileges(username='applogger'):
       if os.getuid() != 0:  # 非root用户不需要处理
           return
       
       user_info = pwd.getpwnam(username)
       os.setgid(user_info.pw_gid)
       os.setuid(user_info.pw_uid)
       os.environ['HOME'] = user_info.pw_dir
   

5.3 日志格式混乱问题

现象：

• 多线程日志交错
• 多进程日志丢失

解决方案：

1. 多线程环境：

   python复制handler = logging.FileHandler('app.log')
   handler.setFormatter(formatter)
   handler.addFilter(threading_filter)
   logger.addHandler(handler)
   

2. 多进程环境：

   python复制from multiprocessing import Queue
   from logging.handlers import QueueHandler, QueueListener
   
   log_queue = Queue()
   queue_handler = QueueHandler(log_queue)
   logger.addHandler(queue_handler)
   
   file_handler = logging.FileHandler('app.log')
   listener = QueueListener(log_queue, file_handler)
   listener.start()
   

5.4 敏感信息过滤

实现方式：

python复制class SensitiveDataFilter(logging.Filter):
    patterns = {
        r'\b\d{4}[-\s]?\d{4}[-\s]?\d{4}[-\s]?\d{4}\b': '[CREDIT CARD]',
        r'\b\d{3}[-\s]?\d{2}[-\s]?\d{4}\b': '[SSN]'
    }
    
    def filter(self, record):
        msg = record.getMessage()
        for pattern, replacement in self.patterns.items():
            msg = re.sub(pattern, replacement, msg)
        record.msg = msg
        return True

logger.addFilter(SensitiveDataFilter())

6. 日志分析与监控实践

6.1 日志分析常用工具

1. 命令行工具：

   • grep/awk/sed：基础过滤和分析
   • jq：处理JSON日志
   • lnav：高级日志查看器

2. 可视化工具：

   • ELK Stack (Elasticsearch + Logstash + Kibana)
   • Grafana + Loki
   • Splunk

3. Python分析库：

   python复制import pandas as pd
   
   # 读取日志到DataFrame
   logs = pd.read_csv(
       'app.log',
       sep=' - ',
       names=['timestamp', 'level', 'logger', 'message'],
       engine='python'
   )
   
   # 分析错误频率
   error_stats = logs[logs['level'] == 'ERROR']['logger'].value_counts()
   

6.2 关键指标监控

1. 错误率监控：

   python复制ERROR_THRESHOLD = 0.01  # 1%
   
   def monitor_error_rate():
       total = count_logs(last_minutes=5)
       errors = count_logs(level='ERROR', last_minutes=5)
       rate = errors / total if total > 0 else 0
       
       if rate > ERROR_THRESHOLD:
           alert(f"High error rate: {rate:.2%}")
   

2. 异常模式检测：

   python复制from collections import Counter
   
   def detect_anomalies():
       messages = get_recent_messages(level='ERROR')
       counter = Counter(messages)
       
       for msg, count in counter.most_common(5):
           if count > NORMAL_THRESHOLD:
               alert(f"Anomaly detected: {msg} (count: {count})")
   

6.3 日志采样策略

对于高流量系统，全量日志可能不现实：

1. 动态采样：

   python复制class DynamicSamplingFilter(logging.Filter):
       def __init__(self, sample_rate=0.1):
           self.sample_rate = sample_rate
       
       def filter(self, record):
           if record.levelno >= logging.ERROR:
               return True
           return random.random() < self.sample_rate
   

2. 分级采样：

   • ERROR/CRITICAL：100%采样
   • WARNING：50%采样
   • INFO：10%采样
   • DEBUG：1%采样

7. 第三方日志库推荐

7.1 结构化日志库

1. structlog：

   python复制import structlog
   
   structlog.configure(
       processors=[
           structlog.processors.JSONRenderer()
       ]
   )
   
   log = structlog.get_logger()
   log.info("user_login", user="alice", ip="192.168.1.1")
   

2. python-json-logger：

   python复制from pythonjsonlogger import jsonlogger
   
   formatter = jsonlogger.JsonFormatter(
       '%(asctime)s %(levelname)s %(name)s %(message)s')
   

7.2 异步日志库

1. loguru：

   python复制from loguru import logger
   
   logger.add("file.log", rotation="100 MB", enqueue=True)  # 自动异步
   logger.info("Async log message")
   

2. aiologger：

   python复制import asyncio
   from aiologger import Logger
   
   async def main():
       logger = Logger.with_default_handlers()
       await logger.info("Async log")
   
   asyncio.run(main())
   

7.3 特殊用途日志库

1. sentry-sdk（错误监控）：

   python复制import sentry_sdk
   
   sentry_sdk.init(dsn="your-dsn")
   
   try:
       risky_operation()
   except Exception:
       logger.exception("Operation failed")
   

2. elastic-apm（性能监控）：

   python复制from elasticapm.handlers.logging import LoggingHandler
   
   apm_handler = LoggingHandler(client)
   logger.addHandler(apm_handler)
   

8. 从配置到实践：完整案例

8.1 Flask Web应用日志配置

python复制from flask import Flask, request
import logging
from logging.handlers import RotatingFileHandler

app = Flask(__name__)

def configure_logging():
    # 禁用默认的Flask日志处理器
    app.logger.handlers.clear()
    
    # 控制台处理器
    console_handler = logging.StreamHandler()
    console_handler.setLevel(logging.INFO)
    
    # 文件处理器
    file_handler = RotatingFileHandler(
        'flask_app.log',
        maxBytes=1024*1024,
        backupCount=5
    )
    file_handler.setLevel(logging.DEBUG)
    
    # 格式化
    formatter = logging.Formatter(
        '[%(asctime)s] %(levelname)s in %(module)s: %(message)s'
    )
    console_handler.setFormatter(formatter)
    file_handler.setFormatter(formatter)
    
    # 添加处理器
    app.logger.addHandler(console_handler)
    app.logger.addHandler(file_handler)
    app.logger.setLevel(logging.DEBUG)

@app.before_request
def log_request():
    app.logger.info(
        "Request: %s %s",
        request.method,
        request.path,
        extra={'ip': request.remote_addr}
    )

@app.after_request
def log_response(response):
    app.logger.info(
        "Response: %s %s -> %s",
        request.method,
        request.path,
        response.status_code
    )
    return response

if __name__ == '__main__':
    configure_logging()
    app.run()

8.2 Django日志配置示例

settings.py配置：

python复制LOGGING = {
    'version': 1,
    'disable_existing_loggers': False,
    'formatters': {
        'verbose': {
            'format': '{levelname} {asctime} {module} {process:d} {thread:d} {message}',
            'style': '{',
        },
    },
    'handlers': {
        'file': {
            'level': 'DEBUG',
            'class': 'logging.handlers.TimedRotatingFileHandler',
            'filename': 'django.log',
            'when': 'midnight',
            'backupCount': 7,
            'formatter': 'verbose'
        },
        'mail_admins': {
            'level': 'ERROR',
            'class': 'django.utils.log.AdminEmailHandler',
            'include_html': True,
        }
    },
    'loggers': {
        'django': {
            'handlers': ['file'],
            'level': 'INFO',
            'propagate': True,
        },
        'myapp': {
            'handlers': ['file', 'mail_admins'],
            'level': 'DEBUG',
        },
    },
}

8.3 异步任务日志实践

Celery任务日志示例：

python复制from celery import Celery
from celery.signals import after_setup_logger

app = Celery('tasks')

@after_setup_logger.connect
def setup_loggers(logger, *args, **kwargs):
    # 确保每个worker有自己的日志文件
    handler = logging.FileHandler(f'celery_worker_{os.getpid()}.log')
    formatter = logging.Formatter(
        '%(asctime)s - %(name)s - %(levelname)s - %(message)s')
    handler.setFormatter(formatter)
    logger.addHandler(handler)

@app.task
def process_data(data):
    logger = process_data.get_logger()
    logger.info("Processing data: %s", data[:100])
    try:
        result = complex_operation(data)
        logger.info("Processing completed")
        return result
    except Exception as e:
        logger.exception("Processing failed")
        raise

9. 日志测试与验证策略

9.1 单元测试中的日志验证

python复制import unittest
from unittest.mock import patch
import logging

class TestLogging(unittest.TestCase):
    def setUp(self):
        self.logger = logging.getLogger('test')
        self.logger.setLevel(logging.INFO)
        self.handler = logging.StreamHandler()
        self.logger.addHandler(self.handler)
    
    def test_error_logging(self):
        with self.assertLogs('test', level='ERROR') as cm:
            self.logger.error('Test error')
            self.assertEqual(cm.output, ['ERROR:test:Test error'])
    
    def test_log_count(self):
        with patch.object(self.handler, 'emit') as mock_emit:
            self.logger.info('Message 1')
            self.logger.warning('Message 2')
            self.assertEqual(mock_emit.call_count, 2)

9.2 集成测试日志检查

python复制def test_api_logging():
    with LogCapture() as logs:
        response = client.get('/api/data')
        logs.check(
            ('app.views', 'INFO', 'GET /api/data'),
            ('app.views', 'INFO', 'Response 200 OK')
        )

9.3 日志性能测试

python复制import timeit

def test_logging_performance():
    setup = '''
import logging
logger = logging.getLogger('perf_test')
logger.setLevel(logging.INFO)
logger.addHandler(logging.NullHandler())
    '''
    
    stmt = 'logger.info("Test message")'
    
    time = timeit.timeit(stmt, setup, number=10000)
    print(f"Average time per log: {time/10000*1e6:.2f}μs")

10. 个人经验与建议

在实际项目中实施日志策略多年，我总结了以下关键经验：

1. 尽早建立日志规范：

   • 在项目启动阶段就定义日志格式、级别和存储策略
   • 制定团队日志编写指南（如禁止直接拼接敏感信息）

2. 平衡日志量与价值：

   • 太多日志会淹没重要信息
   • 太少日志则难以诊断问题
   • 遵循"每个日志条目都应有明确目的"原则

3. 重视日志上下文：

   • 确保每条日志都包含足够上下文（如用户ID、请求ID）
   • 但避免记录敏感数据（密码、信用卡号等）

4. 定期审查日志：

   • 不仅是在出现问题时查看
   • 定期分析日志模式，发现潜在问题

5. 自动化日志分析：

   • 设置自动告警规则（如错误率突增）
   • 建立常见问题的自动诊断脚本

一个特别有用的技巧是创建"日志健康检查"端点：

python复制@app.route('/_health/log')
def log_health_check():
    logger.debug("Health check - DEBUG level")
    logger.info("Health check - INFO level")
    logger.warning("Health check - WARNING level")
    logger.error("Health check - ERROR level")
    return jsonify({"status": "ok"})

这个端点可以：

• 验证所有日志级别是否正常工作
• 检查日志格式是否符合预期
• 确认日志文件权限和磁盘空间