Module ngx_otel_module

• Example Configuration
• Directives
• otel_exporter
• otel_service_name
• otel_resource_attr
• otel_trace
• otel_trace_context
• otel_span_name
• otel_span_attr
• Default span attributes
• Embedded Variables

The ngx_otel_module module provides OpenTelemetry distributed tracing support. The module supports W3C context propagation and OTLP/gRPC export protocol.

The source code of the module is available here. Download and install instructions are available here.

The module is also available in a prebuilt nginx-module-otel package since 1.25.3 and in nginx-plus-module-otel package as part of our commercial subscription since 1.23.4.

Example Configuration

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

Specifies OTel data export parameters:

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

OTLP/gRPC endpoint that will accept telemetry data. TLS is supported since 0.1.2.

trusted_certificate path;

the CA certificates file in PEM format used to verify TLS endpoint (since 0.1.2). Defaults to OS provided CA bundle.

header name value;

a custom HTTP header to add to telemetry export request (since 0.1.2).

interval time;

the maximum interval between two exports, by default is 5 seconds.

batch_size number;

the maximum number of spans to be sent in one batch per worker, by default is 512.

batch_count number;

the number of pending batches per worker, spans exceeding the limit are dropped, by default is 4.

Example:

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

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

Sets the “service.name” attribute of the OTel resource.

Sets a custom OTel resource attribute.

Enables or disables OpenTelemetry tracing. The directive can also be enabled by specifying a variable:

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

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

Specifies how to propagate traceparent/tracestate headers:

extract

uses an existing trace context from the request, so that the identifiers of a trace and the parent span are inherited from the incoming request.

inject

adds a new context to the request, overwriting existing headers, if any.

propagate

updates the existing context (combines extract and inject).

ignore

skips context headers processing.

Defines the name of the OTel span. By default, it is a name of the location for a request. The name can contain variables.

Adds a custom OTel span attribute. The value can contain variables.

Default span attributes

The following span attributes are added automatically:

• 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

Embedded Variables

$otel_trace_id

the identifier of the trace the current span belongs to, for example, 56552bc4daa3bf39c08362527e1dd6c4

$otel_span_id

the identifier of the current span, for example, 4c0b8531ec38ca59

$otel_parent_id

the identifier of the parent span, for example, dc94d281b0f884ea

$otel_parent_sampled

the “sampled” flag of the parent span, can be “1” or “0”