--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/xml/en/docs/ngx_otel_module.xml	Tue May 02 11:39:21 2023 +0100
@@ -0,0 +1,347 @@
+<?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="1">
+
+<section id="summary">
+
+<para>
+The <literal>ngx_otel_module</literal> module (1.23.4) 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>
+<note>
+This module is available as part of our
+<commercial_version>commercial subscription</commercial_version>
+in <literal>nginx-plus-module-otel</literal> package.
+After installation, the module can be loaded
+<link doc="../ngx_core_module.xml" id="load_module">dynamically</link>.
+</note>
+</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</literal></tag-name>
+<tag-desc>
+the address of OTLP/gRPC endpoint that will accept telemetry data.
+</tag-desc>
+
+<tag-name id="interval"><literal>interval</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</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</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    localhost:4317;
+    interval    5s;
+    batch_size  512;
+    batch_count 4;
+}
+</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_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://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/http.md">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>