Nginx记录TraceID需上游通过Header（如X-Trace-ID）透传，配置log_format使用$http_x_trace_id变量，并确保Header未被过滤；后端需统一读取、生成及透传TraceID，结合MDC与日志系统实现全链路追踪。
要在 Nginx 日志中记录请求的 TraceID 实现全链路追踪，核心是：让上游服务（如网关或应用）把 TraceID 通过 HTTP Header 传给 Nginx，Nginx 再在日志格式中提取并输出该字段。Nginx 本身不生成 TraceID，只做透传和记录。
确保 TraceID 通过 Header 传入 Nginx
TraceID 通常由前端网关（如 Spring Cloud Gateway、Envoy）或客户端注入，以标准 Header 形式传递，常见名称有：
- X-Trace-ID
- trace-id
- uber-trace-id（Jaeger）
- ot-tracer-traceid（OpenTracing）
你需要和上下游团队对齐使用的 Header 名称，并确认该 Header 没被 Nginx 默认丢弃（默认不会丢，但若用了 underscores_in_headers on 或自定义 proxy_pass 配置，需留意）。
在 log_format 中定义 TraceID 变量
Nginx 使用 $http_XXX 变量读取请求 Header，其中 XXX 是 Header 名转为小写并用下划线替代短横线。例如：
- Header X-Trace-ID → 变量 $http_x_trace_id
- Header trace-id → 变量 $http_trace_id
在 http 块中定义带 TraceID 的日志格式：
log_format main '$remote_addr - $remote_user [$time_local] '
'"$request" $status $body_bytes_sent '
'"$http_referer" "$http_user_agent" '
'$http_x_trace_id; # ← 追加这一项如果希望空 TraceID 显示为 "-"，可用 $http_x_trace_id 的默认值语法（需 Nginx ≥ 1.11.8）：
'${http_x_trace_id:-"-"}验证 Header 是否能被正确捕获
有时 Header 因大小写、代理设置或安全模块被过滤，可临时加一条日志或用 map 检查：
map $http_x_trace_id $trace_id_log {
"" "-"; # 空值
default $http_x_trace_id;
}
log_format main ... '$trace_id_log';同时建议用 curl 手动测试是否透传成功：
curl -H "X-Trace-ID: abc123" http://your-nginx-host/
再查看 access.log，确认 abc123 出现在对应行末尾。
配合后端统一 TraceID 生成逻辑
仅记录不够，要真正实现全链路追踪，还需：
- 后端应用在收到请求时，优先从 X-Trace-ID 读取；不存在则自动生成并向下透传
- 所有中间件（Redis 客户端、HTTP 调用、消息队列 Producer）都携带该 ID 打点
- 日志框架（如 Logback、Log4j2）配置 MDC 将 TraceID 注入每条日志
- 集中日志系统（ELK / Loki）按 TraceID 字段聚合，实现跨服务串联
