Mercurial > hg > nginx-site
diff xml/en/docs/ngx_otel_module.xml @ 2956:a85e4d126bc7
Updated docs for the upcoming NGINX Plus release.
author | Yaroslav Zhuravlev <yar@nginx.com> |
---|---|
date | Tue, 02 May 2023 11:39:21 +0100 |
parents | |
children | cebca5ba84d7 |
line wrap: on
line diff
--- /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>