ngx_otel_module.xml

<?xml version="1.0"?>

<!--
  Copyright (C) Nginx, Inc.
  -->

<!DOCTYPE module SYSTEM "../../../dtd/module.dtd">

<module name="Module ngx_otel_module"
        link="/en/docs/ngx_otel_module.html"
        lang="en"
        rev="4">

<section id="summary">

<para>
The <literal>ngx_otel_module</literal> module provides
<link url="https://opentelemetry.io">OpenTelemetry</link>
distributed tracing support.
The module supports
<link url="https://w3c.github.io/trace-context">W3C</link>
context propagation and OTLP/gRPC export protocol.
</para>

<para>
The source code of the module is available
<link url="https://github.com/nginxinc/nginx-otel">here</link>.
Download and install instructions are available
<link url="https://github.com/nginxinc/nginx-otel/blob/main/README.md">here</link>.
</para>

<para>
The module is also available in a prebuilt
<literal>nginx-module-otel</literal>
<link doc="../linux_packages.xml" id="dynmodules">package</link>
since 1.25.3
and in <literal>nginx-plus-module-otel</literal> package
as part of our
<commercial_version>commercial subscription</commercial_version> since 1.23.4.
</para>

</section>


<section id="example" name="Example Configuration">

<para>
<example>
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;
        }
    }
}
</example>
</para>

</section>


<section id="directives" name="Directives">

<directive name="otel_exporter">
<syntax block="yes"/>
<default/>
<context>http</context>

<para>
Specifies OTel data export parameters:

<list type="tag">

<tag-name id="endpoint"><literal>
    endpoint [(http|https)://]host:port;</literal></tag-name>
<tag-desc>
OTLP/gRPC endpoint that will accept telemetry data.
TLS is supported since 0.1.2.
</tag-desc>

<tag-name id="trusted_certificate"><literal>
    trusted_certificate path;</literal></tag-name>
<tag-desc>
the CA certificates file in PEM format used to verify TLS endpoint
(since 0.1.2).
Defaults to OS provided CA bundle.
</tag-desc>

<tag-name id="header"><literal>header name value;</literal></tag-name>
<tag-desc>
a custom HTTP header to add to telemetry export request (since 0.1.2).
</tag-desc>

<tag-name id="interval"><literal>interval time;</literal></tag-name>
<tag-desc>
the maximum interval between two exports,
by default is <literal>5</literal> seconds.
</tag-desc>

<tag-name id="batch_size"><literal>batch_size number;</literal></tag-name>
<tag-desc>
the maximum number of spans to be sent in one batch per worker,
by default is <literal>512</literal>.
</tag-desc>

<tag-name id="batch_count"><literal>batch_count number;</literal></tag-name>
<tag-desc>
the number of pending batches per worker,
spans exceeding the limit are dropped,
by default is <literal>4</literal>.
</tag-desc>

</list>
Example:
<example>
otel_exporter {
    endpoint https://otel-example.nginx.com:4317;

    header X-API-Token "my-token-value";
}
</example>
</para>

</directive>


<directive name="otel_service_name">
<syntax><value>name</value></syntax>
<default>unknown_service:nginx</default>
<context>http</context>

<para>
Sets the
“<link url="https://opentelemetry.io/docs/reference/specification/resource/semantic_conventions/#service"><literal>service.name</literal></link>”
attribute of the OTel resource.
</para>

</directive>


<directive name="otel_resource_attr">
<syntax><value>name</value> <value>value</value></syntax>
<default/>
<context>http</context>
<appeared-in>0.1.2</appeared-in>

<para>
Sets a custom OTel resource attribute.
</para>

</directive>


<directive name="otel_trace">
<syntax><literal>on</literal> |
        <literal>off</literal> |
        <literal>$variable</literal></syntax>
<default>off</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Enables or disables OpenTelemetry tracing.
The directive can also be enabled by specifying a variable:
<example>
split_clients "$otel_trace_id" $ratio_sampler {
              10%              on;
              *                off;
}

server {
    location / {
        otel_trace         $ratio_sampler;
        otel_trace_context inject;
        proxy_pass         http://backend;
    }
}
</example>
</para>

</directive>


<directive name="otel_trace_context">
<syntax><literal>extract</literal> |
        <literal>inject</literal> |
        <literal>propagate</literal> |
        <literal>ignore</literal></syntax>
<default>ignore</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Specifies how to propagate
<link url="https://www.w3.org/TR/trace-context/#design-overview">traceparent/tracestate</link> headers:

<list type="tag">

<tag-name id="extract"><literal>extract</literal></tag-name>
<tag-desc>
uses an existing trace context from the request,
so that the identifiers of
a <link id="var_otel_trace_id">trace</link> and
the <link id="var_otel_parent_id">parent span</link>
are inherited from the incoming request.
</tag-desc>

<tag-name id="inject"><literal>inject</literal></tag-name>
<tag-desc>
adds a new context to the request, overwriting existing headers, if any.
</tag-desc>

<tag-name id="propagate"><literal>propagate</literal></tag-name>
<tag-desc>
updates the existing context
(combines <link id="extract"/> and <link id="inject"/>).
</tag-desc>

<tag-name id="ignore"><literal>ignore</literal></tag-name>
<tag-desc>
skips context headers processing.
</tag-desc>

</list>
</para>

</directive>


<directive name="otel_span_name">
<syntax><value>name</value></syntax>
<default/>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Defines the name of the OTel
<link url="https://opentelemetry.io/docs/concepts/observability-primer/#spans">span</link>.
By default, it is a name of the location for a request.
The name can contain variables.
</para>

</directive>


<directive name="otel_span_attr">
<syntax><value>name</value> <value>value</value></syntax>
<default/>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Adds a custom OTel span attribute.
The value can contain variables.
</para>

</directive>

</section>


<section id="span" name="Default span attributes">

<para>
The following
<link url="https://opentelemetry.io/docs/specs/semconv/registry/attributes/http/">span
attributes</link>
are added automatically:

<list type="bullet">

<listitem>
<literal>http.method</literal>
</listitem>

<listitem>
<literal>http.target</literal>
</listitem>

<listitem>
<literal>http.route</literal>
</listitem>

<listitem>
<literal>http.scheme</literal>
</listitem>

<listitem>
<literal>http.flavor</literal>
</listitem>

<listitem>
<literal>http.user_agent</literal>
</listitem>

<listitem>
<literal>http.request_content_length</literal>
</listitem>

<listitem>
<literal>http.response_content_length</literal>
</listitem>

<listitem>
<literal>http.status_code</literal>
</listitem>

<listitem>
<literal>net.host.name</literal>
</listitem>

<listitem>
<literal>net.host.port</literal>
</listitem>

<listitem>
<literal>net.sock.peer.addr</literal>
</listitem>

<listitem>
<literal>net.sock.peer.port</literal>
</listitem>

</list>
</para>

</section>


<section id="variables" name="Embedded Variables">

<para>
<list type="tag">

<tag-name id="var_otel_trace_id"><var>$otel_trace_id</var></tag-name>
<tag-desc>
the identifier of the trace the current span belongs to,
for example, <literal>56552bc4daa3bf39c08362527e1dd6c4</literal>
</tag-desc>

<tag-name id="var_otel_span_id"><var>$otel_span_id</var></tag-name>
<tag-desc>
the identifier of the current span,
for example, <literal>4c0b8531ec38ca59</literal>
</tag-desc>

<tag-name id="var_otel_parent_id"><var>$otel_parent_id</var></tag-name>
<tag-desc>
the identifier of the parent span,
for example, <literal>dc94d281b0f884ea</literal>
</tag-desc>

<tag-name id="var_otel_parent_sampled"><var>$otel_parent_sampled</var></tag-name>
<tag-desc>
the “<literal>sampled</literal>” flag of the parent span,
can be “<literal>1</literal>” or “<literal>0</literal>”
</tag-desc>

</list>
</para>

</section>

</module>