ngx_otel_module 模块

示例配置
指令
     otel_exporter
     otel_service_name
     otel_trace
     otel_trace_context
     otel_span_name
     otel_span_attr
默认跨度属性
嵌入变量

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

该模块的源代码可在 这里 获取。下载和安装说明可在 这里 获取。

该模块也可以在预构建的 nginx-module-otel 软件包 中获取,自 1.25.3 起可用,并作为我们 商业订阅 的一部分提供的 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_exporter { ... }
默认:
上下文: http

指定 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 name;
默认:
otel_service_name unknown_service:nginx;
上下文: http

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

语法: otel_trace on | off | $variable;
默认:
otel_trace off;
上下文: http, server, location

启用或禁用 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 extract | inject | propagate | ignore;
默认:
otel_trace_context ignore;
上下文: http, server, location

指定如何传播 traceparent/tracestate 头:

extract
使用请求中现有的跟踪上下文,以便从传入请求继承跟踪和父跨度的标识符。
inject
向请求添加新的上下文,覆盖现有的任何头。
propagate
更新现有上下文(结合了 extractinject)。
ignore
跳过上下文头处理。

语法: otel_span_name name;
默认:
上下文: http, server, location

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

语法: otel_span_attr name value;
默认:
上下文: http, server, location

添加自定义 OTel span 属性。值可以包含变量。

默认 span 属性

以下 span 属性 将自动添加:

嵌入式变量

$otel_trace_id
当前跨度所属的跟踪的标识符,例如,56552bc4daa3bf39c08362527e1dd6c4
$otel_span_id
当前跨度的标识符,例如,4c0b8531ec38ca59
$otel_parent_id
父跨度的标识符,例如,dc94d281b0f884ea
$otel_parent_sampled
父跨度的 “sampled” 标志,可以是 “1” 或 “0