`ngx_otel_module` NGINX OpenTelemetry 分布式追踪实战-EW帮帮网

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 验证 CA
        header      "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.name
    otel_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;               # 强制注入/覆盖 traceparent

    proxy_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，让你的服务从“黑盒”变“白盒”，为性能调优和故障分析提供可靠的追踪数据！

`ngx_otel_module` NGINX OpenTelemetry 分布式追踪实战