Module ngx_otel_module
Join us for the first quarterly
NGINX Community Call
on July 22nd to connect and discuss NGINX development.
english
русский
news
about
download
security
documentation
faq
books
community
enterprise
community forum (new)
x.com
blog
njs
ingress controller
gateway fabric
Module ngx_otel_moduleExample 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
Syntax:
otel_exporter { ... }
Default:
—
Context:
http
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";
}
Syntax:
otel_service_name name;
Default:
otel_service_name unknown_service:nginx;
Context:
http
Sets the
“service.name”
attribute of the OTel resource.
Syntax:
otel_resource_attr name value;
Default:
—
Context:
http
This directive appeared in version 0.1.2.
Sets a custom OTel resource attribute.
Syntax:
otel_trace on |
off |
$variable;
Default:
otel_trace off;
Context:
http, server, location
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;
}
}
Syntax:
otel_trace_context extract |
inject |
propagate |
ignore;
Default:
otel_trace_context ignore;
Context:
http, server, location
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.
Syntax:
otel_span_name name;
Default:
—
Context:
http, server, location
Defines the name of the OTel
span.
By default, it is a name of the location for a request.
The name can contain variables.
Syntax:
otel_span_attr name value;
Default:
—
Context:
http, server, location
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”