栈记
PythonFastAPI

loguru 日志集成

标准库 logging、loguru sink 与 FastAPI 日志集成

logging 模块

原生 logging 功能总结

Python 标准库 logging 是很多框架和第三方库默认使用的日志系统。Uvicorn、SQLAlchemy 都走这套机制。

Logger

Logger 是日志入口。

import logging

logger = logging.getLogger("app.user")

logger.info("User created")
logger.warning("Login failed")
logger.error("Unhandled error")

logging.getLogger("app.user") 会从全局 registry 里取 logger。同名 logger 在同一个进程里是同一个对象。

assert logging.getLogger("app.user") is logging.getLogger("app.user")

第三方库也会使用固定 logger name:

logging.getLogger("uvicorn.error")
logging.getLogger("uvicorn.access")
logging.getLogger("sqlalchemy.engine")

因此项目可以通过这些名字配置第三方日志。

Handler

Handler 决定日志输出到哪里。

import logging

logger = logging.getLogger("app")
logger.setLevel(logging.INFO)

console_handler = logging.StreamHandler()
file_handler = logging.FileHandler("logs/app.log", encoding="utf-8")

logger.addHandler(console_handler)
logger.addHandler(file_handler)

logger.info("Service started")

这条日志会同时输出到控制台和 logs/app.log。

Formatter

Formatter 决定日志格式。

formatter = logging.Formatter(
    fmt="%(asctime)s | %(levelname)s | %(name)s:%(funcName)s:%(lineno)d - %(message)s",
    datefmt="%Y-%m-%d %H:%M:%S",
)

console_handler.setFormatter(formatter)
file_handler.setFormatter(formatter)

常用字段:

%(asctime)s      时间
%(levelname)s   日志等级
%(name)s        logger name
%(funcName)s    函数名
%(lineno)d      行号
%(message)s     日志内容

配置文件

日志配置可以写在代码里,也可以放到配置文件里。配置文件更适合服务启动时统一接管格式、级别、handler 和第三方 logger。

标准库提供两类常见入口:

from logging.config import fileConfig, dictConfig

fileConfig("logging.ini", disable_existing_loggers=False)
dictConfig(LOGGING_CONFIG)

disable_existing_loggers=False 很重要。FastAPI、Uvicorn、SQLAlchemy 这些库通常会先创建自己的 logger,如果这里用默认值 True,没有在配置里显式声明的既有 logger 可能会被禁用。

INI 风格配置适合简单项目:

[loggers]
keys=root,uvicorn

[handlers]
keys=console

[formatters]
keys=standard

[logger_root]
level=INFO
handlers=console

[logger_uvicorn]
level=INFO
handlers=console
qualname=uvicorn
propagate=0

[handler_console]
class=StreamHandler
level=INFO
formatter=standard
args=(sys.stderr,)

[formatter_standard]
format=%(asctime)s | %(levelname)s | %(name)s - %(message)s
datefmt=%Y-%m-%d %H:%M:%S

使用方式:

from logging.config import fileConfig

fileConfig("logging.ini", disable_existing_loggers=False)

dictConfig

dictConfig 用字典描述 logging 配置。它比 INI 更适合 FastAPI 项目,因为配置可以来自 Python dict、YAML、JSON,也更容易按环境变量拼接。

from logging.config import dictConfig

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",
            "level": "INFO",
            "formatter": "standard",
            "stream": "ext://sys.stderr",
        },
        "app_file": {
            "class": "logging.handlers.RotatingFileHandler",
            "level": "INFO",
            "formatter": "standard",
            "filename": "logs/app.log",
            "maxBytes": 10 * 1024 * 1024,
            "backupCount": 5,
            "encoding": "utf-8",
        },
    },
    "loggers": {
        "app": {
            "level": "INFO",
            "handlers": ["console", "app_file"],
            "propagate": False,
            "disabled": False,
        },
        "uvicorn.error": {
            "level": "INFO",
            "handlers": ["console"],
            "propagate": False,
            "disabled": False,
        },
        "uvicorn.access": {
            "level": "INFO",
            "handlers": [],
            "propagate": False,
            "disabled": True,
        },
    },
    "root": {
        "level": "INFO",
        "handlers": ["console"],
    },
}

dictConfig(LOGGING_CONFIG)

propagate 和 disabled

propagate 和 disabled 经常一起考虑,但语义不同。

logger name 有层级关系:

root
└── app
    └── app.user

如果 propagate=True,日志会继续交给父 logger。接管某个 logger 时,通常要关闭冒泡,避免同一条日志先被当前 logger 的 handler 输出,又被父 logger 或 root logger 再输出一次。

logger = logging.getLogger("app.user")
logger.propagate = False

disabled=True 表示彻底禁用这个 logger。

access_logger = logging.getLogger("uvicorn.access")
access_logger.handlers.clear()
access_logger.propagate = False
access_logger.disabled = True

如果只是替换输出,不应该禁用 logger:

logger.handlers.clear()
logger.addHandler(MyHandler())
logger.propagate = False
logger.disabled = False

合并判断规则:

要接管输出:handlers.clear() + addHandler(...) + propagate=False + disabled=False
要完全关闭:handlers.clear() + propagate=False + disabled=True
只想交给 root:不挂 handler,保持 propagate=True,不设置 disabled=True

轮转

轮转是 handler 的能力,不是 logger 的能力。

按大小轮转:

from logging.handlers import RotatingFileHandler

handler = RotatingFileHandler(
    "logs/app.log",
    maxBytes=10 * 1024 * 1024,
    backupCount=5,
    encoding="utf-8",
)

按时间轮转:

from logging.handlers import TimedRotatingFileHandler

handler = TimedRotatingFileHandler(
    "logs/app.log",
    when="midnight",
    interval=1,
    backupCount=7,
    encoding="utf-8",
)

Loguru

Loguru 功能总结

Loguru 是更易用的日志库。业务代码里使用 Loguru 会比原生 logging 更简洁。

基础写法

from loguru import logger

logger.debug("debug message")
logger.info("service started")
logger.warning("something unusual")
logger.error("request failed")

# Loguru 推荐 `{}` 格式化:
logger.info("User created user_id={} username={}", user_id, username)

# 异常日志:
try:
    1 / 0
except ZeroDivisionError:
    logger.exception("Calculate failed")

add 添加输出目标

logger.add() 添加输出目标,作用类似原生 logging 的 handler。

import sys
from loguru import logger

logger.remove()

# 控制台输出
logger.add(sys.stderr, level="INFO", colorize=True)
# 全量日志文件
logger.add("logs/app.log", level="DEBUG", rotation="10 MB", retention=5, encoding="utf-8",  backtrace=False, diagnose=False)
# 错误日志文件
logger.add("logs/error.log", level="ERROR", rotation="10 MB", retention=5, encoding="utf-8", backtrace=False, diagnose=False)

一条 ERROR 日志会进入控制台、app.log、error.log。一条 INFO 日志不会进入 error.log。

参数作用
sink输出目标,可以是 sys.stderr、文件路径、文件对象、协程函数或自定义 sink
level最低输出级别,比如 DEBUG、INFO、ERROR
format日志格式,默认使用 Loguru 内置格式
filter过滤日志,可以按模块、logger name 或 record 内容决定是否输出
rotation什么时候切分日志文件,支持大小、时间、定时点,比如 "10 MB"、"00:00"
retention旧日志保留策略,可以是数量、时间长度,比如 5、"7 days"
compression轮转后的旧日志压缩方式,比如 "zip"、"gz"
encoding文件编码,通常设置为 "utf-8"
enqueue是否使用队列异步写日志,多进程或高并发写文件时建议开启
serialize是否输出 JSON 字符串,适合被日志采集系统解析
colorize是否启用终端颜色,控制台可以开,文件通常关闭
backtrace是否显示更长的异常调用链,生产环境通常关闭
diagnose是否在异常堆栈里展示变量值,生产环境建议关闭,避免输出敏感数据
catchsink 写入异常是否被 Loguru 捕获,默认会捕获,避免日志系统反过来影响业务流程

remove 移除 sinks

logger.remove() 移除的是 Loguru 自己的 sinks,不会移除原生 logging 的 handlers。

logger.remove()  # 清理 Loguru sinks
logging.getLogger("uvicorn.error").handlers.clear()  # 清理 stdlib handlers

bind 日志绑定上下文

# 绑定后的数据进入 `record["extra"]`。
request_logger = logger.bind(request_id="req-123")
request_logger.info("Request started")

opt 控制单条日志行为

logger.opt(exception=True).error("Unhandled exception")
# `depth` 常用于封装日志方法或转发日志时修正调用位置。
logger.opt(depth=1).info("Log from wrapper")

patcher 统一修改日志记录

from contextvars import ContextVar

request_id_context = ContextVar("request_id", default="-")

def patch_record(record):
    request_id = request_id_context.get()
    if request_id != "-":
        record["message"] = f"[request_id={request_id}] {record['message']}"

logger.configure(patcher=patch_record)

从原生 logging 转发到 Loguru

Uvicorn、SQLAlchemy 使用原生 logging。业务代码使用 Loguru 时,可以通过自定义 logging.Handler 转发。

class InterceptHandler(logging.Handler):
    def emit(self, record):
        # record 是原生 logging 生成的 LogRecord
        # 这里把它转换成一条 Loguru 日志
        logger.bind(display_name=record.name).opt(
            exception=record.exc_info,
        ).log(record.levelname, record.getMessage())
# 接管第三方 logger:
third_logger = logging.getLogger("uvicorn.error")
third_logger.handlers.clear()
third_logger.addHandler(InterceptHandler())
third_logger.propagate = False
third_logger.disabled = False
# 彻底关闭第三方 logger:
access_logger = logging.getLogger("uvicorn.access")
access_logger.handlers.clear()
access_logger.propagate = False
access_logger.disabled = True

FastAPI 集成实践

FastAPI 日志集成实践总结

Loguru 基础配置

# app/core/logger.py
import sys
from contextvars import ContextVar
from pathlib import Path
from typing import Any
from loguru import logger
from app.core.config import settings
from app.core.logging_sqlalchemy import configure_sqlalchemy_logging
from app.core.logging_uvicorn import configure_uvicorn_logging

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

class AppLogger:
    def __init__(self, log_dir: Path, level: str, max_bytes: int, backup_count: int) -> None:
        self.log_dir = log_dir
        self.level = level
        self.max_bytes = max_bytes
        self.backup_count = backup_count
        self._configured = False

    def setup(self) -> None:
        if self._configured:
            return
        self.log_dir.mkdir(parents=True, exist_ok=True)

        # 1. 清理 Loguru 默认 sink
        logger.remove()
        # 2. 为所有 Loguru 日志补充 display_name / request_id
        logger.configure(patcher=self._patch_record)
        # 3. 控制台输出
        logger.add(sys.stderr, level=self.level, colorize=True, backtrace=False, diagnose=False)
        # 4. 全量日志文件
        logger.add(self.log_dir / "app.log", level=self.level, rotation=self.max_bytes, retention=self.backup_count, 
            encoding="utf-8", 
            colorize=False,
            backtrace=False,
            diagnose=False,
        )
        # 5. 错误日志文件
        logger.add(self.log_dir / "error.log", level="ERROR", rotation=self.max_bytes, retention=self.backup_count,
            encoding="utf-8",
            colorize=False,
            backtrace=False,
            diagnose=False,
        )

        # 6. 接管第三方 stdlib logging
        configure_uvicorn_logging()
        configure_sqlalchemy_logging(self.level)
        self._configured = True

    def get_logger(self, name: str | None = None):
        if name is None:
            return logger
        return logger.bind(display_name=name)

    @staticmethod
    def _patch_record(record: dict[str, Any]) -> None:
        message_parts = []

        display_name = record["extra"].get("display_name")
        if display_name:
            message_parts.append(str(display_name))

        request_id = record["extra"].get("request_id") or request_id_context.get()
        if request_id != "-":
            message_parts.append(f"[request_id={request_id}]")

        if message_parts:
            record["message"] = f"{' '.join(message_parts)} {record['message']}"

app_logger = AppLogger(
    log_dir=settings.LOG_DIR,
    level=settings.LOG_LEVEL,
    max_bytes=settings.LOG_MAX_BYTES,
    backup_count=settings.LOG_BACKUP_COUNT,
)

get_logger = app_logger.get_logger

app_logger 是最终导出的单例。应用启动时只调用 app_logger.setup(),它内部完成 Loguru sink 初始化,并调用 configure_uvicorn_logging()、configure_sqlalchemy_logging() 接管第三方日志。

业务 logger

from app.core.logger import get_logger

logger = get_logger("app.users")

业务代码:

logger.info("User created user_id={}", user.id)
logger.warning("Login failed username={}", username)
logger.exception("Create user failed username={}", username)

Uvicorn 集成示例

# app/core/logging_uvicorn.py
import logging
import os
from loguru import logger

_UVICORN_LOGGER_NAMES = ("uvicorn.error", "uvicorn", "uvicorn.asgi")

class InterceptHandler(logging.Handler):
    def emit(self, record: logging.LogRecord) -> None:
        try:
            level = logger.level(record.levelname).name
        except ValueError:
            level = record.levelno

        frame = logging.currentframe()
        depth = 0
        while frame:
            filename = frame.f_code.co_filename
            if filename == __file__ or f"{os.sep}logging{os.sep}" in filename:
                frame = frame.f_back
                depth += 1
            else:
                break

        # 将 Uvicorn 的 stdlib LogRecord 转成 Loguru 日志
        logger.bind(display_name=record.name).opt(
            depth=depth,
            exception=record.exc_info,
        ).log(level, record.getMessage())

def configure_uvicorn_logging() -> None:
    # uvicorn.access 会和中间件 request line 重复,所以关闭
    access_logger = logging.getLogger("uvicorn.access")
    access_logger.handlers.clear()
    access_logger.propagate = False
    access_logger.disabled = True

    # uvicorn.error / uvicorn / uvicorn.asgi 继续保留,但转发给 Loguru
    for logger_name in _UVICORN_LOGGER_NAMES:
        uvicorn_logger = logging.getLogger(logger_name)
        uvicorn_logger.handlers.clear()
        uvicorn_logger.addHandler(InterceptHandler())
        uvicorn_logger.propagate = False
        uvicorn_logger.disabled = False

SQLAlchemy 集成示例

# app/core/logging_sqlalchemy.py
import logging
from loguru import logger
from app.core.config import settings

_SQL_LOGGER_NAMES = ("sqlalchemy", "sqlalchemy.engine")
_SQL_PREFIXES = (
    "ALTER ",
    "CREATE ",
    "DELETE ",
    "DESCRIBE ",
    "DROP ",
    "INSERT ",
    "SELECT ",
    "UPDATE ",
)

class SqlAlchemyHandler(logging.Handler):
    def emit(self, record: logging.LogRecord) -> None:
        message = record.getMessage()

        # 只保留 SQL statement,过滤事务行、结果行等噪声
        if not message.strip().upper().startswith(_SQL_PREFIXES):
            return

        # SQLAlchemy 的 stdlib LogRecord 转成 Loguru 日志
        logger.bind(display_name=record.name).opt(
            exception=record.exc_info,
        ).debug(message)

def _normalize_level(level: str | int) -> str:
    if isinstance(level, int):
        return logging.getLevelName(level)
    return level

def configure_sqlalchemy_logging(level: str | int) -> None:
    log_level = logging.getLevelName(_normalize_level(level))
    enable_sql_logs = settings.SQL_ECHO and log_level <= logging.DEBUG

    for logger_name in _SQL_LOGGER_NAMES:
        sql_logger = logging.getLogger(logger_name)
        sql_logger.handlers.clear()
        sql_logger.propagate = False
        sql_logger.setLevel(logging.DEBUG if enable_sql_logs else logging.WARNING)

    if enable_sql_logs:
        logging.getLogger("sqlalchemy.engine").addHandler(SqlAlchemyHandler())

FastAPI request_id 中间件

from uuid import uuid4
from fastapi import Request
from starlette.middleware.base import BaseHTTPMiddleware
from app.core.logger import get_logger, request_id_context

logger = get_logger("app.request")

class LoggingMiddleware(BaseHTTPMiddleware):
    async def dispatch(self, request: Request, call_next):
        request_id = request.headers.get("X-Request-ID") or uuid4().hex
        token = request_id_context.set(request_id)

        try:
            target = request.url.path
            if request.url.query:
                target = f"{target}?{request.url.query}"

            # 由中间件替代 uvicorn.access 输出 request line
            logger.info(
                '{} - "{} {} HTTP/{}"',
                request.client.host if request.client else "-",
                request.method,
                target,
                request.scope.get("http_version", "1.1"),
            )

            response = await call_next(request)
            response.headers["X-Request-ID"] = request_id
            return response
        finally:
            request_id_context.reset(token)

实际项目中还需要补充:

  • request/response body 脱敏。
  • 大 body 截断。
  • response body iterator 重建。
  • binary body 保护。

FastAPI 入口

from fastapi import FastAPI

from app.core.config import settings
from app.core.logger import app_logger
from app.middlewares.logging import LoggingMiddleware

app_logger.setup()

app = FastAPI(
    title=settings.APP_NAME,
    debug=settings.APP_ENV == "local",
)

app.add_middleware(LoggingMiddleware)

On this page