Skip to content

Commit

Permalink
Clarify boundaries of numeric env vars (#4331)
Browse files Browse the repository at this point in the history 
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]>
  • Loading branch information
@jack-berg @reyang @pellared
3 people authored Jan 15, 2025
1 parent 7a1caee commit d46ad22
Show file tree
Hide file tree
Showing 3 changed files with 69 additions and 44 deletions.
4 changes: 4 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,10 @@ release.

### SDK Configuration

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

### Common

### Supplementary Guidelines
Expand Down
103 changes: 62 additions & 41 deletions specification/configuration/sdk-environment-variables.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@ aliases:
* [Numeric](#numeric)
+ [Integer](#integer)
+ [Duration](#duration)
+ [Timeout](#timeout)
* [String](#string)
+ [Enum](#enum)
- [General SDK Configuration](#general-sdk-configuration)
Expand Down Expand Up @@ -82,6 +83,7 @@ Variables accepting numeric values are sub-classified into:

* [Integer](#integer)
* [Duration](#duration)
* [Timeout](#timeout)

The following guidance applies to all numeric types.

Expand Down Expand Up @@ -110,18 +112,36 @@ configuration sources with the default.
#### Integer

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

#### 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.
Any value that represents a duration 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.

#### Timeout

Timeout values are similar to [duration](#duration) values, but are treated as a
separate type because of differences in how they interpret timeout zero values (
see below).

Any value that represents 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.

Implementations SHOULD interpret timeout zero values (i.e. `0` indicating 0
milliseconds) as no limit (i.e. infinite). In practice, implementations MAY
treat no limit as "a very long time" and substitute a very large duration (
e.g. the maximum milliseconds representable by a 32-bit integer).

### String

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

## Batch Span Processor

| Name | Description | Default | Type | Notes |
|--------------------------------|------------------------------------------------------------------|---------|--------------|-------------------------------------------------------|
| OTEL_BSP_SCHEDULE_DELAY | Delay interval (in milliseconds) between two consecutive exports | 5000 | [Duration][] | |
| OTEL_BSP_EXPORT_TIMEOUT | Maximum allowed time (in milliseconds) to export data | 30000 | [Duration][] | |
| OTEL_BSP_MAX_QUEUE_SIZE | Maximum queue size | 2048 | [Integer][] | |
| OTEL_BSP_MAX_EXPORT_BATCH_SIZE | Maximum batch size | 512 | [Integer][] | Must be less than or equal to OTEL_BSP_MAX_QUEUE_SIZE |
| Name | Description | Default | Type | Notes |
|--------------------------------|------------------------------------------------------------------|---------|--------------|-----------------------------------------------------------------------------------|
| OTEL_BSP_SCHEDULE_DELAY | Delay interval (in milliseconds) between two consecutive exports | 5000 | [Duration][] | |
| OTEL_BSP_EXPORT_TIMEOUT | Maximum allowed time (in milliseconds) to export data | 30000 | [Timeout][] | |
| OTEL_BSP_MAX_QUEUE_SIZE | Maximum queue size | 2048 | [Integer][] | Valid values are positive. |
| 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. |

## Batch LogRecord Processor

| Name | Description | Default | Type | Notes |
|---------------------------------|------------------------------------------------------------------|---------|--------------|--------------------------------------------------------|
| OTEL_BLRP_SCHEDULE_DELAY | Delay interval (in milliseconds) between two consecutive exports | 1000 | [Duration][] | |
| OTEL_BLRP_EXPORT_TIMEOUT | Maximum allowed time (in milliseconds) to export data | 30000 | [Duration][] | |
| OTEL_BLRP_MAX_QUEUE_SIZE | Maximum queue size | 2048 | [Integer][] | |
| OTEL_BLRP_MAX_EXPORT_BATCH_SIZE | Maximum batch size | 512 | [Integer][] | Must be less than or equal to OTEL_BLRP_MAX_QUEUE_SIZE |
| Name | Description | Default | Type | Notes |
|---------------------------------|------------------------------------------------------------------|---------|--------------|------------------------------------------------------------------------------------|
| OTEL_BLRP_SCHEDULE_DELAY | Delay interval (in milliseconds) between two consecutive exports | 1000 | [Duration][] | |
| OTEL_BLRP_EXPORT_TIMEOUT | Maximum allowed time (in milliseconds) to export data | 30000 | [Timeout][] | |
| OTEL_BLRP_MAX_QUEUE_SIZE | Maximum queue size | 2048 | [Integer][] | Valid values are positive. |
| 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. |

## Attribute Limits

Expand All @@ -211,32 +231,32 @@ 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 | Type |
|-----------------------------------|--------------------------------------|----------|-------------|
| OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT | Maximum allowed attribute value size | no limit | [Integer][] |
| OTEL_ATTRIBUTE_COUNT_LIMIT | Maximum allowed attribute count | 128 | [Integer][] |
| Name | Description | Default | Type | Notes |
|-----------------------------------|--------------------------------------|----------|-------------|--------------------------------|
| OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT | Maximum allowed attribute value size | no limit | [Integer][] | Valid values are non-negative. |
| OTEL_ATTRIBUTE_COUNT_LIMIT | Maximum allowed attribute count | 128 | [Integer][] | Valid values are non-negative. |

## Span Limits

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

| Name | Description | Default | Type |
|----------------------------------------|------------------------------------------------|----------|-------------|
| OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT | Maximum allowed attribute value size | no limit | [Integer][] |
| OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT | Maximum allowed span attribute count | 128 | [Integer][] |
| OTEL_SPAN_EVENT_COUNT_LIMIT | Maximum allowed span event count | 128 | [Integer][] |
| OTEL_SPAN_LINK_COUNT_LIMIT | Maximum allowed span link count | 128 | [Integer][] |
| OTEL_EVENT_ATTRIBUTE_COUNT_LIMIT | Maximum allowed attribute per span event count | 128 | [Integer][] |
| OTEL_LINK_ATTRIBUTE_COUNT_LIMIT | Maximum allowed attribute per span link count | 128 | [Integer][] |
| Name | Description | Default | Type | Notes |
|----------------------------------------|------------------------------------------------|----------|-------------|--------------------------------|
| OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT | Maximum allowed attribute value size | no limit | [Integer][] | Valid values are non-negative. |
| OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT | Maximum allowed span attribute count | 128 | [Integer][] | Valid values are non-negative. |
| OTEL_SPAN_EVENT_COUNT_LIMIT | Maximum allowed span event count | 128 | [Integer][] | Valid values are non-negative. |
| OTEL_SPAN_LINK_COUNT_LIMIT | Maximum allowed span link count | 128 | [Integer][] | Valid values are non-negative. |
| OTEL_EVENT_ATTRIBUTE_COUNT_LIMIT | Maximum allowed attribute per span event count | 128 | [Integer][] | Valid values are non-negative. |
| OTEL_LINK_ATTRIBUTE_COUNT_LIMIT | Maximum allowed attribute per span link count | 128 | [Integer][] | Valid values are non-negative. |

## LogRecord Limits

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

| Name | Description | Default | Type |
|---------------------------------------------|--------------------------------------------|----------|-------------|
| OTEL_LOGRECORD_ATTRIBUTE_VALUE_LENGTH_LIMIT | Maximum allowed attribute value size | no limit | [Integer][] |
| OTEL_LOGRECORD_ATTRIBUTE_COUNT_LIMIT | Maximum allowed log record attribute count | 128 | [Integer][] |
| Name | Description | Default | Type | Notes |
|---------------------------------------------|--------------------------------------------|----------|-------------|--------------------------------|
| OTEL_LOGRECORD_ATTRIBUTE_VALUE_LENGTH_LIMIT | Maximum allowed attribute value size | no limit | [Integer][] | Valid values are non-negative. |
| OTEL_LOGRECORD_ATTRIBUTE_COUNT_LIMIT | Maximum allowed log record attribute count | 128 | [Integer][] | Valid values are non-negative. |

## OTLP Exporter

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

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

### Exemplar

| Name | Description | Default | Type | Notes |
|--------------------------------|-----------------------------------------------------|-----------------|----------|-------|
| `OTEL_METRICS_EXEMPLAR_FILTER` | Filter for which measurements can become Exemplars. | `"trace_based"` | [Enum][] | |
| Name | Description | Default | Type |
|--------------------------------|-----------------------------------------------------|-----------------|----------|
| `OTEL_METRICS_EXEMPLAR_FILTER` | Filter for which measurements can become Exemplars. | `"trace_based"` | [Enum][] |

Known values for `OTEL_METRICS_EXEMPLAR_FILTER` are:

Expand All @@ -342,10 +362,10 @@ Known values for `OTEL_METRICS_EXEMPLAR_FILTER` are:
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 | Type | Notes |
|-------------------------------|-------------------------------------------------------------------------------|---------|--------------|-------|
| `OTEL_METRIC_EXPORT_INTERVAL` | The time interval (in milliseconds) between the start of two export attempts. | 60000 | [Duration][] | |
| `OTEL_METRIC_EXPORT_TIMEOUT` | Maximum allowed time (in milliseconds) to export data. | 30000 | [Duration][] | |
| Name | Description | Default | Type |
|-------------------------------|-------------------------------------------------------------------------------|---------|--------------|
| `OTEL_METRIC_EXPORT_INTERVAL` | The time interval (in milliseconds) between the start of two export attempts. | 60000 | [Duration][] |
| `OTEL_METRIC_EXPORT_TIMEOUT` | Maximum allowed time (in milliseconds) to export data. | 30000 | [Timeout][] |

## Declarative configuration

Expand Down Expand Up @@ -399,5 +419,6 @@ OTEL_{LANGUAGE}_{FEATURE}
[Float]: #float
[Integer]: #integer
[Duration]: #duration
[Timeout]: #timeout
[String]: #string
[Enum]: #enum
6 changes: 3 additions & 3 deletions specification/protocol/exporter.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ Each configuration option MUST be overridable by a signal specific option.
- **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.
- Default: `false`
- Env vars: `OTEL_EXPORTER_OTLP_INSECURE` `OTEL_EXPORTER_OTLP_TRACES_INSECURE` `OTEL_EXPORTER_OTLP_METRICS_INSECURE` `OTEL_EXPORTER_OTLP_LOGS_INSECURE` [2]
- Type: [Boolean[]
- Type: [Boolean][]

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

- **Protocol**: The transport protocol. Options MUST be one of: `grpc`, `http/protobuf`, `http/json`.
See [Specify Protocol](./exporter.md#specify-protocol) for more details.
Expand Down Expand Up @@ -209,7 +209,7 @@ OTel-OTLP-Exporter-Python/1.2.3
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].

[Boolean]: ../configuration/sdk-environment-variables.md#boolean
[Duration]: ../configuration/sdk-environment-variables.md#duration
[Timeout]: ../configuration/sdk-environment-variables.md#timeout
[String]: ../configuration/sdk-environment-variables.md#string
[Enum]: ../configuration/sdk-environment-variables.md#enum

Expand Down

0 comments on commit d46ad22

Please sign in to comment.