基于Nginx+FastAPI的服务器请求追踪最佳实践咨询

一、请求唯一ID（最简便通用的方案） #

你提出的UUID放入请求头的思路完全可行，这也是中小型服务最常用的追踪方式，足够应对月100万请求的规模——UUID的重复概率极低，完全可以忽略。具体落地分两步：

1. Nginx层生成并传递请求ID #

在Nginx配置中给每个请求生成唯一标识，既可以直接用Nginx原生的$request_id（16字节随机字符串，唯一性足够），也可以生成UUIDv4，同时把这个ID注入请求头传递给后端，还能写入Nginx访问日志方便关联排查：

http {
    log_format main '$remote_addr - $remote_user [$time_local] "$request" '
                    '$status $body_bytes_sent "$http_referer" '
                    '"$http_user_agent" "$request_id"';

    server {
        listen 80;
        location / {
            # 将Nginx原生request_id作为追踪ID传给FastAPI
            proxy_set_header X-Trace-ID $request_id;
            proxy_pass http://your-fastapi-upstream;
        }
    }
}

如果偏好UUID格式，可安装nginx-module-uuid4模块，用$uuid4替代$request_id即可。

2. FastAPI层接收并传递请求ID #

通过FastAPI的依赖项获取请求头里的X-Trace-ID，然后在所有需要打日志的函数（A/B/C）中带上这个ID。可以通过日志格式化自动注入，避免手动传递的冗余：

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

app = FastAPI()
trace_id_var = ContextVar("trace_id", default="unknown-trace-id")

# 配置日志格式，强制包含trace_id
class TraceIdFilter(logging.Filter):
    def filter(self, record):
        record.trace_id = trace_id_var.get()
        return True

logger = logging.getLogger(__name__)
logger.addFilter(TraceIdFilter())
logging.basicConfig(
    format='%(asctime)s - %(levelname)s - %(trace_id)s - %(message)s',
    level=logging.INFO
)

# 定义依赖项，获取并设置trace_id到上下文
def get_trace_id(request: Request):
    trace_id = request.headers.get("X-Trace-ID", "unknown-trace-id")
    trace_id_var.set(trace_id)
    return trace_id

@app.get("/")
async def root(trace_id: str = Depends(get_trace_id)):
    logger.info("开始执行请求处理流程")
    func_a()
    func_b()
    func_c()
    return {"message": "处理完成"}

def func_a():
    logger.info("Func A执行完成")

def func_b():
    logger.info("Func B执行完成")

def func_c():
    logger.info("Func C执行完成")

用ContextVar存储trace_id，结合日志过滤器，所有函数的日志都会自动带上当前请求的追踪ID，不用手动传递参数。

二、轻量分布式追踪（可选，适配未来扩展） #

如果后续服务可能拆分，现在可以提前用轻量方案铺垫，比如OpenTelemetry——它能自动生成trace_id和span_id，不仅能追踪单请求的函数调用链，还能无缝扩展到多服务场景。

FastAPI集成OpenTelemetry的极简示例：

from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor, ConsoleSpanExporter
from fastapi import FastAPI

# 初始化追踪器
trace.set_tracer_provider(TracerProvider())
tracer = trace.get_tracer(__name__)
trace.get_tracer_provider().add_span_processor(
    BatchSpanProcessor(ConsoleSpanExporter())
)

app = FastAPI()

@app.get("/")
async def root():
    with tracer.start_as_current_span("请求主流程"):
        with tracer.start_as_current_span("执行Func A"):
            func_a()
        with tracer.start_as_current_span("执行Func B"):
            func_b()
        with tracer.start_as_current_span("执行Func C"):
            func_c()
    return {"message": "处理完成"}

def func_a():
    with trace.get_tracer(__name__).start_as_current_span("Func A内部逻辑"):
        # 业务代码
        pass

# Func B、Func C写法类似

这种方式不需要手动管理trace_id，OpenTelemetry会自动生成并关联调用链路，后续还能导出到Jaeger、Grafana Loki等工具做可视化分析。

三、实用补充技巧 #

• 若客户端自身携带了请求标识（比如移动端的请求ID），优先使用客户端ID，无标识时再生成服务端ID，方便客户端直接排查问题。
• 日志中可额外加入用户ID、请求路径、HTTP方法等字段，缩小问题定位范围。
• 月100万请求的日志量不大，用Loki+Grafana或ELK做日志聚合，可快速通过trace_id搜索整个请求的完整日志链路。

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