Nginx 实现链路可观测性的关键是 traceparent 全链路透传与统一 OTLP 导出，需启用 ngx_otel_module（≥v0.1.2），配置 otel_trace_context propagate，并确保后端与缓存层协同解析 W3C trace context。
要让 Nginx 在网关、缓存与后端之间形成完整的链路可观测性，关键不是只装一个模块，而是让请求上下文（traceparent）贯穿整个调用路径，并确保各环节使用统一的 OpenTelemetry 协议导出数据。Nginx 本身不生成业务逻辑追踪，但它必须正确传播和透传追踪头，同时自身行为（如代理耗时、缓存命中、重写规则）也要被采集。
确认 Nginx 版本与模块支持
Nginx 官方原生 ngx_otel_module（≥ v0.1.2）是当前最稳妥的选择，它支持 W3C trace context 传播、OTLP/gRPC 导出，且无需修改源码编译。OpenResty 或旧版 Nginx 若未内置该模块，需自行构建或使用预编译包（如 Alibaba Cloud Linux 的 nginx-module-otel）。注意：社区早期模块仅支持 gRPC 上报，不支持 HTTP/JSON 导出，配置前务必核对版本说明。
在 Nginx 中启用并配置 OTel 模块
在 /etc/nginx/nginx.conf 主配置中添加以下内容：
- 加载模块：
load_module modules/ngx_otel_module.so; - 全局启用追踪与上下文注入：
http {<br> otel_exporter {<br> endpoint "https://otlp.example.com:4317"; # gRPC 接入点<br> header Authentication "Bearer xxxxxxxx"; # 鉴权 Token<br> }<br> otel_trace on;<br> otel_service_name "nginx-gateway";<br> otel_trace_context propagate; # 向 upstream 注入 traceparent<br> } - 若只对特定路径启用（如 API 网关流量），可将
otel_trace on移至location块内，避免对静态资源等冗余采样。
确保后端与缓存层协同透传
Nginx 的可观测性只有在上下游配合下才完整：
-
后端服务：必须使用 OpenTelemetry SDK（如 Java Agent、Python auto-instrumentation），并启用 W3C trace context 解析。收到 Nginx 转发的
traceparent头后，自动延续 span，而非新建 trace。 -
缓存层（如 Redis、Memcached）：若 Nginx 使用
proxy_cache，其命中/未命中状态不会自动打点。可通过log_format记录$upstream_cache_status，再由日志采集器（如 Fluent Bit + OTel Collector）解析为 span attribute；更优方式是让后端在响应中返回缓存标识（如X-Cache: HIT），由后端 SDK 将其作为 span 属性上报。 -
反向代理链路：若存在多级 Nginx（如边缘 Nginx → 内网 Nginx），每层都需配置
otel_trace_context propagate，并确保proxy_pass不删除或覆盖原始 trace headers。
验证与调试要点
部署后需快速确认链路是否真正贯通：
- 发起一次请求，检查响应头是否含
traceparent（格式为00-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx-xxxxxxxxxxxxxxxx-01）； - 在 Jaeger 或可观测平台中搜索该 trace ID，应能看到至少三个 span：Nginx 接收请求、Nginx 转发请求、后端处理请求；
- 检查 Nginx span 的 attributes 是否包含关键字段：
http.method、http.route、http.status_code、net.peer.name（上游地址）、upstream_cache_status（若已集成）； - 若 trace 断在 Nginx 后就消失，大概率是后端未启用 OTel 自动插桩，或禁用了 W3C header 解析。
