模块 ngx_otel_module


otel_exporter
otel_service_name
otel_trace
otel_trace_context otel_span_name

otel_span_attr
默认 span 属性
的示例Directives
嵌入式变量

这ngx_otel_modulemodule （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;
        }
    }
}

Directives

语法： otel_exporter { ... }
默认值： —
上下文： http

指定 OTel 数据导出参数：

endpoint
将接受遥测数据的 OTLP/gRPC 端点的地址。
interval
两次导出之间的最大间隔， 默认情况下为5秒。
batch_size
每个工作程序在一批中发送的最大 span 数， 默认情况下为512.
batch_count
每个工作程序的待处理批次数， 超过限制的 span 将被丢弃， 默认情况下为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

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

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

启用或禁用 OpenTelemetry 跟踪。 也可以通过指定变量来启用该Directives：

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
使用请求中的现有跟踪上下文， 这样，的标识符 a trace 和 父 span 继承自传入请求。
inject
向请求添加新的上下文，覆盖现有标头（如果有）。
propagate
更新现有上下文 （将 extract 和 inject 组合在一起）。
ignore
跳过上下文标头处理。

语法： otel_span_name name;
默认值： —
上下文： http,server,location

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

语法： otel_span_attr name value;
默认值： —
上下文： http,server,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
“sampled“ 父 span 的标志， 可以是”1“ 或 ”0”