Skip to content

Commit d46ad22

Browse files
jack-bergreyangpellared
authored
Clarify boundaries of numeric env vars (#4331)
Resolves #4283. * Adds new guidance indicates that for timeout variables, "implementations SHOULD interpret timeout values of zero as indefinite". * Clarifies range of acceptable values for `OTEL_ATTRIBUTE_*` / `OTEL_SPAN_ATTRIBUTE_*` / `OTEL_LOGRECORD_ATTRIBUTE_*`, `OTEL_BSP_MAX_QUEUE_SIZE`, `OTEL_BLRP_MAX_QUEUE_SIZE`. Related PR to `opentelemetry-configuration`: open-telemetry/opentelemetry-configuration#151 --------- Co-authored-by: Reiley Yang <[email protected]> Co-authored-by: Robert Pająk <[email protected]>
1 parent 7a1caee commit d46ad22

File tree

3 files changed

+69
-44
lines changed

3 files changed

+69
-44
lines changed

‎CHANGELOG.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,10 @@ release.
3232

3333
### SDK Configuration
3434

35+
- Clarify that implementations should interpret timeout environment variable
36+
values of zero as no limit (infinity).
37+
([#4331](https://github.com/open-telemetry/opentelemetry-specification/pull/4331))
38+
3539
### Common
3640

3741
### Supplementary Guidelines

‎specification/configuration/sdk-environment-variables.md‎

Lines changed: 62 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ aliases:
2222
* [Numeric](#numeric)
2323
+ [Integer](#integer)
2424
+ [Duration](#duration)
25+
+ [Timeout](#timeout)
2526
* [String](#string)
2627
+ [Enum](#enum)
2728
- [General SDK Configuration](#general-sdk-configuration)
@@ -82,6 +83,7 @@ Variables accepting numeric values are sub-classified into:
8283

8384
* [Integer](#integer)
8485
* [Duration](#duration)
86+
* [Timeout](#timeout)
8587

8688
The following guidance applies to all numeric types.
8789

@@ -110,18 +112,36 @@ configuration sources with the default.
110112
#### Integer
111113

112114
If an implementation chooses to support an integer-valued environment variable,
113-
it SHOULD support nonnegative values between 0 and 2³¹ − 1 (inclusive).
115+
it SHOULD support non-negative values between 0 and 2³¹ − 1 (inclusive).
114116
Individual SDKs MAY choose to support a larger range of values.
115117

116118
#### Duration
117119

118-
Any value that represents a duration, for example a timeout, MUST be an integer
119-
representing a number of milliseconds. The value is non-negative - if a negative
120-
value is provided, the implementation MUST generate a warning, gracefully ignore
121-
the setting and use the default value if it is defined.
120+
Any value that represents a duration MUST be an integer representing a number of
121+
milliseconds. The value is non-negative - if a negative value is provided, the
122+
implementation MUST generate a warning, gracefully ignore the setting and use
123+
the default value if it is defined.
122124

123125
For example, the value `12000` indicates 12000 milliseconds, i.e., 12 seconds.
124126

127+
#### Timeout
128+
129+
Timeout values are similar to [duration](#duration) values, but are treated as a
130+
separate type because of differences in how they interpret timeout zero values (
131+
see below).
132+
133+
Any value that represents a timeout MUST be an integer representing a number of
134+
milliseconds. The value is non-negative - if a negative value is provided, the
135+
implementation MUST generate a warning, gracefully ignore the setting and use
136+
the default value if it is defined.
137+
138+
For example, the value `12000` indicates 12000 milliseconds, i.e., 12 seconds.
139+
140+
Implementations SHOULD interpret timeout zero values (i.e. `0` indicating 0
141+
milliseconds) as no limit (i.e. infinite). In practice, implementations MAY
142+
treat no limit as "a very long time" and substitute a very large duration (
143+
e.g. the maximum milliseconds representable by a 32-bit integer).
144+
125145
### String
126146

127147
String values are sub-classified into:
@@ -188,21 +208,21 @@ Depending on the value of `OTEL_TRACES_SAMPLER`, `OTEL_TRACES_SAMPLER_ARG` may b
188208

189209
## Batch Span Processor
190210

191-
| Name | Description | Default | Type | Notes |
192-
|--------------------------------|------------------------------------------------------------------|---------|--------------|-------------------------------------------------------|
193-
| OTEL_BSP_SCHEDULE_DELAY | Delay interval (in milliseconds) between two consecutive exports | 5000 | [Duration][] | |
194-
| OTEL_BSP_EXPORT_TIMEOUT | Maximum allowed time (in milliseconds) to export data | 30000 | [Duration][] | |
195-
| OTEL_BSP_MAX_QUEUE_SIZE | Maximum queue size | 2048 | [Integer][] | |
196-
| OTEL_BSP_MAX_EXPORT_BATCH_SIZE | Maximum batch size | 512 | [Integer][] | Must be less than or equal to OTEL_BSP_MAX_QUEUE_SIZE |
211+
| Name | Description | Default | Type | Notes |
212+
|--------------------------------|------------------------------------------------------------------|---------|--------------|-----------------------------------------------------------------------------------|
213+
| OTEL_BSP_SCHEDULE_DELAY | Delay interval (in milliseconds) between two consecutive exports | 5000 | [Duration][] | |
214+
| OTEL_BSP_EXPORT_TIMEOUT | Maximum allowed time (in milliseconds) to export data | 30000 | [Timeout][] | |
215+
| OTEL_BSP_MAX_QUEUE_SIZE | Maximum queue size | 2048 | [Integer][] | Valid values are positive. |
216+
| OTEL_BSP_MAX_EXPORT_BATCH_SIZE | Maximum batch size | 512 | [Integer][] | Must be less than or equal to OTEL_BSP_MAX_QUEUE_SIZE. Valid values are positive. |
197217

198218
## Batch LogRecord Processor
199219

200-
| Name | Description | Default | Type | Notes |
201-
|---------------------------------|------------------------------------------------------------------|---------|--------------|--------------------------------------------------------|
202-
| OTEL_BLRP_SCHEDULE_DELAY | Delay interval (in milliseconds) between two consecutive exports | 1000 | [Duration][] | |
203-
| OTEL_BLRP_EXPORT_TIMEOUT | Maximum allowed time (in milliseconds) to export data | 30000 | [Duration][] | |
204-
| OTEL_BLRP_MAX_QUEUE_SIZE | Maximum queue size | 2048 | [Integer][] | |
205-
| OTEL_BLRP_MAX_EXPORT_BATCH_SIZE | Maximum batch size | 512 | [Integer][] | Must be less than or equal to OTEL_BLRP_MAX_QUEUE_SIZE |
220+
| Name | Description | Default | Type | Notes |
221+
|---------------------------------|------------------------------------------------------------------|---------|--------------|------------------------------------------------------------------------------------|
222+
| OTEL_BLRP_SCHEDULE_DELAY | Delay interval (in milliseconds) between two consecutive exports | 1000 | [Duration][] | |
223+
| OTEL_BLRP_EXPORT_TIMEOUT | Maximum allowed time (in milliseconds) to export data | 30000 | [Timeout][] | |
224+
| OTEL_BLRP_MAX_QUEUE_SIZE | Maximum queue size | 2048 | [Integer][] | Valid values are positive. |
225+
| OTEL_BLRP_MAX_EXPORT_BATCH_SIZE | Maximum batch size | 512 | [Integer][] | Must be less than or equal to OTEL_BLRP_MAX_QUEUE_SIZE. Valid values are positive. |
206226

207227
## Attribute Limits
208228

@@ -211,32 +231,32 @@ which that SDK implements truncation mechanism.
211231

212232
See the SDK [Attribute Limits](../common/README.md#attribute-limits) section for the definition of the limits.
213233

214-
| Name | Description | Default | Type |
215-
|-----------------------------------|--------------------------------------|----------|-------------|
216-
| OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT | Maximum allowed attribute value size | no limit | [Integer][] |
217-
| OTEL_ATTRIBUTE_COUNT_LIMIT | Maximum allowed attribute count | 128 | [Integer][] |
234+
| Name | Description | Default | Type | Notes |
235+
|-----------------------------------|--------------------------------------|----------|-------------|--------------------------------|
236+
| OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT | Maximum allowed attribute value size | no limit | [Integer][] | Valid values are non-negative. |
237+
| OTEL_ATTRIBUTE_COUNT_LIMIT | Maximum allowed attribute count | 128 | [Integer][] | Valid values are non-negative. |
218238

219239
## Span Limits
220240

221241
See the SDK [Span Limits](../trace/sdk.md#span-limits) section for the definition of the limits.
222242

223-
| Name | Description | Default | Type |
224-
|----------------------------------------|------------------------------------------------|----------|-------------|
225-
| OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT | Maximum allowed attribute value size | no limit | [Integer][] |
226-
| OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT | Maximum allowed span attribute count | 128 | [Integer][] |
227-
| OTEL_SPAN_EVENT_COUNT_LIMIT | Maximum allowed span event count | 128 | [Integer][] |
228-
| OTEL_SPAN_LINK_COUNT_LIMIT | Maximum allowed span link count | 128 | [Integer][] |
229-
| OTEL_EVENT_ATTRIBUTE_COUNT_LIMIT | Maximum allowed attribute per span event count | 128 | [Integer][] |
230-
| OTEL_LINK_ATTRIBUTE_COUNT_LIMIT | Maximum allowed attribute per span link count | 128 | [Integer][] |
243+
| Name | Description | Default | Type | Notes |
244+
|----------------------------------------|------------------------------------------------|----------|-------------|--------------------------------|
245+
| OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT | Maximum allowed attribute value size | no limit | [Integer][] | Valid values are non-negative. |
246+
| OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT | Maximum allowed span attribute count | 128 | [Integer][] | Valid values are non-negative. |
247+
| OTEL_SPAN_EVENT_COUNT_LIMIT | Maximum allowed span event count | 128 | [Integer][] | Valid values are non-negative. |
248+
| OTEL_SPAN_LINK_COUNT_LIMIT | Maximum allowed span link count | 128 | [Integer][] | Valid values are non-negative. |
249+
| OTEL_EVENT_ATTRIBUTE_COUNT_LIMIT | Maximum allowed attribute per span event count | 128 | [Integer][] | Valid values are non-negative. |
250+
| OTEL_LINK_ATTRIBUTE_COUNT_LIMIT | Maximum allowed attribute per span link count | 128 | [Integer][] | Valid values are non-negative. |
231251

232252
## LogRecord Limits
233253

234254
See the SDK [LogRecord Limits](../logs/sdk.md#logrecord-limits) section for the definition of the limits.
235255

236-
| Name | Description | Default | Type |
237-
|---------------------------------------------|--------------------------------------------|----------|-------------|
238-
| OTEL_LOGRECORD_ATTRIBUTE_VALUE_LENGTH_LIMIT | Maximum allowed attribute value size | no limit | [Integer][] |
239-
| OTEL_LOGRECORD_ATTRIBUTE_COUNT_LIMIT | Maximum allowed log record attribute count | 128 | [Integer][] |
256+
| Name | Description | Default | Type | Notes |
257+
|---------------------------------------------|--------------------------------------------|----------|-------------|--------------------------------|
258+
| OTEL_LOGRECORD_ATTRIBUTE_VALUE_LENGTH_LIMIT | Maximum allowed attribute value size | no limit | [Integer][] | Valid values are non-negative. |
259+
| OTEL_LOGRECORD_ATTRIBUTE_COUNT_LIMIT | Maximum allowed log record attribute count | 128 | [Integer][] | Valid values are non-negative. |
240260

241261
## OTLP Exporter
242262

@@ -247,7 +267,7 @@ See [OpenTelemetry Protocol Exporter Configuration Options](../protocol/exporter
247267
| Name | Description | Default | Type |
248268
|-------------------------------|------------------------------------------------------------------------------------|--------------------------------------|-------------|
249269
| OTEL_EXPORTER_ZIPKIN_ENDPOINT | Endpoint for Zipkin traces | `http://localhost:9411/api/v2/spans` | [String][] |
250-
| OTEL_EXPORTER_ZIPKIN_TIMEOUT | Maximum time (in milliseconds) the Zipkin exporter will wait for each batch export | 10000 | [Integer][] |
270+
| OTEL_EXPORTER_ZIPKIN_TIMEOUT | Maximum time (in milliseconds) the Zipkin exporter will wait for each batch export | 10000 | [Timeout][] |
251271

252272
Additionally, the following environment variables are reserved for future
253273
usage in Zipkin Exporter configuration:
@@ -327,9 +347,9 @@ Additional known values for `OTEL_LOGS_EXPORTER` are:
327347

328348
### Exemplar
329349

330-
| Name | Description | Default | Type | Notes |
331-
|--------------------------------|-----------------------------------------------------|-----------------|----------|-------|
332-
| `OTEL_METRICS_EXEMPLAR_FILTER` | Filter for which measurements can become Exemplars. | `"trace_based"` | [Enum][] | |
350+
| Name | Description | Default | Type |
351+
|--------------------------------|-----------------------------------------------------|-----------------|----------|
352+
| `OTEL_METRICS_EXEMPLAR_FILTER` | Filter for which measurements can become Exemplars. | `"trace_based"` | [Enum][] |
333353

334354
Known values for `OTEL_METRICS_EXEMPLAR_FILTER` are:
335355

@@ -342,10 +362,10 @@ Known values for `OTEL_METRICS_EXEMPLAR_FILTER` are:
342362
Environment variables specific for the push metrics exporters (OTLP, stdout, in-memory)
343363
that use [periodic exporting MetricReader](../metrics/sdk.md#periodic-exporting-metricreader).
344364

345-
| Name | Description | Default | Type | Notes |
346-
|-------------------------------|-------------------------------------------------------------------------------|---------|--------------|-------|
347-
| `OTEL_METRIC_EXPORT_INTERVAL` | The time interval (in milliseconds) between the start of two export attempts. | 60000 | [Duration][] | |
348-
| `OTEL_METRIC_EXPORT_TIMEOUT` | Maximum allowed time (in milliseconds) to export data. | 30000 | [Duration][] | |
365+
| Name | Description | Default | Type |
366+
|-------------------------------|-------------------------------------------------------------------------------|---------|--------------|
367+
| `OTEL_METRIC_EXPORT_INTERVAL` | The time interval (in milliseconds) between the start of two export attempts. | 60000 | [Duration][] |
368+
| `OTEL_METRIC_EXPORT_TIMEOUT` | Maximum allowed time (in milliseconds) to export data. | 30000 | [Timeout][] |
349369

350370
## Declarative configuration
351371

@@ -399,5 +419,6 @@ OTEL_{LANGUAGE}_{FEATURE}
399419
[Float]: #float
400420
[Integer]: #integer
401421
[Duration]: #duration
422+
[Timeout]: #timeout
402423
[String]: #string
403424
[Enum]: #enum

‎specification/protocol/exporter.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@ Each configuration option MUST be overridable by a signal specific option.
3636
- **Insecure**: Whether to enable client transport security for the exporter's gRPC connection. This option only applies to OTLP/gRPC when an endpoint is provided without the `http` or `https` scheme - OTLP/HTTP always uses the scheme provided for the `endpoint`. Implementations MAY choose to not implement the `insecure` option if it is not required or supported by the underlying gRPC client implementation.
3737
- Default: `false`
3838
- Env vars: `OTEL_EXPORTER_OTLP_INSECURE` `OTEL_EXPORTER_OTLP_TRACES_INSECURE` `OTEL_EXPORTER_OTLP_METRICS_INSECURE` `OTEL_EXPORTER_OTLP_LOGS_INSECURE` [2]
39-
- Type: [Boolean[]
39+
- Type: [Boolean][]
4040

4141
- **Certificate File**: The trusted certificate to use when verifying a server's TLS credentials. Should only be used for a secure connection.
4242
- Default: n/a
@@ -66,7 +66,7 @@ Each configuration option MUST be overridable by a signal specific option.
6666
- **Timeout**: Maximum time the OTLP exporter will wait for each batch export.
6767
- Default: 10s
6868
- Env vars: `OTEL_EXPORTER_OTLP_TIMEOUT` `OTEL_EXPORTER_OTLP_TRACES_TIMEOUT` `OTEL_EXPORTER_OTLP_METRICS_TIMEOUT` `OTEL_EXPORTER_OTLP_LOGS_TIMEOUT`
69-
- Type: [Duration][]
69+
- Type: [Timeout][]
7070

7171
- **Protocol**: The transport protocol. Options MUST be one of: `grpc`, `http/protobuf`, `http/json`.
7272
See [Specify Protocol](./exporter.md#specify-protocol) for more details.
@@ -209,7 +209,7 @@ OTel-OTLP-Exporter-Python/1.2.3
209209
The format of the header SHOULD follow [RFC 7231][rfc-7231]. The conventions used for specifying the OpenTelemetry SDK language and version are available in the [Resource semantic conventions][resource-semconv].
210210

211211
[Boolean]: ../configuration/sdk-environment-variables.md#boolean
212-
[Duration]: ../configuration/sdk-environment-variables.md#duration
212+
[Timeout]: ../configuration/sdk-environment-variables.md#timeout
213213
[String]: ../configuration/sdk-environment-variables.md#string
214214
[Enum]: ../configuration/sdk-environment-variables.md#enum
215215

0 commit comments

Comments
 (0)