Flask中按路由实现自定义Correlation ID读取、全链路日志追踪的方案咨询

核心实现逻辑 #

依托Flask原生的请求上下文隔离机制，配合Python logging系统的动态字段注入能力，完全可以复刻Java MDC、Express生态correlation-id库的全链路追踪能力，不存在第三方库的固定请求头硬编码限制，所有规则可完全自定义。

分步实现流程 #

1. 配置带Correlation ID的全局日志体系 #

通过自定义日志Filter，自动从请求上下文提取Correlation ID并注入所有日志记录，效果和Java MDC透传完全一致：

import logging
from flask import g

class CorrelationIdFilter(logging.Filter):
    def filter(self, record):
        # 从请求上下文读取Correlation ID，非请求触发的日志使用默认标识
        record.correlation_id = g.get("correlation_id", "system-internal")
        return True

# 配置全局日志格式
log_format = "%(asctime)s [%(levelname)s] [%(correlation_id)s] %(name)s: %(message)s"
logging.basicConfig(format=log_format)
# 给全局日志处理器挂载自定义Filter
root_logger = logging.getLogger()
for handler in root_logger.handlers:
    handler.addFilter(CorrelationIdFilter())

配置完成后，不管是框架本身的系统日志、路由层的访问日志、还是业务代码的埋点日志，都会自动携带当前请求的Correlation ID，无需在每处打日志时手动传参。

2. 注册请求钩子实现全生命周期ID处理 #

使用Flask原生的before_request/after_request钩子，对应Java生态的HandlerInterceptor能力，完成ID的读取、生成、响应注入全流程：

import uuid
from flask import Flask, request

app = Flask(__name__)
# 自定义Correlation ID对应的请求头名称，可根据业务需求随意修改，无硬编码限制
CORRELATION_ID_HEADER = "X-Custom-Trace-Id"

@app.before_request
def resolve_correlation_id():
    # 优先读取请求头中传入的自定义Correlation ID
    incoming_correlation_id = request.headers.get(CORRELATION_ID_HEADER)
    # 若请求未携带ID，自动生成符合UUID规范的唯一标识
    g.correlation_id = incoming_correlation_id if incoming_correlation_id else str(uuid.uuid4())

@app.after_request
def inject_correlation_id(response):
    # 将最终使用的Correlation ID注入响应头，返回给调用方
    response.headers[CORRELATION_ID_HEADER] = g.correlation_id
    return response

3. 路由维度的日志埋点 #

因为全局日志已经自动透传Correlation ID，所有路由内的日志都会天然关联对应链路，无需重复编写埋点逻辑。示例路由代码：

@app.route("/api/order/create")
def create_order():
    app.logger.info("开始处理订单创建请求")
    # 业务逻辑处理
    app.logger.info("订单创建完成")
    return {"code": 0, "message": "success"}

注意事项 #

• 异步场景适配：如果使用Flask 2.0+的异步路由能力，需要将原基于g对象的上下文存储替换为contextvars模块的协程隔离上下文变量，避免多协程并发下的ID串号问题。
• 跨服务透传：调用下游服务时，只需将当前上下文的Correlation ID添加到出站请求的对应请求头中，即可和Java、Express生态的链路追踪体系兼容打通。
• 检索能力：所有日志统一携带Correlation ID字段后，可直接在日志检索系统中按该字段筛选，拉取单个请求全生命周期的所有日志，实现全链路追踪能力。

内容的提问来源于stack exchange，提问作者ChamaraL