Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Clarify boundaries of numeric env vars #4331

Open
wants to merge 7 commits into
base: main
Choose a base branch
from
Open

Clarify boundaries of numeric env vars #4331

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
143a790
Clarify boundaries of numeric env vars
jack-berg Dec 9, 2024
291ec6b
Fix toc
jack-berg Dec 10, 2024
e2df979
Merge branch 'main' of https://github.com/open-telemetry/opentelemetr…
jack-berg Jan 2, 2025
c3a0b21
Interpret timeout of zero as indefinite
jack-berg Jan 2, 2025
55d2972
Cleanup
jack-berg Jan 2, 2025
d064caa
Add changelog entry
jack-berg Jan 2, 2025
970b693
Merge branch 'main' into clarify-number-env-var-bounds
reyang Jan 8, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
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 indefinite.
([#4331](https://github.com/open-telemetry/opentelemetry-specification/pull/4331))

### Common

### Supplementary Guidelines
Expand Down
93 changes: 53 additions & 40 deletions specification/configuration/sdk-environment-variables.md
View file
Open in desktop
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](#duration)

The following guidance applies to all numeric types.

Expand Down Expand Up @@ -115,13 +117,23 @@ 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 is a sub-classification of [duration](#duration): All timeouts are also
durations, but not all durations are timeouts.

Comment on lines +129 to +131
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

is this important? I ask because it seems that 0 duration is defined as zero milliseconds, and so it's hard for me to think of timeouts as a "subclass" of duration since they don't have that behavior

Suggested change
Timeout is a sub-classification of [duration](#duration): All timeouts are also
durations, but not all durations are timeouts.
Timeout is a sub-classification of [duration](#duration): All timeouts are also
durations, but not all durations are timeouts.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

From duration we get:

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.

From timeout's perspective, the useful bits which are inherited are:

  • timeouts are integers representing a number of milliseconds
  • values are non-negative, warn if negative value is given

You make a good point that the zero value semantics are different for duration and timeout. We could keep it as is, where timeout essentially overrides the duration zero value semantics. Copy the bits of duration semantics we care about into timeout.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We could keep it as is, where timeout essentially overrides the duration zero value semantics

this would make sense to me if the timeout restricted ("narrowed") the behavior of its "super type", but that's not the case here, so it doesn't seem like a duration in my mind (a timeout can't be used in places where a duration would be used). probably I'm thinking too much OOP

For variables that represent a timeout (e.g. exporter timeout), implementations
jack-berg marked this conversation as resolved.
Show resolved Hide resolved
SHOULD interpret a value of zero as indefinite. In practice, implementations MAY
treat indefinite 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 +200,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 +223,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. |
Comment on lines +237 to +242
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

can we say anything useful about the 0 value for these env vars?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The zero value is valid here. Are you suggesting a change in semantics or improved phrasing to make it more clear that zero is valid?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ah, I wasn't sure if 0 mean none or unlimited here

but re-reading it seems that none is the obvious interpretation and may not need clarification

sort of related, it's a bit odd that the default value of OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT isn't expressible as a valid value, maybe it should allow -1 for unlimited? (might be a nice general property for declarative config to always be able to "get back" the default value when someone else has overridden it)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

sort of related, it's a bit odd that the default value of OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT isn't expressible as a valid value, maybe it should allow -1 for unlimited

I don't disagree - but I'm reluctant to try to tackle that in this PR 😛.

A user can use effectively express the default config with something like the max value of a 32 bit integer (2,147,483,647). Obviously its a lot more cumbersome than -1.


## 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 +259,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 +339,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 +354,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 +411,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
Open in desktop
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
Loading