当中转站响应头不出现 X-Request-ID 时,多数情况下不是链路断了,而是链路ID从上游到中转站的传递路径上被丢弃了,或中转站根本没有参与生成。要让上游与本地日志能串起来,关键要定两件事:由谁生成链路ID,以及通过哪个请求头把 ID 从入口带到上游。建议先不要直接补响应头,而是先做一次带请求头的探测,确认 ID 断在哪一层。
先定位链路ID断在哪一层
用 curl -v 分别请求上游和中转站,比较两个响应的 HTTP 头。如果上游响应里有 X-Request-ID,而中转站响应里没有,问题在中转站的响应头透传配置;如果上游响应里也没有,说明上游或更前一层没有生成链路ID。
同时检查上游的访问日志,看上游收到的请求里是否包含 X-Request-ID。如果上游日志里没有该头,说明中转站发往上游的请求里也没带这个 ID,即使上游本来会生成,也不会影响它的返回。
- 适用场景:任何通过中转站转发请求的前后端链路。
- 操作动作:用同一测试请求分别 curl 上游和中转站,记录请求头与响应头。
- 验证方式:对比两端响应头里 X-Request-ID 的存在性。
- 风险边界:上游可能是动态生成且不固定,所以只比较是否存在,不比较值是否一致。
分支A:上游有ID,但中转站没有透传
这类情况的特点是:上游已经返回 X-Request-ID,但客户端收到的响应头里没有。原因一般出在中转站的响应头透传配置——有些网关会默认剥离未知头,有些则因为配置了 add_header 而覆盖了同名头。这时不需要改上游,只需要在中转站把上游的 X-Request-ID 复制到响应头。
以 Nginx 为例,在 location 块中显式从上游响应取值:
add_header X-Request-ID $upstream_http_x_request_id;这条指令表示将上游响应中 x-request-id 的值写入当前响应头。注意 add_header 在非 200/201 等状态码下不生效,可能需要补 always 参数,例如 add_header X-Request-ID $upstream_http_x_request_id always。
- 适用场景:上游有生成链路ID,但中转站没把该响应头暴露给下游。
- 操作动作:在中转站配置里显式透传或复制该响应头。
- 验证方式:重新 curl 中转站,响应头里应出现 X-Request-ID,且值等于上游返回的值。
- 风险边界:如果中转站还配置了其它 add_header,需确认不会重复声明同名头;建议在统一配置处管理响应头。
分支B:上游没有生成链路ID
如果上游响应本身不带 X-Request-ID,就不能依赖上游。此时由中转站作为链路入口生成一个 ID,并向上游放在请求头里,向客户端放在响应头里。这样本地日志和上游日志就能通过同一个请求头值关联起来。
以 Nginx 为例,在 location 块里设置:
proxy_set_header X-Request-ID $request_id;
add_header X-Request-ID $request_id always;这里 $request_id 是 Nginx 内置变量,每个请求会生成一个不重复的 ID。第一行让上游收到这个 ID,第二行让客户端从响应头拿到。如果你的中转站是自研服务,则在入口生成 UUID,放入请求上下文,并在转发时写到 X-Request-ID 请求头,完成业务处理后也写到响应头。
- 适用场景:上游从不提供链路ID,且无法修改上游代码。
- 操作动作:在中转站入口生成 ID,同时写入请求头和响应头。
- 验证方式:请求上游的日志里能看到 X-Request-ID 字段,客户端响应头里也有同样内容。
- 风险边界:由中转站生成的 ID 不能和上游内部链路追踪 ID 混用,除非上游统一采用该请求头作为追踪上下文。
分支C:本地日志没记录这个ID
即使响应头有 ID,如果中转站本地 access log 里没有记录,仍然无法和上游日志对上。这时需要把同一个链路ID写进日志。Nginx 可以在 log_format 中定义字段:
log_format trace '$remote_addr - $request_id - $upstream_response_time';
access_log /var/log/nginx/access.log trace;注意这里使用的是 $request_id,而不是 $http_x_request_id。$http_x_request_id 只读客户端请求头里的值;如果客户端没传,它就为空。而 $request_id 是 Nginx 在这个请求生命周期内固定的值,即使客户端没传也会生成。如果中转站需要记录的是上游生成的 ID,则日志字段应改为 $upstream_http_x_request_id,这样在分支A和分支B下需要区分来源。
- 适用场景:本地日志中没有与上游一致的关联字段。
- 操作动作:修改 log_format,增加 $request_id 或你自定义的变量,同时确认 access_log 使用了这个格式。
- 验证方式:重新请求后,查看 access log 新增字段与响应头 X-Request-ID 是否一致。
- 风险边界:如果上游已经生成了 ID 并需要记录,那么本地日志应记录 $upstream_http_x_request_id,而不是 $request_id,两者是不同来源。
验证信号:让一次请求在三处看到同一ID
完成上述动作后,用同一个测试请求验证三处:客户端收到的响应头、中转站 access log、上游业务日志。三个位置的 X-Request-ID 值应当一致,或至少能通过一个 ID 关联。如果上游日志不包含该头,说明上游没有读取这个请求头,需要在上游日志配置里增加对该头的输出。
如果客户端并不需要这个响应头,只做日志关联,可以不添加响应头,仅保留请求头传递和本地日志。但考虑到前端排查问题需要,通常建议保留响应头。最后保留一个自查清单:
- 上游是否返回 X-Request-ID?
- 中转站是否将请求头 X-Request-ID 传给上游?
- 中转站是否将响应头 X-Request-ID 返回给客户端?
- 中转站本地日志是否记录了同名的链路ID?
- 上游日志是否读取了该请求头并原文输出?