-
Notifications
You must be signed in to change notification settings - Fork 893
/
sdk-environment-variables.md
362 lines (263 loc) · 25.3 KB
/
sdk-environment-variables.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
<!--- Hugo front matter used to generate the website version of this page:
title: Environment Variable Specification
linkTitle: Env var
aliases:
- /docs/reference/specification/sdk-environment-variables
- /docs/specs/otel/sdk-environment-variables
--->
# OpenTelemetry Environment Variable Specification
**Status**: [Stable](../document-status.md) except where otherwise specified
<details>
<summary>Table of Contents</summary>
<!-- toc -->
- [Implementation guidelines](#implementation-guidelines)
- [Parsing empty value](#parsing-empty-value)
- [Special configuration types](#special-configuration-types)
* [Boolean value](#boolean-value)
* [Numeric value](#numeric-value)
* [Enum value](#enum-value)
* [Duration](#duration)
- [General SDK Configuration](#general-sdk-configuration)
- [Batch Span Processor](#batch-span-processor)
- [Batch LogRecord Processor](#batch-logrecord-processor)
- [Attribute Limits](#attribute-limits)
- [Span Limits](#span-limits)
- [LogRecord Limits](#logrecord-limits)
- [OTLP Exporter](#otlp-exporter)
- [Zipkin Exporter](#zipkin-exporter)
- [Prometheus Exporter](#prometheus-exporter)
- [Exporter Selection](#exporter-selection)
* [In-development Exporter Selection](#in-development-exporter-selection)
- [Metrics SDK Configuration](#metrics-sdk-configuration)
* [Exemplar](#exemplar)
* [Periodic exporting MetricReader](#periodic-exporting-metricreader)
- [Declarative configuration](#declarative-configuration)
- [Language Specific Environment Variables](#language-specific-environment-variables)
<!-- tocstop -->
</details>
The goal of this specification is to unify the environment variable names between different OpenTelemetry implementations.
Implementations MAY choose to allow configuration via the environment variables in this specification, but are not required to.
If they do, they SHOULD use the names listed in this document.
## Implementation guidelines
Environment variables MAY be handled (implemented) directly by a component, in the SDK, or in a separate component (e.g. environment-based autoconfiguration component).
The environment-based configuration MUST have a direct code configuration equivalent.
## Parsing empty value
The SDK MUST interpret an empty value of an environment variable the same way as when the variable is unset.
## Special configuration types
### Boolean value
Any value that represents a Boolean MUST be set to true only by the case-insensitive string `"true"`, meaning `"True"` or `"TRUE"` are also accepted, as true.
An implementation MUST NOT extend this definition and define additional values that are interpreted as true.
Any value not explicitly defined here as a true value, including unset and empty values, MUST be interpreted as false.
If any value other than a true value, case-insensitive string `"false"`, empty, or unset is used, a warning SHOULD be logged to inform users about the fallback to false being applied.
All Boolean environment variables SHOULD be named and defined such that false is the expected safe default behavior.
Renaming or changing the default value MUST NOT happen without a major version upgrade.
### Numeric value
If an implementation chooses to support an integer-valued environment variable, it SHOULD support nonnegative values between 0 and 2³¹ − 1 (inclusive). Individual SDKs MAY choose to support a larger range of values.
> The following paragraph was added after stabilization and the requirements are
> thus qualified as "SHOULD" to allow implementations to avoid breaking changes.
> For new
> implementations, these should be treated as MUST requirements.
For variables accepting a numeric value, if the user provides a value the implementation cannot parse,
or which is outside the valid range for the configuration item, the implementation SHOULD
generate a warning and gracefully ignore the setting, i.e., treat them as not set.
In particular, implementations
SHOULD NOT assign a custom interpretation e.g. to negative values if a negative
value does not naturally apply to a configuration and does not have an explicitly specified meaning, but treat it like any other
invalid value.
For example, a value specifying a buffer size must naturally be non-negative.
Treating a negative value as "buffer everything" would be an example of such a discouraged custom interpretation.
Instead the default buffer size should be used.
Note that this could make a difference even if the custom interpretation is identical with the default value,
because it might reset a value set from other configuration sources with the default.
### Enum value
For variables which accept a known value out of a set, i.e., an enum value, implementations MAY support additional values not listed here.
For variables accepting an enum value, if the user provides a value the implementation does not recognize, the implementation MUST generate a warning and gracefully ignore the setting.
If a null object (empty, no-op) value is acceptable, then the enum value representing it MUST be `"none"`.
### Duration
Any value that represents a duration, for example a timeout, MUST be an integer representing a number of
milliseconds. The value is non-negative - if a negative value is provided, the implementation MUST generate a warning,
gracefully ignore the setting and use the default value if it is defined.
For example, the value `12000` indicates 12000 milliseconds, i.e., 12 seconds.
## General SDK Configuration
| Name | Description | Default | Notes |
|--------------------------|---------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| OTEL_SDK_DISABLED | Disable the SDK for all signals | false | Boolean value. If "true", a no-op SDK implementation will be used for all telemetry signals. Any other value or absence of the variable will have no effect and the SDK will remain enabled. This setting has no effect on propagators configured through the OTEL_PROPAGATORS variable. |
| OTEL_RESOURCE_ATTRIBUTES | Key-value pairs to be used as resource attributes | See [Resource semantic conventions](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/resource/README.md#semantic-attributes-with-dedicated-environment-variable) for details. | See [Resource SDK](../resource/sdk.md#specifying-resource-information-via-an-environment-variable) for more details. |
| OTEL_SERVICE_NAME | Sets the value of the [`service.name`](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/resource/README.md#service) resource attribute | | If `service.name` is also provided in `OTEL_RESOURCE_ATTRIBUTES`, then `OTEL_SERVICE_NAME` takes precedence. |
| OTEL_LOG_LEVEL | Log level used by the [SDK internal logger](../error-handling.md#self-diagnostics) | "info" | |
| OTEL_PROPAGATORS | Propagators to be used as a comma-separated list | "tracecontext,baggage" | Values MUST be deduplicated in order to register a `Propagator` only once. |
| OTEL_TRACES_SAMPLER | Sampler to be used for traces | "parentbased_always_on" | See [Sampling](../trace/sdk.md#sampling) |
| OTEL_TRACES_SAMPLER_ARG | String value to be used as the sampler argument | | The specified value will only be used if OTEL_TRACES_SAMPLER is set. Each Sampler type defines its own expected input, if any. Invalid or unrecognized input MUST be logged and MUST be otherwise ignored, i.e. the implementation MUST behave as if OTEL_TRACES_SAMPLER_ARG is not set. |
Known values for `OTEL_PROPAGATORS` are:
- `"tracecontext"`: [W3C Trace Context](https://www.w3.org/TR/trace-context/)
- `"baggage"`: [W3C Baggage](https://www.w3.org/TR/baggage/)
- `"b3"`: [B3 Single](../context/api-propagators.md#configuration)
- `"b3multi"`: [B3 Multi](../context/api-propagators.md#configuration)
- `"jaeger"`: [Jaeger](https://www.jaegertracing.io/sdk-migration/#propagation-format)
- `"xray"`: [AWS X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html#xray-concepts-tracingheader) (_third party_)
- `"ottrace"`: [OT Trace](https://github.com/opentracing?q=basic&type=&language=) (_third party_)
- `"none"`: No automatically configured propagator.
Known values for `OTEL_TRACES_SAMPLER` are:
- `"always_on"`: `AlwaysOnSampler`
- `"always_off"`: `AlwaysOffSampler`
- `"traceidratio"`: `TraceIdRatioBased`
- `"parentbased_always_on"`: `ParentBased(root=AlwaysOnSampler)`
- `"parentbased_always_off"`: `ParentBased(root=AlwaysOffSampler)`
- `"parentbased_traceidratio"`: `ParentBased(root=TraceIdRatioBased)`
- `"parentbased_jaeger_remote"`: `ParentBased(root=JaegerRemoteSampler)`
- `"jaeger_remote"`: `JaegerRemoteSampler`
- `"xray"`: [AWS X-Ray Centralized Sampling](https://docs.aws.amazon.com/xray/latest/devguide/xray-console-sampling.html) (_third party_)
Depending on the value of `OTEL_TRACES_SAMPLER`, `OTEL_TRACES_SAMPLER_ARG` may be set as follows:
- For `traceidratio` and `parentbased_traceidratio` samplers: Sampling probability, a number in the [0..1] range, e.g. "0.25". Default is 1.0 if unset.
- For `jaeger_remote` and `parentbased_jaeger_remote`: The value is a comma separated list:
- `endpoint`: the endpoint in form of `scheme://host:port` of gRPC server that serves the sampling strategy for the service ([sampling.proto](https://github.com/jaegertracing/jaeger-idl/blob/master/proto/api_v2/sampling.proto)).
- `pollingIntervalMs`: in milliseconds indicating how often the sampler will poll the backend for updates to sampling strategy.
- `initialSamplingRate`: in the [0..1] range, which is used as the sampling probability when the backend cannot be reached to retrieve a sampling strategy. This value stops having an effect once a sampling strategy is retrieved successfully, as the remote strategy will be used until a new update is retrieved.
- Example: `endpoint=http://localhost:14250,pollingIntervalMs=5000,initialSamplingRate=0.25`
## Batch Span Processor
| Name | Description | Default | Notes |
| ------------------------------ | ---------------------------------------------------------------- | ------- | ----------------------------------------------------- |
| OTEL_BSP_SCHEDULE_DELAY | Delay interval (in milliseconds) between two consecutive exports | 5000 | |
| OTEL_BSP_EXPORT_TIMEOUT | Maximum allowed time (in milliseconds) to export data | 30000 | |
| OTEL_BSP_MAX_QUEUE_SIZE | Maximum queue size | 2048 | |
| OTEL_BSP_MAX_EXPORT_BATCH_SIZE | Maximum batch size | 512 | Must be less than or equal to OTEL_BSP_MAX_QUEUE_SIZE |
## Batch LogRecord Processor
| Name | Description | Default | Notes |
| ------------------------------- | ---------------------------------------------------------------- | ------- | ------------------------------------------------------ |
| OTEL_BLRP_SCHEDULE_DELAY | Delay interval (in milliseconds) between two consecutive exports | 1000 | |
| OTEL_BLRP_EXPORT_TIMEOUT | Maximum allowed time (in milliseconds) to export data | 30000 | |
| OTEL_BLRP_MAX_QUEUE_SIZE | Maximum queue size | 2048 | |
| OTEL_BLRP_MAX_EXPORT_BATCH_SIZE | Maximum batch size | 512 | Must be less than or equal to OTEL_BLRP_MAX_QUEUE_SIZE |
## Attribute Limits
Implementations SHOULD only offer environment variables for the types of attributes, for
which that SDK implements truncation mechanism.
See the SDK [Attribute Limits](../common/README.md#attribute-limits) section for the definition of the limits.
| Name | Description | Default | Notes |
| --------------------------------- | ------------------------------------ | ------- | ----- |
| OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT | Maximum allowed attribute value size | no limit| |
| OTEL_ATTRIBUTE_COUNT_LIMIT | Maximum allowed attribute count | 128 | |
## Span Limits
See the SDK [Span Limits](../trace/sdk.md#span-limits) section for the definition of the limits.
| Name | Description | Default | Notes |
| -------------------------------------- | ---------------------------------------------- | ------- | ----- |
| OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT | Maximum allowed attribute value size | no limit | |
| OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT | Maximum allowed span attribute count | 128 | |
| OTEL_SPAN_EVENT_COUNT_LIMIT | Maximum allowed span event count | 128 | |
| OTEL_SPAN_LINK_COUNT_LIMIT | Maximum allowed span link count | 128 | |
| OTEL_EVENT_ATTRIBUTE_COUNT_LIMIT | Maximum allowed attribute per span event count | 128 | |
| OTEL_LINK_ATTRIBUTE_COUNT_LIMIT | Maximum allowed attribute per span link count | 128 | |
## LogRecord Limits
See the SDK [LogRecord Limits](../logs/sdk.md#logrecord-limits) section for the definition of the limits.
| Name | Description | Default | Notes |
| ------------------------------------------- | -------------------------------------------| -------- | ----- |
| OTEL_LOGRECORD_ATTRIBUTE_VALUE_LENGTH_LIMIT | Maximum allowed attribute value size | no limit | |
| OTEL_LOGRECORD_ATTRIBUTE_COUNT_LIMIT | Maximum allowed log record attribute count | 128 | |
## OTLP Exporter
See [OpenTelemetry Protocol Exporter Configuration Options](../protocol/exporter.md).
## Zipkin Exporter
| Name | Description | Default |
| ----------------------------- | ---------------------------------------------------------------------------------- |------------------------------------- |
| OTEL_EXPORTER_ZIPKIN_ENDPOINT | Endpoint for Zipkin traces | `http://localhost:9411/api/v2/spans` |
| OTEL_EXPORTER_ZIPKIN_TIMEOUT | Maximum time (in milliseconds) the Zipkin exporter will wait for each batch export | 10000 |
Additionally, the following environment variables are reserved for future
usage in Zipkin Exporter configuration:
- `OTEL_EXPORTER_ZIPKIN_PROTOCOL`
This will be used to specify whether or not the exporter uses v1 or v2, json,
thrift or protobuf. As of 1.0 of the specification, there
_is no specified default, or configuration via environment variables_.
## Prometheus Exporter
**Status**: [Development](../document-status.md)
| Name | Description | Default |
| ----------------------------- | --------------------------------| ---------------------------- |
| OTEL_EXPORTER_PROMETHEUS_HOST | Host used by the Prometheus exporter | "localhost" |
| OTEL_EXPORTER_PROMETHEUS_PORT | Port used by the Prometheus exporter | 9464 |
## Exporter Selection
We define environment variables for setting one or more exporters per signal.
| Name | Description | Default |
| ------------- | ---------------------------------------------------------------------------- | ------- |
| OTEL_TRACES_EXPORTER | Trace exporter to be used | "otlp" |
| OTEL_METRICS_EXPORTER | Metrics exporter to be used | "otlp" |
| OTEL_LOGS_EXPORTER | Logs exporter to be used | "otlp" |
The implementation MAY accept a comma-separated list to enable setting multiple exporters.
Known values for `OTEL_TRACES_EXPORTER` are:
- `"otlp"`: [OTLP](../protocol/otlp.md)
- `"zipkin"`: [Zipkin](https://zipkin.io/zipkin-api/) (Defaults to [protobuf](https://github.com/openzipkin/zipkin-api/blob/master/zipkin.proto) format)
- `"console"`: [Standard Output](../trace/sdk_exporters/stdout.md)
- `"logging"`: [Standard Output](../trace/sdk_exporters/stdout.md). It is a deprecated value left for backwards compatibility. It SHOULD
NOT be supported by new implementations.
- `"none"`: No automatically configured exporter for traces.
Known values for `OTEL_METRICS_EXPORTER` are:
- `"otlp"`: [OTLP](../protocol/otlp.md)
- `"prometheus"`: [Prometheus](https://github.com/prometheus/docs/blob/master/content/docs/instrumenting/exposition_formats.md)
- `"console"`: [Standard Output](../metrics/sdk_exporters/stdout.md)
- `"logging"`: [Standard Output](../metrics/sdk_exporters/stdout.md). It is a deprecated value left for backwards compatibility. It SHOULD
NOT be supported by new implementations.
- `"none"`: No automatically configured exporter for metrics.
Known values for `OTEL_LOGS_EXPORTER` are:
- `"otlp"`: [OTLP](../protocol/otlp.md)
- `"console"`: [Standard Output](../logs/sdk_exporters/stdout.md)
- `"logging"`: [Standard Output](../logs/sdk_exporters/stdout.md). It is a deprecated value left for backwards compatibility. It SHOULD
NOT be supported by new implementations.
- `"none"`: No automatically configured exporter for logs.
### In-development Exporter Selection
**Status**: [Development](../document-status.md)
In addition to the above, the following environment variables are added for in-development exporter selection:
Additional known values for `OTEL_TRACES_EXPORTER` are:
- `"otlp/stdout"`: [OTLP File](../protocol/file-exporter.md) writing to standard output
Additional known values for `OTEL_METRICS_EXPORTER` are:
- `"otlp/stdout"`: [OTLP File](../protocol/file-exporter.md) writing to standard output
Additional known values for `OTEL_LOGS_EXPORTER` are:
- `"otlp/stdout"`: [OTLP File](../protocol/file-exporter.md) writing to standard output
## Metrics SDK Configuration
### Exemplar
| Name | Description | Default | Notes |
|-----------------|---------|-------------|---------|
| `OTEL_METRICS_EXEMPLAR_FILTER` | Filter for which measurements can become Exemplars. | `"trace_based"` | |
Known values for `OTEL_METRICS_EXEMPLAR_FILTER` are:
- `"always_on"`: [AlwaysOn](../metrics/sdk.md#alwayson)
- `"always_off"`: [AlwaysOff](../metrics/sdk.md#alwaysoff)
- `"trace_based"`: [TraceBased](../metrics/sdk.md#tracebased)
### Periodic exporting MetricReader
Environment variables specific for the push metrics exporters (OTLP, stdout, in-memory)
that use [periodic exporting MetricReader](../metrics/sdk.md#periodic-exporting-metricreader).
| Name | Description | Default | Notes |
| ----------------------------- | ----------------------------------------------------------------------------- | ------- | ----- |
| `OTEL_METRIC_EXPORT_INTERVAL` | The time interval (in milliseconds) between the start of two export attempts. | 60000 | |
| `OTEL_METRIC_EXPORT_TIMEOUT` | Maximum allowed time (in milliseconds) to export data. | 30000 | |
## Declarative configuration
**Status**: [Development](../document-status.md)
Environment variables involved in [declarative configuration](./README.md#declarative-configuration).
| Name | Description | Default | Notes |
|-------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------|-----------|
| OTEL_EXPERIMENTAL_CONFIG_FILE | The path of the configuration file used to configure the SDK. If set, the configuration in this file takes precedence over all other SDK configuration environment variables. | | See below |
If `OTEL_EXPERIMENTAL_CONFIG_FILE` is set, the file at the specified path is used to
call [Parse](./sdk.md#parse). The
resulting [configuration model](./sdk.md#in-memory-configuration-model) is
used to call [Create](./sdk.md#create) to produce fully configured
SDK components.
When `OTEL_EXPERIMENTAL_CONFIG_FILE` is set, all other environment variables
besides those referenced in the configuration file
for [environment variable substitution](./data-model.md#environment-variable-substitution)
MUST be ignored. Ignoring the environment variables is necessary because
there is no intuitive way to merge the flat environment variable scheme with the
structured file configuration scheme in all cases. Users that require merging
multiple sources of configuration are encouraged to customize the configuration
model returned by `Parse` before `Create` is called. For example, a user may
call `Parse` on multiple files and define logic from merging the resulting
configuration models, or overlay values from environment variables on top of a
configuration model. Implementations MAY provide a mechanism to customize the
configuration model parsed from `OTEL_EXPERIMENTAL_CONFIG_FILE`.
Users are encouraged to use the `sdk-config.yaml` (TODO: Add link when
available) as a starting point for `OTEL_EXPERIMENTAL_CONFIG_FILE`. This file
represents a common SDK configuration scenario, and includes environment
variable substitution references to environment variables which are otherwise
ignored.
TODO: deprecate env vars which are not
compatible ([#3967](https://github.com/open-telemetry/opentelemetry-specification/issues/3967))
TODO: provide solution for platforms to contribute to
configure ([#3966](https://github.com/open-telemetry/opentelemetry-specification/issues/3966))
## Language Specific Environment Variables
To ensure consistent naming across projects, this specification recommends that language specific environment variables are formed using the following convention:
```
OTEL_{LANGUAGE}_{FEATURE}
```