模块 ngx_otel_module

ngx_otel_module 模块 (1.23.4) 是一个 第三方模块，它提供 OpenTelemetry 分布式跟踪支持。该模块支持 W3C 上下文传播和 OTLP/gRPC 导出协议。

下载和安装说明 在此处 提供。该模块还可用作预构建的 nginx-module-otel 动态模块 包 (1.25.3)。

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

将接受遥测数据的 OTLP/gRPC 端点的地址。

interval

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

batch_size

每个工作进程在一个批处理中发送的最大跨度数，默认值为 512。

batch_count

每个工作进程的待处理批处理数，超过限制的跨度将被丢弃，默认值为 4。

示例

otel_exporter {
    endpoint    localhost:4317;
    interval    5s;
    batch_size  512;
    batch_count 4;
}

otel_service_name unknown_service:nginx;

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

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

从请求中使用现有的跟踪上下文，以便 跟踪 和 父跨度 的标识符从传入请求中继承。

注入

向请求添加新上下文，覆盖现有标头（如果有）。

传播

更新现有上下文（合并 提取 和 注入）。

忽略

跳过上下文标头处理。

定义 OTel span 的名称。默认情况下，它是请求位置的名称。名称可以包含变量。

添加自定义 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”