Mercurial > hg > nginx-site

comparison xml/en/docs/ngx_otel_module.xml @ 2956:a85e4d126bc7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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
comparison
equal deleted inserted replaced
2955:2c4d7151b9a9 2956:a85e4d126bc7
1 <?xml version="1.0"?>
2
3 <!--
4 Copyright (C) Nginx, Inc.
5 -->
6
7 <!DOCTYPE module SYSTEM "../../../dtd/module.dtd">
8
9 <module name="Module ngx_otel_module"
10 link="/en/docs/ngx_otel_module.html"
11 lang="en"
12 rev="1">
13
14 <section id="summary">
15
16 <para>
17 The <literal>ngx_otel_module</literal> module (1.23.4) provides
18 <link url="https://opentelemetry.io">OpenTelemetry</link>
19 distributed tracing support.
20 The module supports
21 <link url="https://w3c.github.io/trace-context">W3C</link>
22 context propagation and OTLP/gRPC export protocol.
23 </para>
24
25 <para>
26 <note>
27 This module is available as part of our
28 <commercial_version>commercial subscription</commercial_version>
29 in <literal>nginx-plus-module-otel</literal> package.
30 After installation, the module can be loaded
31 <link doc="../ngx_core_module.xml" id="load_module">dynamically</link>.
32 </note>
33 </para>
34
35 </section>
36
37
38 <section id="example" name="Example Configuration">
39
40 <para>
41 <example>
42 load_module modules/ngx_otel_module.so;
43
44 events {
45 }
46
47 http {
48
49 otel_exporter {
50 endpoint localhost:4317;
51 }
52
53 server {
54 listen 127.0.0.1:8080;
55
56 location / {
57 otel_trace on;
58 otel_trace_context inject;
59
60 proxy_pass http://backend;
61 }
62 }
63 }
64 </example>
65 </para>
66
67 </section>
68
69
70 <section id="directives" name="Directives">
71
72 <directive name="otel_exporter">
73 <syntax block="yes"/>
74 <default/>
75 <context>http</context>
76
77 <para>
78 Specifies OTel data export parameters:
79
80 <list type="tag">
81
82 <tag-name id="endpoint"><literal>endpoint</literal></tag-name>
83 <tag-desc>
84 the address of OTLP/gRPC endpoint that will accept telemetry data.
85 </tag-desc>
86
87 <tag-name id="interval"><literal>interval</literal></tag-name>
88 <tag-desc>
89 the maximum interval between two exports,
90 by default is <literal>5</literal> seconds.
91 </tag-desc>
92
93 <tag-name id="batch_size"><literal>batch_size</literal></tag-name>
94 <tag-desc>
95 the maximum number of spans to be sent in one batch per worker,
96 by default is <literal>512</literal>.
97 </tag-desc>
98
99 <tag-name id="batch_count"><literal>batch_count</literal></tag-name>
100 <tag-desc>
101 the number of pending batches per worker,
102 spans exceeding the limit are dropped,
103 by default is <literal>4</literal>.
104 </tag-desc>
105
106 </list>
107 Example:
108 <example>
109 otel_exporter {
110 endpoint localhost:4317;
111 interval 5s;
112 batch_size 512;
113 batch_count 4;
114 }
115 </example>
116 </para>
117
118 </directive>
119
120
121 <directive name="otel_service_name">
122 <syntax><value>name</value></syntax>
123 <default>unknown_service:nginx</default>
124 <context>http</context>
125
126 <para>
127 Sets the
128 “<link url="https://opentelemetry.io/docs/reference/specification/resource/semantic_conventions/#service"><literal>service.name</literal></link>”
129 attribute of the OTel resource.
130 </para>
131
132 </directive>
133
134
135 <directive name="otel_trace">
136 <syntax><literal>on</literal> |
137 <literal>off</literal> |
138 <literal>$variable</literal></syntax>
139 <default>off</default>
140 <context>http</context>
141 <context>server</context>
142 <context>location</context>
143
144 <para>
145 Enables or disables OpenTelemetry tracing.
146 The directive can also be enabled by specifying a variable:
147 <example>
148 split_clients "$otel_trace_id" $ratio_sampler {
149 10% on;
150 * off;
151 }
152
153 server {
154 location / {
155 otel_trace $ratio_sampler;
156 otel_trace_context inject;
157 proxy_pass http://backend;
158 }
159 }
160 </example>
161 </para>
162
163 </directive>
164
165
166 <directive name="otel_trace_context">
167 <syntax><literal>extract</literal> |
168 <literal>inject</literal> |
169 <literal>propagate</literal> |
170 <literal>ignore</literal></syntax>
171 <default>ignore</default>
172 <context>http</context>
173 <context>server</context>
174 <context>location</context>
175
176 <para>
177 Specifies how to propagate
178 <link url="https://www.w3.org/TR/trace-context/#design-overview">traceparent/tracestate</link> headers:
179
180 <list type="tag">
181
182 <tag-name id="extract"><literal>extract</literal></tag-name>
183 <tag-desc>
184 uses an existing trace context from the request,
185 so that the identifiers of
186 a <link id="var_otel_trace_id">trace</link> and
187 the <link id="var_otel_parent_id">parent span</link>
188 are inherited from the incoming request.
189 </tag-desc>
190
191 <tag-name id="inject"><literal>inject</literal></tag-name>
192 <tag-desc>
193 adds a new context to the request, overwriting existing headers, if any.
194 </tag-desc>
195
196 <tag-name id="propagate"><literal>propagate</literal></tag-name>
197 <tag-desc>
198 updates the existing context
199 (combines <link id="extract"/> and <link id="inject"/>).
200 </tag-desc>
201
202 <tag-name id="ignore"><literal>ignore</literal></tag-name>
203 <tag-desc>
204 skips context headers processing.
205 </tag-desc>
206
207 </list>
208 </para>
209
210 </directive>
211
212
213 <directive name="otel_span_name">
214 <syntax><value>name</value></syntax>
215 <default/>
216 <context>http</context>
217 <context>server</context>
218 <context>location</context>
219
220 <para>
221 Defines the name of the OTel
222 <link url="https://opentelemetry.io/docs/concepts/observability-primer/#spans">span</link>.
223 By default, it is a name of the location for a request.
224 The name can contain variables.
225 </para>
226
227 </directive>
228
229
230 <directive name="otel_span_attr">
231 <syntax><value>name</value> <value>value</value></syntax>
232 <default/>
233 <context>http</context>
234 <context>server</context>
235 <context>location</context>
236
237 <para>
238 Adds a custom OTel span attribute.
239 The value can contain variables.
240 </para>
241
242 </directive>
243
244 </section>
245
246
247 <section id="span" name="Default span attributes">
248
249 <para>
250 The following <link url="https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/http.md">span attributes</link>
251 are added automatically:
252
253 <list type="bullet">
254
255 <listitem>
256 <literal>http.method</literal>
257 </listitem>
258
259 <listitem>
260 <literal>http.target</literal>
261 </listitem>
262
263 <listitem>
264 <literal>http.route</literal>
265 </listitem>
266
267 <listitem>
268 <literal>http.scheme</literal>
269 </listitem>
270
271 <listitem>
272 <literal>http.flavor</literal>
273 </listitem>
274
275 <listitem>
276 <literal>http.user_agent</literal>
277 </listitem>
278
279 <listitem>
280 <literal>http.request_content_length</literal>
281 </listitem>
282
283 <listitem>
284 <literal>http.response_content_length</literal>
285 </listitem>
286
287 <listitem>
288 <literal>http.status_code</literal>
289 </listitem>
290
291 <listitem>
292 <literal>net.host.name</literal>
293 </listitem>
294
295 <listitem>
296 <literal>net.host.port</literal>
297 </listitem>
298
299 <listitem>
300 <literal>net.sock.peer.addr</literal>
301 </listitem>
302
303 <listitem>
304 <literal>net.sock.peer.port</literal>
305 </listitem>
306
307 </list>
308 </para>
309
310 </section>
311
312
313 <section id="variables" name="Embedded Variables">
314
315 <para>
316 <list type="tag">
317
318 <tag-name id="var_otel_trace_id"><var>$otel_trace_id</var></tag-name>
319 <tag-desc>
320 the identifier of the trace the current span belongs to,
321 for example, <literal>56552bc4daa3bf39c08362527e1dd6c4</literal>
322 </tag-desc>
323
324 <tag-name id="var_otel_span_id"><var>$otel_span_id</var></tag-name>
325 <tag-desc>
326 the identifier of the current span,
327 for example, <literal>4c0b8531ec38ca59</literal>
328 </tag-desc>
329
330 <tag-name id="var_otel_parent_id"><var>$otel_parent_id</var></tag-name>
331 <tag-desc>
332 the identifier of the parent span,
333 for example, <literal>dc94d281b0f884ea</literal>
334 </tag-desc>
335
336 <tag-name id="var_otel_parent_sampled"><var>$otel_parent_sampled</var></tag-name>
337 <tag-desc>
338 the “<literal>sampled</literal>” flag of the parent span,
339 can be “<literal>1</literal>” or “<literal>0</literal>”
340 </tag-desc>
341
342 </list>
343 </para>
344
345 </section>
346
347 </module>