FastAPI日志配置与结构化日志教程

日志是任何应用程序的重要组成部分，它帮助我们调试问题、监控性能和了解系统行为。在FastAPI中，日志配置相对简单，但掌握它可以让你的应用更健壮。本教程将带你从基础到进阶，学习如何配置日志并实现结构化日志，即使你是新手也能轻松上手。

为什么需要日志？

在开发FastAPI应用时，你可能遇到错误、需要追踪请求流程或监控性能。日志就是记录这些信息的工具，它可以输出到控制台、文件或其他系统，便于分析和调试。

基本日志配置

FastAPI基于Python，因此使用Python内置的logging模块来配置日志。让我们一步步来。

第一步：导入logging模块

在FastAPI应用的入口文件（如main.py）中，首先导入logging模块。

import logging

第二步：配置日志

最简单的方式是设置日志级别和处理器。例如，将日志输出到控制台。

import logging

# 创建一个logger实例
logger = logging.getLogger(__name__)

# 设置日志级别，例如DEBUG级别会记录所有信息
logger.setLevel(logging.DEBUG)

# 创建一个控制台处理器
console_handler = logging.StreamHandler()
console_handler.setLevel(logging.DEBUG)

# 定义日志格式
formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
console_handler.setFormatter(formatter)

# 将处理器添加到logger
logger.addHandler(console_handler)

第三步：在FastAPI中使用日志

在FastAPI路由或依赖项中，使用这个logger记录信息。

from fastapi import FastAPI, Depends
import logging

app = FastAPI()

# 获取logger
logger = logging.getLogger(__name__)

@app.get("/")
def read_root():
    logger.info("处理根路径请求")
    return {"message": "Hello, World!"}

@app.get("/items/{item_id}")
def read_item(item_id: int):
    logger.debug(f"获取物品ID: {item_id}")
    # 模拟错误
    try:
        result = 1 / 0  # 引发错误
    except Exception as e:
        logger.error(f"处理物品时出错: {e}")
        return {"error": "内部错误"}
    return {"item_id": item_id}

运行应用后，访问这些端点，你会看到日志输出到控制台，显示时间、名称、级别和消息。

结构化日志：进阶配置

结构化日志是一种以机器可读格式（如JSON）记录日志的方法，便于在日志聚合系统中进行分析。对于生产环境，这非常有价值。

什么是结构化日志？

传统日志是文本字符串，结构化日志则记录为键值对，例如JSON格式。这让你能轻松地查询和分析日志数据，如按错误类型筛选。

使用structlog库实现结构化日志

structlog是一个流行的Python库，用于结构化日志记录。首先，安装它。

pip install structlog

配置structlog

在FastAPI应用中集成structlog。我们将配置它以输出JSON格式的日志。

import structlog
import logging
from fastapi import FastAPI

# 初始化structlog
structlog.configure(
    processors=[
        structlog.stdlib.filter_by_level,
        structlog.stdlib.add_logger_name,
        structlog.stdlib.add_log_level,
        structlog.stdlib.PositionalArgumentsFormatter(),
        structlog.processors.TimeStamper(fmt="iso"),
        structlog.processors.JSONRenderer()  # 输出JSON格式
    ],
    context_class=dict,
    logger_factory=structlog.stdlib.LoggerFactory(),
    wrapper_class=structlog.stdlib.BoundLogger,
    cache_logger_on_first_use=True,
)

# 创建一个logger
logger = structlog.get_logger()

app = FastAPI()

@app.get("/")
def read_root():
    logger.info("处理根路径请求", endpoint="/", method="GET")
    return {"message": "Hello, World!"}

@app.get("/items/{item_id}")
def read_item(item_id: int):
    logger.debug("获取物品", item_id=item_id)
    try:
        result = 1 / 0
    except Exception as e:
        logger.error("处理物品错误", item_id=item_id, error=str(e))
        return {"error": "内部错误"}
    return {"item_id": item_id}

在这个示例中，日志会以JSON格式输出，如：{"event": "处理根路径请求", "endpoint": "/", "method": "GET", "level": "info", "timestamp": "2023-10-05T12:00:00Z", "logger": "__main__"}。

将结构化日志输出到文件

如果你想将日志保存到文件，可以添加一个文件处理器。

import logging.handlers

# 添加文件处理器
file_handler = logging.handlers.RotatingFileHandler('app.log', maxBytes=10000, backupCount=5)
file_handler.setLevel(logging.DEBUG)
file_formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
file_handler.setFormatter(file_formatter)

# 获取标准logger并添加处理器
std_logger = logging.getLogger(__name__)
std_logger.addHandler(file_handler)

# 结合structlog，你可能需要自定义处理器
# 简单起见，这里使用标准logging到文件，structlog到控制台

最佳实践

1. 环境变量控制日志级别：使用环境变量（如LOG_LEVEL）动态设置日志级别，便于在不同环境（开发、生产）切换。

2. 集中式日志系统：在生产环境中，考虑使用像Elasticsearch、Logstash和Kibana（ELK栈）或Sentry等工具来聚合和分析日志。

3. 避免日志污染：不要在日志中记录敏感信息，如密码或API密钥。使用结构化日志时，确保加密或掩码数据。

4. 日志旋转：对于文件日志，使用旋转处理器以避免文件过大。Python的logging.handlers.RotatingFileHandler可以帮助实现。

总结

通过本教程，你学会了在FastAPI中配置基本日志和结构化日志。日志是开发中不可或缺的工具，正确配置可以大大提高调试效率和系统可维护性。从简单的控制台输出到复杂的JSON结构化日志，逐步进阶，确保你的应用日志既人性化又机器友好。

继续实践，尝试在你的项目中应用这些技巧，并根据需求调整配置。Happy coding！