Nginx 本身不生成标准 OpenTracing/OpenTelemetry 格式的 trace span，但它作为反向代理处于请求入口，是链路追踪“染色”的关键起点。实现负载均衡层面的分布式链路追踪染色，核心不是让 Nginx 发送 span，而是稳定生成、透传并关联请求标识，使下游服务能延续同一链路上下文。重点在标识一致性、透传可靠性与日志可观测性。
确保 $request_id 稳定可用并纳入日志
$request_id 是 Nginx 内置变量（1.11.0+ 默认启用），每次请求生成唯一 UUIDv4 字符串（如 `a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8`），生命周期覆盖主请求、子请求与重试，适合作为链路锚点。 - 检查 Nginx 版本：运行 `nginx -v`，确保 ≥ 1.11.0；旧版本需升级或谨慎使用 map + random 模拟（不推荐） - 在 log_format 中显式包含它，形成第一环“染色日志”：
log_format main '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" $request_id $upstream_http_x_request_id';
access_log /var/log/nginx/access.log main;
这样每条 access 日志都带原始 request_id 和下游返回的 x-request-id（便于比对是否被覆盖）
通过 proxy_set_header 透传至后端服务
仅记录不够，必须让业务服务拿到并复用该 ID，否则链路断裂。 - 在 proxy_pass 前添加透传头：
proxy_set_header X-Request-ID $request_id;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
- 若后端已集成 OpenTelemetry 或 Sleuth，它们会自动读取 `X-Request-ID` 并作为 trace 上下文源头（需关闭其自动生成逻辑，例如 Spring Cloud Sleuth 设置 `sleuth.propagation.type=B3` 并配置 fallback） - 避免在 Nginx 层重复生成新 ID；所有中间层（网关、Sidecar）应优先信任上游透传的 `X-Request-ID`
与负载均衡策略联动做灰度染色路由
在负载均衡转发时，可基于 $request_id 衍生灰度分组，实现“同 ID 同路径”，保障链路连续性。 - 利用 map 指令哈希 request_id 前几位决定上游集群：
map $request_id $upstream_group {
default "prod";
~^(?
}
map $upstream_group $route_to {
default "backend-prod";
~^[0-4][0-9]{3}$ "backend-gray";
}
- 在 location 中使用变量路由，并透传染色信息：
proxy_pass http://$route_to;
proxy_set_header X-Trace-Group $route_to;
proxy_set_header X-Request-ID $request_id;
这样灰度请求不仅走指定 upstream，其日志和 trace 中也携带分组标签，便于全链路聚合分析
补充：让 Nginx 出现在 APM 链路图中（可选）
默认 Nginx 不上报 span，若需它在 Jaeger/SkyWalking 等系统中显示为一个节点，需借助扩展模块： - 使用官方 Nginx OTel 模块（≥0.1.2）：支持 gRPC 上报 span，需配置 endpoint 和鉴权 Token，并开启 `otel_trace on` - 注意限制：仅支持 gRPC 上报，不支持 HTTP；旧版本需配合 OpenTelemetry Collector 中转 - 启用后，Nginx 会生成自己的 span，并通过 `otel_trace_context propagate` 自动注入 `traceparent` 头给下游，真正实现端到端 span 链接
不复杂但容易忽略。关键是把 $request_id 当作“链路身份证”，从入口开始稳稳握住，再一层层交下去。
