模块 ngx_otel_module

ngx_otel_module 模块提供 OpenTelemetry 分布式追踪支持。该模块支持 W3C 上下文传播和 OTLP/gRPC 导出协议。

模块的源代码可在此处获取：此处。下载和安装说明可在此处获取：此处。

自 1.25.3 版本起，该模块也提供预构建的 nginx-module-otel 包；作为我们 商业订阅 的一部分，自 1.23.4 版本起，该模块也提供 nginx-plus-module-otel 包。

load_module modules/ngx_otel_module.so;

events {
}

http {

    otel_exporter {
        endpoint localhost:4317;
    }

    server {
        listen 127.0.0.1:8080;

        location / {
            otel_trace         on;
            otel_trace_context inject;

            proxy_pass http://backend;
        }
    }
}

指定 OTel 数据导出参数

endpoint [(http|https)://]host:port;

接受遥测数据的 OTLP/gRPC 端点。自 0.1.2 版本起支持 TLS。

trusted_certificate path;

用于验证 TLS 端点的 PEM 格式 CA 证书文件（自 0.1.2 版本起）。默认为操作系统提供的 CA 捆绑包。

header name value;

添加到遥测导出请求的自定义 HTTP 头部（自 0.1.2 版本起）。

interval time;

两次导出之间的最大间隔，默认为 5 秒。

batch_size number;

每个 worker 在一个批次中发送的 Span 的最大数量，默认为 512。

batch_count number;

每个 worker 待处理批次的数量，超过限制的 Span 将被丢弃，默认为 4。

示例

otel_exporter {
    endpoint https://otel-example.nginx.com:4317;

    header X-API-Token "my-token-value";
}

otel_service_name unknown_service:nginx;

设置 OTel 资源的 "service.name" 属性。

设置自定义 OTel 资源属性。

otel_trace off;

启用或禁用 OpenTelemetry 追踪。也可以通过指定变量来启用此指令。

split_clients "$otel_trace_id" $ratio_sampler {
              10%              on;
              *                off;
}

server {
    location / {
        otel_trace         $ratio_sampler;
        otel_trace_context inject;
        proxy_pass         http://backend;
    }
}

otel_trace_context ignore;

指定如何传播 traceparent/tracestate 头部

extract

使用请求中现有的追踪上下文，以便 追踪 的标识符和 父 Span 的标识符继承自入站请求。

inject

添加一个新的上下文到请求中，如果存在现有头部，则覆盖它们。

propagate

更新现有上下文（结合了 extract 和 inject）。

ignore

跳过上下文头部处理。

定义 OTel Span 的名称。默认情况下，它是请求的 location 名称。该名称可以包含变量。

添加一个自定义 OTel Span 属性。该值可以包含变量。

以下 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

当前 Span 所属的追踪的标识符，例如 56552bc4daa3bf39c08362527e1dd6c4

$otel_span_id

当前 Span 的标识符，例如 4c0b8531ec38ca59

$otel_parent_id

父 Span 的标识符，例如 dc94d281b0f884ea

$otel_parent_sampled

父 Span 的 "sampled" 标志，可以是 "1" 或 "0"