loguru 日志集成
标准库 logging、loguru sink 与 FastAPI 日志集成
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 = Falsedisabled=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 会比原生 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 | 是否在异常堆栈里展示变量值,生产环境建议关闭,避免输出敏感数据 |
catch | sink 写入异常是否被 Loguru 捕获,默认会捕获,避免日志系统反过来影响业务流程 |
remove 移除 sinks
logger.remove() 移除的是 Loguru 自己的 sinks,不会移除原生 logging 的 handlers。
logger.remove() # 清理 Loguru sinks
logging.getLogger("uvicorn.error").handlers.clear() # 清理 stdlib handlersbind 日志绑定上下文
# 绑定后的数据进入 `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 = TrueFastAPI 集成实践

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_loggerapp_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 = FalseSQLAlchemy 集成示例
# 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)