怎么通过 Nginx 日志追踪全链路请求 ID-Nginx-PHP中文网

核心是用$request_id作为唯一标识，从nginx入口自动生成32位十六进制id（需≥1.11.0），通过proxy_set_header x-request-id $request_id透传至后端，并在log_format中显式记录，配合各服务统一读取、复用和日志落盘，最终实现全链路日志聚合检索。

怎么通过 nginx 日志追踪全链路请求 id

核心是用 $request_id 作为唯一标识，从 Nginx 入口开始生成、透传、记录，并在所有下游服务中复用该 ID，最终通过日志平台按 ID 聚合检索。

确保 Nginx 正确生成并记录 $request_id

Nginx 1.11.0 及以上版本原生支持 $request_id，每次请求自动产生一个 32 位小写十六进制字符串。不需要额外模块或 Lua 脚本。

在 http 块中定义日志格式，显式包含 $request_id，例如：
log_format main '$request_id - $remote_addr [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent"';
在 server 或 location 块中启用该格式：
access_log /var/log/nginx/access.log main;
避免使用 $http_x_request_id 替代 —— 它来自客户端，可能为空、被篡改或格式不一致。

把 request_id 透传到后端服务

ID 必须随请求一起发给下游，且不能被覆盖或丢弃。

Nginx Config Linter

对 Nginx 配置文件进行语法检查、验证和安全、性能审计。

下载

在 location 块内、紧邻 proxy_pass 的位置添加：
proxy_set_header X-Request-ID $request_id;
如果上游（如网关）已带 X-Request-ID，应优先复用，避免重复生成：
用 map 提取并兜底：
map $http_x_request_id $forwarded_id { "" $request_id; default $http_x_request_id; }
再写 proxy_set_header X-Request-ID $forwarded_id;
确认后端服务（Spring Boot/Go/Node.js 等）实际读取了该 header，并注入日志上下文（如 MDC、Zap 字段、Winston metadata），而不是自行生成新 ID。

验证透传是否生效

链路是否完整，靠验证，不是靠配置完就默认成功。

用 curl -I http://your-domain/api 查看响应头，确认返回了 X-Request-ID，且值与 Nginx access.log 中对应行的 $request_id 完全一致。
检查 Nginx 错误日志是否有 upstream sent too big header 类报错——可能是透传 header 导致响应头超长，需调大 large_client_header_buffers。
若自定义 header 含下划线（如 X-Request-ID），务必在 http 块开头加：
underscores_in_headers on;，否则 Nginx 默认忽略。