Module ngx_otel_module

The ngx_otel_module module (1.23.4) 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.

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;
        }
    }
}

Specifies OTel data export parameters:

endpoint

the address of OTLP/gRPC endpoint that will accept telemetry data.

interval

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

batch_size

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

batch_count

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

Example:

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

otel_service_name unknown_service:nginx;

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

otel_trace off;

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;
    }
}

otel_trace_context ignore;

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.

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

$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”