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，讓你的服務從“黑盒”變“白盒”，為性能調優和故障分析提供可靠的追蹤數據！
)
