Mercurial > hg > nginx-site
view xml/en/docs/ngx_otel_module.xml @ 2975:f8ad45c72992
nginx-1.25.1
author | Maxim Dounin <mdounin@mdounin.ru> |
---|---|
date | Tue, 13 Jun 2023 18:15:59 +0300 |
parents | cebca5ba84d7 |
children |
line wrap: on
line source
<?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>