Web 服务器与网关 / 系统课时

传递请求追踪标识

传递请求追踪标识

本课学习如何在 Nginx 网关层生成、复用并传递请求追踪标识,使客户端请求能够与后端服务日志建立关联。完成配置后,可以通过一个 ID 快速检索同一次请求经过的完整链路。

学习目标

  • 理解请求追踪标识在网关中的作用。
  • 配置 Nginx 生成或转发请求 ID。
  • 将请求 ID 同时写入上游请求、响应头和访问日志。

认识请求追踪标识流程

在微服务架构中,一个请求可能经过网关、多个业务服务和数据库访问层。如果每个组件只记录自己的日志,很难确认这些日志是否属于同一次请求。

请求追踪标识通常由入口网关创建。如果客户端已经提供合法标识,网关可以复用;如果没有,则生成新的唯一值,并通过请求头传递给后端。

请求追踪标识在网关和服务之间传递的流程图

配置请求 ID 传递

Nginx 可以使用 $request_id 变量生成唯一请求标识,并通过 proxy_set_header 传递给上游。

nginx
http {
    log_format trace '$request_id $remote_addr $request_uri';

    server {
        listen <PORT>;

        location /api/ {
            proxy_set_header X-Request-ID $request_id;
            add_header X-Request-ID $request_id always;
            proxy_pass http://backend;
        }
    }
}

预期结果

text
客户端响应头:
X-Request-ID: 7f2c8d4e8a9b

上游请求头:
X-Request-ID: 7f2c8d4e8a9b

实际生成的 ID 会随请求变化,示例值仅用于说明传递关系。

复用客户端已有标识

部分系统由前端、API 网关或链路追踪组件提前生成 ID。此时需要避免无条件覆盖已有值,可以使用 map 判断是否存在请求头。

nginx
http {
    map $http_x_request_id $trace_id {
        default $http_x_request_id;
        "" $request_id;
    }

    server {
        location / {
            proxy_set_header X-Request-ID $trace_id;
        }
    }
}

预期结果

text
已有请求头:
X-Request-ID: client-id-001

转发结果:
X-Request-ID: client-id-001

没有请求头时,Nginx 会使用自身生成的请求标识。

验证追踪链路

验证时应同时检查客户端响应、Nginx 访问日志和上游服务日志,确认同一个 ID 在多个位置保持一致。

bash
curl -i http://example.com/api/test

预期结果

text
HTTP/1.1 200 OK
X-Request-ID: 7f2c8d4e8a9b

如果响应没有返回标识,应检查 add_header 是否配置在正确上下文,以及请求是否经过目标 location。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

传递请求追踪标识

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通