Flask默认日志不支持直接写JSON,需替换FileHandler为自定义handler或使用python-json-logger;须正确处理exc_info、上下文字段、日志轮转及UTF-8编码。

Flask 默认日志不支持直接写 JSON,得自己封装 handler
Flask 的 app.logger 底层用的是 Python 标准 logging 模块,默认输出纯文本。想写结构化 JSON 到文件,不能只靠 Formatter 改格式——得替换掉默认的 FileHandler,换成能序列化字典的自定义 handler。
常见错误是只改 Formatter,比如继承 logging.Formatter 并在 format() 里 json.dumps(),这会导致日志字段丢失(如 exc_info、stack_info 不被自动提取),而且时间戳、行号等元信息容易错乱。
实操建议:
- 继承
logging.FileHandler,重写emit()方法,在写入前把record.__dict__转成字典并补全关键字段(asctime、levelname、message等) - 用
logging.setLogRecordFactory()注入一个工厂函数,确保所有 log record 都带request_id、endpoint等上下文字段(需配合 Flask 中间件) - 避免在
emit()里做耗时操作(如每次调用都datetime.now().isoformat()),优先复用record.asctime
用 python-json-logger 是最省事的方案
python-json-logger 是专为这个场景设计的第三方包,它提供 JsonFormatter,能正确处理 exc_info、stack_info、extra 字段,并兼容标准 FileHandler。
立即学习“Python免费学习笔记(深入)”;
安装和配置示例:
pip install python-json-logger
在 Flask 初始化后加:
import logging
from pythonjsonlogger import jsonlogger
<p>handler = logging.FileHandler("app.log")
formatter = jsonlogger.JsonFormatter(
"%(asctime)s %(name)s %(levelname)s %(message)s %(funcName)s %(lineno)d",
rename_fields={"asctime": "@timestamp", "levelname": "level"}
)
handler.setFormatter(formatter)</p><p>app.logger.addHandler(handler)
app.logger.setLevel(logging.INFO)注意点:
-
rename_fields只影响顶层 key 名,不递归重命名嵌套结构(比如exc_info里的字段) - 如果用了
app.logger.info("msg", extra={"user_id": 123}),user_id会平级出现在 JSON 顶层,无需额外处理 - Windows 下文件路径含中文时,
FileHandler要显式传encoding="utf-8",否则 JSON 中文会乱码
在请求生命周期中注入 request 相关字段
纯 JSON 日志没上下文价值很低。想让每条日志带 method、path、status_code、duration_ms,不能靠全局变量——要用 Flask 的 before_request / after_request + g 对象或 logging.LoggerAdapter。
推荐用 LoggerAdapter 动态注入:
from flask import g, request, after_this_request
import time
<p>class RequestContextAdapter(logging.LoggerAdapter):
def process(self, msg, kwargs):
context = {
"method": getattr(g, "method", request.method),
"path": getattr(g, "path", request.path),
"request_id": getattr(g, "request_id", "unknown"),
}
kwargs["extra"] = {<strong>kwargs.get("extra", {}), </strong>context}
return msg, kwargs</p><p>app.logger = RequestContextAdapter(app.logger, {}) # 绑定到 app.logger</p><p>@app.before_request
def before_req():
g.start_time = time.time()</p><p>@app.after_request
def after_req(response):
duration = (time.time() - g.start_time) * 1000
app.logger.info(
"request completed",
extra={"status_code": response.status_code, "duration_ms": round(duration, 2)}
)
return response关键细节:
- 别在
before_request里直接往app.logger写日志——此时响应状态还没出来,status_code不可知 -
after_this_request比after_request更安全,它在 response 已生成但尚未发送时执行,适合记耗时 - 如果用了 Gunicorn,要禁用其访问日志(
--access-logfile "-" --error-logfile "-"),否则重复记录
日志文件滚动和 Unicode 处理容易被忽略
生产环境必须轮转日志,否则单个文件无限增长。Python 标准 RotatingFileHandler 或 TimedRotatingFileHandler 都支持,但和 JSON 配合时有两个坑:
- 轮转后新文件开头不是完整 JSON(没有
[),导致下游解析失败——JSON 日志本质是“每行一个 JSON 对象”(NDJSON),不是单个大 JSON 数组,所以轮转本身没问题,但别指望用json.load()读整个文件 -
TimedRotatingFileHandler在 Windows 上按秒轮转可能失效(系统时钟精度问题),建议用RotatingFileHandler+maxBytes控制 - 所有 handler 必须显式指定
encoding="utf-8",否则含中文的 JSON 写入后无法被jq或 Pythonjson.loads()正确解析
示例配置:
from logging.handlers import RotatingFileHandler <p>handler = RotatingFileHandler( "app.log", maxBytes=10 <em> 1024 </em> 1024, # 10MB backupCount=5, encoding="utf-8" )
真正难的是日志消费端——别指望用 tail -f 实时看 JSON 日志,得配 jq 或 ELK;如果只是调试,加个简易格式化中间件更实用:
@app.after_request
def pretty_json_log(response):
if request.path.startswith("/api/") and response.is_json:
try:
app.logger.debug("response body", extra={"body": response.get_json()})
except Exception:
pass
return response这种写法会把响应体塞进日志,但要注意:大响应体(>1MB)会拖慢请求、撑爆磁盘,线上务必加大小限制和开关控制。


















