otel: NGINX OpenTelemetry 动态模块

安装

您可以在任何基于 RHEL 的发行版中安装此模块，包括但不限于：

RedHat Enterprise Linux 7、8、9 和 10
CentOS 7、8、9
AlmaLinux 8、9
Rocky Linux 8、9
Amazon Linux 2 和 Amazon Linux 2023

CentOS/RHEL 8+、Fedora Linux、Amazon Linux 2023+CentOS/RHEL 7 和 Amazon Linux 2

dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-otel

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install nginx-module-otel

通过在 /etc/nginx/nginx.conf 顶部添加以下内容来启用模块：

load_module modules/ngx_otel_module.so;

本文档描述了 nginx-module-otel v0.1.2，于 2025 年 3 月 15 日发布。

什么是 OpenTelemetry

OpenTelemetry (OTel) 是一个用于监控、追踪、故障排除和优化应用程序的可观察性框架。OTel 使得可以从已部署的应用程序堆栈中收集遥测数据。

什么是 NGINX 原生 OTel 模块

ngx_otel_module 动态模块使 NGINX Open Source 或 NGINX Plus 能够将遥测数据发送到 OTel 收集器。它支持 W3C trace context 传播、OpenTelemetry 协议 (OTLP)/gRPC 追踪导出，并提供了相较于现有 OTel 模块的几个优势，包括：

更好的性能

第三方 OTel 实现启用追踪时会将请求处理性能降低多达 50%。NGINX 原生模块将此影响限制在大约 10-15% 之间。

轻松配置

设置和配置可以直接在 NGINX 配置文件中完成。

动态、基于变量的控制

能够使用 cookies、tokens 和变量动态控制追踪参数。有关更多详细信息，请参见我们的基于比例的追踪示例。

此外，作为商业订阅的一部分， NGINX Plus 通过 NGINX Plus API 和键值存储模块启用对采样参数的动态控制。

启用 OTel 模块

按照上述安装步骤，模块将默认安装到 /etc/nginx/modules 中。通过在主 NGINX 配置文件（位于 /etc/nginx/nginx.conf）的顶部添加以下行来加载模块。

load_module modules/ngx_otel_module.so;

配置模块

有关指令、嵌入变量、默认跨度属性和示例配置的完整列表，请参阅 ngx_otel_module 文档。

示例

使用这些示例配置 OTel 追踪的一些常见用例。

简单追踪

此示例为所有 http 请求发送遥测数据。

http {
    otel_exporter {
        endpoint localhost:4317;
    }

    otel_trace on;

    server {
        location / {
            proxy_pass http://backend;
        }
    }
}

基于父级的追踪

在此示例中，我们从传入请求中继承追踪上下文，仅在父级跨度被采样时记录跨度。我们还将追踪上下文和采样决策传播到上游服务器。

http {
    server {
        location / {
            otel_trace $otel_parent_sampled;
            otel_trace_context propagate;

            proxy_pass http://backend;
        }
    }
}

基于比例的追踪

在此基于比例的示例中，追踪被配置为一定比例的流量（在此情况下为 10%）：

http {
    # 追踪 10% 的请求
    split_clients $otel_trace_id $ratio_sampler {
        10%     on;
        *       off;
    }

    # 或者我们可以追踪 10% 的用户会话
    split_clients $cookie_sessionid $session_sampler {
        10%     on;
        *       off;
    }

    server {
        location / {
            otel_trace $ratio_sampler;
            otel_trace_context inject;

            proxy_pass http://backend;
        }
    }
}

收集和查看追踪

有几种方法和可用软件包可以查看追踪。为了快速入门，Jaeger 提供了一个一体化容器，用于收集、处理和查看 OTel 追踪数据。请按照这些步骤下载、安装、启动和使用 Jaeger 的 OTel 服务。

更新日志

请查看我们的发布页面以跟踪更新。

GitHub

您可以在 nginx-module-otel 的 GitHub 仓库中找到此模块的其他配置提示和文档。