1. 模块简介
ngx_otel_module 为 NGINX（开源版 1.25.3+，商业版 1.23.4+）提供了 OpenTelemetry（OTel）分布式追踪支持，能够：
- 自动采集 HTTP 请求的生命周期 Span
- 上下文传播：兼容 W3C
traceparent/tracestate - OTLP/gRPC 导出：将 Span 批量上传到 OTel Collector 或云端后端
模块的源码和安装说明见官方仓库（GitHub: nginx-module-otel）。
2. 安装与加载
2.1 开源版预构建包
# Debian/Ubuntu
apt-get install nginx-module-otel
# 或者在源码编译时
./configure \--add-dynamic-module=path/to/ngx_otel_module \[其他选项…]
make && make install
2.2 商业版（NGINX Plus）
# 已包含 MODULE
# 只需在 nginx.conf 中 load_module 即可
load_module modules/ngx_otel_module.so;
3. 核心指令详解
全部指令 仅在 http（或 server、location）上下文有效。
3.1 OTel 导出器配置
http {otel_exporter {endpoint localhost:4317; # OTLP/gRPC 端点trusted_certificate /etc/ssl/ca.pem; # TLS 验证 CAheader "X-API-Token" "token"; # 自定义请求头interval 5s; # 最大发送间隔（默认 5s）batch_size 512; # 最大 Span 批量大小batch_count 4; # 最大并发批次数}
}
- TLS 支持：
(http|https)://+trusted_certificate - 请求头：用于上传鉴权
- 批量控制：调节吞吐与资源消耗平衡
3.2 服务与资源属性
http {otel_service_name my-nginx-service; # resource.service.nameotel_resource_attr deployment "blue"; # 自定义 resource 属性
}
otel_service_name：设置service.name（默认unknown_service:nginx）otel_resource_attr：任意 key/value，标注部署信息、环境等
3.3 启用追踪与上下文传播
server {listen 8080;otel_trace on; # 开启追踪otel_trace_context inject; # 强制注入/覆盖 traceparentproxy_pass http://backend;
}
-
otel_trace：可用变量控制，如基于split_clients动态采样 -
otel_trace_context：extract：仅提取外部上下文inject：强制为下游请求注入新的或覆盖已有上下文propagate：提取并更新ignore：不处理
3.4 自定义 Span 名称与属性
location /api/ {otel_span_name "API $uri"; # 自定义 Span 名称otel_span_attr user_id $cookie_uid; # 添加自定义 Span 属性otel_span_attr debug "true";
}
- 默认 Span 名称为 NGINX
location - 支持变量，结合自定义逻辑埋点
4. 默认 Span 属性 & 内置变量
模块自动为每个 HTTP 请求 Span 设置一系列标准属性：
http.method
http.target
http.route
http.scheme
http.flavor
http.user_agent
http.request_content_length
http.response_content_length
http.status_code
net.host.name
net.host.port
net.sock.peer.addr
net.sock.peer.port
同时提供以下内置变量，可用于自定义属性或采样逻辑：
| 变量 | 含义 |
|---|---|
$otel_trace_id | Trace 标识符，如 56552bc4daa3bf39... |
$otel_span_id | 当前 Span ID，如 4c0b8531ec38ca59 |
$otel_parent_id | 父 Span ID |
$otel_parent_sampled | 父 Span 的 Sampled 标志（1 或 0） |
5. 动态采样示例
结合 split_clients 模块，实现比例采样：
# 按 trace_id 哈希 10% 流量采样
split_clients "$otel_trace_id" $ratio_sampler {10% on;* off;
}server {otel_trace $ratio_sampler; # 动态开关otel_trace_context propagate;proxy_pass http://backend;
}
6. 性能与最佳实践
-
批量与间隔：
batch_size与interval配合，需根据流量规模和后端吞吐调优。
-
上下文传播模式：
inject覆盖性最强，适用于关闭无痕迹客户端；extract用于被动接入已有追踪链；
-
自定义资源属性：
- 在多租户或多环境部署中，务必设置
otel_resource_attr标注环境或版本。
- 在多租户或多环境部署中，务必设置
-
监控 OTel Agent：
- 定期检查 Collector 或后端的遥测接收指标，避免上报端点故障导致数据丢失。
7. 总结
ngx_otel_module 通过零侵入的方式，将 OpenTelemetry 分布式追踪能力无缝集成到 NGINX 中。
- 自动化 Span：从入口到代理，全链路捕获 HTTP 请求细节。
- 灵活控制：支持自定义 Span 名称、属性、采样策略。
- 标准导出：兼容 OTLP/gRPC，方便对接主流监控与 APM 工具。
立即启用：在你的 NGINX 配置中引入 ngx_otel_module，让你的服务从“黑盒”变“白盒”，为性能调优和故障分析提供可靠的追踪数据！
)
