FastAPI日志：日志格式配置的终极指南

FastAPI日志：日志格式配置的终极指南

【免费下载链接】fastapi FastAPI framework, high performance, easy to learn, fast to code, ready for production 项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi

FastAPI作为一款高性能、易学习、开发快速的现代Python Web框架，在生产环境中可靠运行离不开完善的日志系统。本文将详细介绍如何在FastAPI项目中配置日志格式，帮助开发者轻松实现日志的定制化管理。

为什么日志格式配置对FastAPI项目至关重要

在FastAPI应用的开发和运维过程中，日志扮演着不可或缺的角色。合适的日志格式能够：

• 提供清晰的故障排查线索
• 记录关键业务操作流程
• 满足合规性和审计要求
• 优化性能监控和系统调优

FastAPI的日志系统基于Python标准的logging模块实现，主要通过fastapi/logger.py模块进行管理，默认创建了名为"fastapi"的日志器实例。

FastAPI日志基础配置方法

使用basicConfig快速配置

FastAPI项目中最基础的日志配置方式是使用logging.basicConfig，可以在应用启动时快速设置日志级别和格式：

import logging
from fastapi import FastAPI

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
)

app = FastAPI()

@app.get("/")
def root():
    app.logger.info("Root endpoint accessed")
    return {"message": "Hello World"}

这种方式简单直接，适合快速开发和调试阶段使用。在FastAPI的脚本工具如scripts/docs.py中也采用了类似的基础配置方式。

通过Uvicorn配置日志

当使用Uvicorn作为FastAPI的ASGI服务器时，可以通过命令行参数或代码方式配置日志：

import uvicorn
from fastapi import FastAPI

app = FastAPI()

if __name__ == "__main__":
    uvicorn.run(
        app, 
        host="0.0.0.0", 
        port=8000,
        log_config={
            "version": 1,
            "formatters": {
                "default": {
                    "format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
                }
            },
            "handlers": {
                "console": {
                    "class": "logging.StreamHandler",
                    "formatter": "default"
                }
            },
            "root": {
                "level": "INFO",
                "handlers": ["console"]
            }
        }
    )

这种方式可以实现更精细的日志配置，包括不同处理器的设置和日志级别控制。

高级日志格式定制

结构化日志格式

在生产环境中，推荐使用JSON等结构化格式记录日志，便于日志分析工具进行处理：

import logging
import json
from pythonjsonlogger import jsonlogger

logger = logging.getLogger("fastapi")
handler = logging.StreamHandler()

formatter = jsonlogger.JsonFormatter(
    "%(asctime)s %(name)s %(levelname)s %(message)s %(module)s %(funcName)s"
)
handler.setFormatter(formatter)
logger.addHandler(handler)
logger.setLevel(logging.INFO)

包含请求信息的日志格式

结合FastAPI的请求上下文，可以创建包含请求信息的定制日志格式：

from fastapi import Request, FastAPI
import logging
from contextvars import ContextVar

request_id: ContextVar[str] = ContextVar("request_id", default="")

class RequestFormatter(logging.Formatter):
    def format(self, record):
        record.request_id = request_id.get()
        return super().format(record)

app = FastAPI()

@app.middleware("http")
async def add_request_id(request: Request, call_next):
    request_id.set(str(uuid.uuid4()))
    response = await call_next(request)
    return response

# 配置日志
handler = logging.StreamHandler()
handler.setFormatter(RequestFormatter(
    "%(asctime)s - %(name)s - %(request_id)s - %(levelname)s - %(message)s"
))
logging.getLogger("fastapi").addHandler(handler)

日志配置最佳实践

不同环境的日志策略

• 开发环境：使用详细的日志格式，设置DEBUG级别，便于问题排查
• 测试环境：使用标准日志格式，设置INFO级别，记录关键操作
• 生产环境：使用结构化日志格式，设置WARNING级别，同时配置文件轮转和日志聚合

避免日志泄露敏感信息

在日志配置中，确保过滤掉密码、令牌等敏感信息：

import logging
from typing import Any

class SensitiveDataFilter(logging.Filter):
    def filter(self, record: logging.LogRecord) -> bool:
        if hasattr(record, "msg") and isinstance(record.msg, str):
            # 替换敏感信息
            record.msg = record.msg.replace(record.args.get("password", ""), "***")
        return True

logger = logging.getLogger("fastapi")
logger.addFilter(SensitiveDataFilter())

日志配置文件示例

对于大型FastAPI项目，建议使用配置文件管理日志设置，例如创建logging_config.py：

# logging_config.py
import logging.config

LOGGING_CONFIG = {
    "version": 1,
    "disable_existing_loggers": False,
    "formatters": {
        "detailed": {
            "format": "%(asctime)s - %(name)s - %(levelname)s - %(module)s:%(lineno)d - %(message)s"
        },
        "json": {
            "class": "pythonjsonlogger.jsonlogger.JsonFormatter",
            "format": "%(asctime)s %(name)s %(levelname)s %(module)s %(lineno)d %(message)s"
        }
    },
    "handlers": {
        "console": {
            "class": "logging.StreamHandler",
            "formatter": "detailed",
            "level": "INFO"
        },
        "file": {
            "class": "logging.handlers.RotatingFileHandler",
            "filename": "app.log",
            "maxBytes": 10485760,  # 10MB
            "backupCount": 5,
            "formatter": "json",
            "level": "WARNING"
        }
    },
    "loggers": {
        "fastapi": {
            "handlers": ["console", "file"],
            "level": "INFO",
            "propagate": False
        },
        "uvicorn": {
            "handlers": ["console"],
            "level": "INFO"
        }
    },
    "root": {
        "handlers": ["console"],
        "level": "WARNING"
    }
}

def setup_logging():
    logging.config.dictConfig(LOGGING_CONFIG)

然后在FastAPI应用入口处调用：

# main.py
from fastapi import FastAPI
from logging_config import setup_logging

setup_logging()
app = FastAPI()

# ... 应用代码 ...

通过合理配置FastAPI日志格式，开发者可以获得清晰、有用的日志信息，从而更有效地监控和维护应用系统。无论是简单的基础配置还是复杂的高级定制，FastAPI都提供了灵活的日志管理能力，满足不同场景的需求。

【免费下载链接】fastapi FastAPI framework, high performance, easy to learn, fast to code, ready for production 项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi