Python日志与异常处理实战：从基础到高级技巧-代码聚汇网

Python日志与异常处理实战：从基础到高级技巧

大厂男孩的粉丝

1. Python项目日志与异常处理的重要性

在项目开发初期，很多开发者往往只关注功能实现而忽略了日志和异常处理。这种短视行为在项目上线后会带来一系列严重问题。我经历过一个电商项目，上线初期由于缺乏完善的日志系统，当用户反馈支付失败时，我们花了整整两天才定位到一个第三方支付接口的超时问题。这个教训让我深刻认识到：良好的日志设计和异常处理不是可选项，而是项目质量的基石。

日志系统就像飞机的黑匣子，记录了系统运行的每一个关键动作。当系统出现问题时，完善的日志能让我们快速还原现场。我曾接手过一个遗留系统，其日志仅简单打印到控制台且没有任何格式，排查一个数据库死锁问题耗费了团队三周时间。而合理的异常处理则如同汽车的防撞系统，能在问题发生时保护用户体验。一个未处理的异常可能导致用户看到晦涩的堆栈信息，甚至直接暴露系统内部结构。

2. 日志系统设计详解

2.1 日志级别实战解析

Python的logging模块定义了5个标准级别，但实际项目中我们需要更精细的划分。在我的AI项目中，我扩展了日志级别：

python复制import logging
logging.addLevelName(15, "TRACE")  # 介于DEBUG和INFO之间
logging.addLevelName(25, "NOTICE")  # 重要的业务事件

这种扩展特别适合机器学习场景：

TRACE：记录特征工程中的中间结果
NOTICE：记录模型训练的关键指标

关键经验：生产环境日志级别应设为INFO，开发环境设为DEBUG。但要注意DEBUG日志可能包含敏感信息，上线前必须审查。

2.2 日志格式深度定制

一个结构化的日志格式应该包含机器可读的信息。这是我的推荐格式：

python复制formatter = logging.Formatter(
    "%(asctime)s.%(msecs)03d|%(levelname)s|%(process)d|%(thread)d|"
    "%(module)s.%(funcName)s:%(lineno)d|%(message)s",
    datefmt="%Y-%m-%dT%H:%M:%S"
)

这种格式的优势：

精确到毫秒的时间戳，便于排序和分析
包含进程和线程ID，适合并发场景
记录调用位置，快速定位代码

2.3 日志输出高级配置

2.3.1 文件输出优化

对于生产环境，推荐使用RotatingFileHandler和TimedRotatingFileHandler组合：

python复制from logging.handlers import RotatingFileHandler, TimedRotatingFileHandler

# 按大小轮转(单个文件100MB，保留10个)
size_handler = RotatingFileHandler(
    'app.log', maxBytes=100*1024*1024, backupCount=10
)

# 按天轮转(保留30天)
time_handler = TimedRotatingFileHandler(
    'app.log', when='midnight', backupCount=30
)

2.3.2 网络日志收集

对于分布式系统，建议配置SocketHandler或HTTPHandler将日志发送到中央收集器：

python复制socket_handler = logging.handlers.SocketHandler(
    'logstash.example.com', 5044
)

2.4 日志切割最佳实践

大型项目的日志切割需要考虑：

按业务模块分离日志
压缩历史日志节省空间
使用logrotate工具管理

示例配置：

bash复制# /etc/logrotate.d/python-app
/var/log/python-app/*.log {
    daily
    missingok
    rotate 30
    compress
    delaycompress
    notifempty
    create 640 root adm
    sharedscripts
    postrotate
        systemctl reload python-app >/dev/null 2>&1 || true
    endscript
}

2.5 日志分析实战方案

ELK Stack搭建步骤：

Filebeat收集日志
Logstash解析和过滤
Elasticsearch存储
Kibana可视化

关键过滤规则示例：

ruby复制# logstash.conf
filter {
    grok {
        match => { "message" => "%{TIMESTAMP_ISO8601:timestamp}\|%{LOGLEVEL:level}\|%{NUMBER:pid}\|%{NUMBER:tid}\|%{DATA:location}\|%{GREEDYDATA:msg}" }
    }
    date {
        match => [ "timestamp", "yyyy-MM-dd'T'HH:mm:ss.SSS" ]
    }
}

3. 异常处理高级技巧

3.1 异常分类体系设计

完善的异常体系应该包含：

python复制class AppError(Exception):
    """应用基类异常"""
    def __init__(self, code=500, message='Internal Error', **kwargs):
        self.code = code
        self.message = message
        self.extra = kwargs

class DBError(AppError):
    """数据库异常"""
    
class RedisError(DBError):
    """Redis异常"""
    def __init__(self, command, key):
        super().__init__(
            code=1001,
            message=f"Redis operation failed",
            command=command,
            key=key
        )

3.2 FastAPI异常处理增强

在FastAPI中实现全局异常处理：

python复制from fastapi import Request
from fastapi.responses import JSONResponse

@app.exception_handler(AppError)
async def handle_app_error(request: Request, exc: AppError):
    return JSONResponse(
        status_code=400,
        content={
            "error": {
                "code": exc.code,
                "message": exc.message,
                **exc.extra
            }
        }
    )

@app.exception_handler(500)
async def handle_internal_error(request: Request, exc: Exception):
    logger.critical("Unhandled exception", exc_info=exc)
    return JSONResponse(
        status_code=500,
        content={
            "error": {
                "code": 500,
                "message": "Internal Server Error"
            }
        }
    )

3.3 异常与日志联动

通过装饰器实现自动日志记录：

python复制def log_exceptions(func):
    @wraps(func)
    async def wrapper(*args, **kwargs):
        try:
            return await func(*args, **kwargs)
        except AppError as e:
            logger.warning(
                f"Business exception: {e.code} - {e.message}",
                extra=e.extra
            )
            raise
        except Exception as e:
            logger.error(
                "Unexpected error",
                exc_info=e,
                stack_info=True
            )
            raise
    return wrapper

@log_exceptions
async def sensitive_operation():
    # 业务代码
    pass

4. 性能优化关键点

4.1 日志性能瓶颈

常见问题及解决方案：

I/O阻塞：使用QueueHandler异步处理

python复制from logging.handlers import QueueHandler, QueueListener

log_queue = Queue()
queue_handler = QueueHandler(log_queue)
listener = QueueListener(
    log_queue, 
    file_handler,
    socket_handler
)
listener.start()

格式转换开销：避免频繁字符串格式化

python复制# 不推荐
logger.debug(f"User {user_id} did {action}")

# 推荐
logger.debug("User %s did %s", user_id, action)

4.2 结构化日志实践

使用python-json-logger实现JSON日志：

python复制from pythonjsonlogger import jsonlogger

formatter = jsonlogger.JsonFormatter(
    '%(asctime)s %(levelname)s %(module)s %(funcName)s %(lineno)d %(message)s'
)

输出示例：

json复制{
  "asctime": "2023-07-20T14:32:45.123",
  "levelname": "ERROR",
  "module": "payment",
  "funcName": "process_order",
  "lineno": 42,
  "message": "Payment failed",
  "order_id": 12345,
  "user_id": 67890
}

5. 实战：电商系统日志设计

5.1 核心日志场景

用户行为追踪

python复制logger.info(
    "User action",
    extra={
        "type": "user_action",
        "user_id": 123,
        "action": "add_to_cart",
        "item_id": 456,
        "timestamp": datetime.utcnow().isoformat()
    }
)

订单状态变更

python复制logger.notice(
    "Order status changed",
    extra={
        "order_id": 789,
        "from_status": "pending",
        "to_status": "paid",
        "payment_amount": 99.99
    }
)

5.2 异常处理流程

python复制class OrderError(AppError):
    """订单相关异常"""
    
class InsufficientStock(OrderError):
    def __init__(self, item_id, requested, available):
        super().__init__(
            code=4001,
            message="Insufficient stock",
            item_id=item_id,
            requested=requested,
            available=available
        )

async def create_order(order_data):
    try:
        check_inventory(order_data.items)
        process_payment(order_data.payment)
        # ...
    except InsufficientStock as e:
        logger.warning(
            "Stock check failed",
            extra=vars(e)
        )
        raise
    except PaymentError as e:
        logger.error(
            "Payment processing failed",
            extra={
                "order_id": order_data.id,
                "error": str(e)
            }
        )
        raise

6. 监控与告警集成

6.1 Prometheus指标暴露

通过prometheus-client集成日志指标：

python复制from prometheus_client import Counter, Histogram

LOG_COUNTER = Counter(
    'app_log_messages_total',
    'Total log messages',
    ['level', 'module']
)

class PrometheusLogFilter(logging.Filter):
    def filter(self, record):
        LOG_COUNTER.labels(
            level=record.levelname,
            module=record.module
        ).inc()
        return True

logger.addFilter(PrometheusLogFilter())

6.2 Sentry错误追踪

配置Sentry捕获关键错误：

python复制import sentry_sdk
from sentry_sdk.integrations.logging import LoggingIntegration

sentry_logging = LoggingIntegration(
    level=logging.INFO,
    event_level=logging.ERROR
)

sentry_sdk.init(
    dsn="your-dsn",
    integrations=[sentry_logging],
    traces_sample_rate=1.0
)

7. 测试策略

7.1 日志测试方法

使用pytest测试日志输出：

python复制def test_order_creation_logs(caplog):
    with caplog.at_level(logging.INFO):
        create_test_order()
    
    assert "Order created" in caplog.text
    assert any(
        "order_id" in json.loads(record.msg)
        for record in caplog.records
    )

7.2 异常测试方案

测试异常处理逻辑：

python复制@pytest.mark.parametrize("user_id,expected", [
    (0, InvalidParameterException),
    (999, UserNotFoundException),
    (1, None)
])
def test_get_user_errors(user_id, expected):
    if expected:
        with pytest.raises(expected):
            get_user(user_id)
    else:
        assert get_user(user_id) is not None

在长期的项目维护中，我总结出一个黄金法则：日志要像侦探笔记一样详尽，异常处理要像安全网一样可靠。当系统出现问题时，好的日志能让你快速定位原因；当用户遇到错误时，完善的异常处理能保持体验流畅。记住，今天在日志和异常处理上多花一小时，明天可能节省十小时的故障排查时间。