中转站响应头缺少x-request-id时如何用链路ID串联上游与本地日志

文章导读
当中转站响应头不出现 X-Request-ID 时,多数情况下不是链路断了,而是链路ID从上游到中转站的传递路径上被丢弃了,或中转站根本没有参与生成。要让上游与本地日志能串起来,关键要定两件事:由谁生成链路ID,以及通过哪个请求头把 ID 从入口带到上游。建议先不要直接补响应头,而是先做一次带请求头的探测,确认 ID 断在哪一层。
📋 目录
  1. A 先定位链路ID断在哪一层
  2. B 分支A:上游有ID,但中转站没有透传
  3. C 分支B:上游没有生成链路ID
  4. D 分支C:本地日志没记录这个ID
  5. E 验证信号:让一次请求在三处看到同一ID
A A

当中转站响应头不出现 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,并向上游放在请求头里,向客户端放在响应头里。这样本地日志和上游日志就能通过同一个请求头值关联起来。

中转站响应头缺少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 关联。如果上游日志不包含该头,说明上游没有读取这个请求头,需要在上游日志配置里增加对该头的输出。

如果客户端并不需要这个响应头,只做日志关联,可以不添加响应头,仅保留请求头传递和本地日志。但考虑到前端排查问题需要,通常建议保留响应头。最后保留一个自查清单:

  1. 上游是否返回 X-Request-ID?
  2. 中转站是否将请求头 X-Request-ID 传给上游?
  3. 中转站是否将响应头 X-Request-ID 返回给客户端?
  4. 中转站本地日志是否记录了同名的链路ID?
  5. 上游日志是否读取了该请求头并原文输出?