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 2 commits into
base: main
Choose a base branch
from
+46 −38
Open

Clarify boundaries of numeric env vars #4331

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 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
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
82 changes: 45 additions & 37 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 value](#numeric-value)
* [Enum value](#enum-value)
* [Duration](#duration)
* [Timeout values](#timeout-values)
- [General SDK Configuration](#general-sdk-configuration)
- [Batch Span Processor](#batch-span-processor)
- [Batch LogRecord Processor](#batch-logrecord-processor)
Expand Down Expand Up @@ -108,6 +109,13 @@ 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 values

For variables that represent a timeout (e.g. exporter timeout), implementations
Copy link
Member

Choose a reason for hiding this comment

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

There is the "Duration" section right above the "Timeout values" section, it has mentioned things such as "an integer representing a number of milliseconds" and "if a negative value is provided, the implementation MUST generate a warning". Are "Duration" and "Timeout values" mutually exclusive?

Copy link
Member Author

Choose a reason for hiding this comment

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

A timeout is a type of duration. So maybe I should move this content to the duration section, or as a subsection within duration.

Copy link
Member

Choose a reason for hiding this comment

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

A timeout is a type of duration. So maybe I should move this content to the duration section, or as a subsection within duration.

Yep, that'll bring clarity, thanks!

Copy link
Member

Choose a reason for hiding this comment

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

A timeout is a type of duration.

Am I correct that _DELAY are the only configurations that of type duration but are not of type timeout? Do we want to have zero delay?

Copy link
Member Author

Choose a reason for hiding this comment

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

do we want to have zero delay?

I came to the conclusion that while its odd, its still valid-ish. Take the batch span processor's delay interval, which represents the gap in time from the conclusion of one export to the start of the next. Assume that exports over the network take some amount of time like 2ms. Setting the batch span processor's delay to zero is just saying: "as soon as one export resolves, start the next".

Copy link
Member

Choose a reason for hiding this comment

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

+1 on supporting zero delay, folks from the operating system background would find it common https://learn.microsoft.com/windows/win32/api/synchapi/nf-synchapi-sleepex#parameters.

SHOULD validate that values are positive unless they have good reasons not to (
e.g. backwards compatibility with semantics where a negative or zero value means
Copy link
Member

Choose a reason for hiding this comment

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

I think this will lead to inconsistency and confusion, let's say if Java SDK decided to treat -1 as indefinite while Python SDK decided to fall back to defaults (e.g. 30,000 milliseconds).

I think it is better to ask all SDKs to have a consistent behavior.

Copy link
Member Author

Choose a reason for hiding this comment

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

I think it is better to ask all SDKs to have a consistent behavior.

Consistency is best, but its difficult to make consistency recommendations post hoc. Consider our change in advice to make http/protobuf default OTLP protocol, when it was previously grpc. We have portions of the ecosystem which made the switch, either because they went stable after the change in advice or decided the change wasn't impactful enough to be breaking for users, and other portions which stuck with grpc as the default (like opentelemetry-java).

If all maintainers agree that changing their semantics is a bugfix, let's get rid of this qualification.

Copy link
Member

@reyang reyang Dec 10, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

I agree with the grpc and http/protobuf example. However, I think for timeouts there is a high chance that we can achieve consistency. For example, if 3 language implementation SIGs are saying "-1 means indefinite to us" while other SIGs treat negative values as invalid, it is possible to have all implementations treating -1 as indefinite.

Copy link
Member Author

Choose a reason for hiding this comment

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

For example, if 3 language implementation SIGs are saying "-1 means indefinite to us" while other SIGs treat negative values as invalid, it is possible to have all implementations treating -1 as indefinite.

Its true. Its always acceptable to loosen the restriction.

Copy link
Member

@pellared pellared Dec 10, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

I think we should define it similarly like in other types e.g.

The value is positive - 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; if a zero value is provided, the implementation SHOULD (not "MUST" because of backwards compatibility when it is used to represent infinity or zero) generate a warning, gracefully ignore the setting and use the default value if it is defined.

let's say if Java SDK decided to treat -1 as indefinite

This should be seen as a bug given the definition of the duration type:

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.

The only issue is when 0 is handled as Infinite or zero. See:

Copy link
Member Author

Choose a reason for hiding this comment

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

To summarize the arguments:

  • If negative, generate a warning and use the default. This is already the specified behavior for duration properties, which includes timeout.
  • If zero, interpret to mean indefinite. There is prior art to support this interpretation. Also, its less controversial for an implementation which currently rejects 0 as invalid to begin accepting it than it is for an implementation which currently accepts zero to begin rejecting it. I.e. loosening restrictiveness is always ok. Increasing restrictiveness may be interpreted as a breaking change.

Given these arguments, does anyone feel strongly that we should reject 0 as invalid? Tagging folks who originally supported this idea: @tigrannajaryan, @lmolkova, @cijothomas, @pellared

indefinite).

## General SDK Configuration

| Name | Description | Default | Notes |
Expand Down Expand Up @@ -148,27 +156,27 @@ Depending on the value of `OTEL_TRACES_SAMPLER`, `OTEL_TRACES_SAMPLER_ARG` may b
- 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.
- `pollingIntervalMs`: in milliseconds indicating how often the sampler will poll the backend for updates to sampling strategy. Valid values are positive.
- `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 |
| Name | Description | Default | Notes |
|--------------------------------|------------------------------------------------------------------|---------|-----------------------------------------------------------------------------------|
| OTEL_BSP_SCHEDULE_DELAY | Delay interval (in milliseconds) between two consecutive exports | 5000 | Valid values are non-negative. |
Copy link
Member

Choose a reason for hiding this comment

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

Maybe we should add a Type column instead? The type definitions contain more information which is relevant.

Copy link
Member Author

Choose a reason for hiding this comment

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

I agree. Opened #4336 to address separately.

| OTEL_BSP_EXPORT_TIMEOUT | Maximum allowed time (in milliseconds) to export data | 30000 | Valid values are positive. |
| OTEL_BSP_MAX_QUEUE_SIZE | Maximum queue size | 2048 | Valid values are positive. |
| OTEL_BSP_MAX_EXPORT_BATCH_SIZE | Maximum batch size | 512 | Must be less than or equal to OTEL_BSP_MAX_QUEUE_SIZE. Valid values are positive. |

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

## Attribute Limits

Expand All @@ -177,43 +185,43 @@ 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 | |
| Name | Description | Default | Notes |
|-----------------------------------|--------------------------------------|----------|--------------------------------|
| OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT | Maximum allowed attribute value size | no limit | Valid values are non-negative. |
| OTEL_ATTRIBUTE_COUNT_LIMIT | Maximum allowed attribute count | 128 | 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 | 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 | |
| Name | Description | Default | Notes |
|----------------------------------------|------------------------------------------------|----------|--------------------------------|
| OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT | Maximum allowed attribute value size | no limit | Valid values are non-negative. |
| OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT | Maximum allowed span attribute count | 128 | Valid values are non-negative. |
| OTEL_SPAN_EVENT_COUNT_LIMIT | Maximum allowed span event count | 128 | Valid values are non-negative. |
| OTEL_SPAN_LINK_COUNT_LIMIT | Maximum allowed span link count | 128 | Valid values are non-negative. |
| OTEL_EVENT_ATTRIBUTE_COUNT_LIMIT | Maximum allowed attribute per span event count | 128 | Valid values are non-negative. |
| OTEL_LINK_ATTRIBUTE_COUNT_LIMIT | Maximum allowed attribute per span link count | 128 | 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 | 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 | |
| Name | Description | Default | Notes |
|---------------------------------------------|--------------------------------------------|----------|--------------------------------|
| OTEL_LOGRECORD_ATTRIBUTE_VALUE_LENGTH_LIMIT | Maximum allowed attribute value size | no limit | Valid values are non-negative. |
| OTEL_LOGRECORD_ATTRIBUTE_COUNT_LIMIT | Maximum allowed log record attribute count | 128 | Valid values are non-negative. |

## 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 |
| Name | Description | Default | Notes |
| ----------------------------- | ---------------------------------------------------------------------------------- |------------------------------------- |-------|
| 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 | Valid values are positive. |

Additionally, the following environment variables are reserved for future
usage in Zipkin Exporter configuration:
Expand Down Expand Up @@ -308,10 +316,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 | 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 | |
| Name | Description | Default | Notes |
|-------------------------------|-------------------------------------------------------------------------------|---------|----------------------------|
| `OTEL_METRIC_EXPORT_INTERVAL` | The time interval (in milliseconds) between the start of two export attempts. | 60000 | Valid values are positive. |
| `OTEL_METRIC_EXPORT_TIMEOUT` | Maximum allowed time (in milliseconds) to export data. | 30000 | Valid values are positive. |

## Declarative configuration

Expand Down
2 changes: 1 addition & 1 deletion specification/protocol/exporter.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ Each configuration option MUST be overridable by a signal specific option.
- Default: No value [3]
- Env vars: `OTEL_EXPORTER_OTLP_COMPRESSION` `OTEL_EXPORTER_OTLP_TRACES_COMPRESSION` `OTEL_EXPORTER_OTLP_METRICS_COMPRESSION` `OTEL_EXPORTER_OTLP_LOGS_COMPRESSION`

- **Timeout**: Maximum time the OTLP exporter will wait for each batch export.
- **Timeout**: Maximum time the OTLP exporter will wait for each batch export. Valid values are positive.
- Default: 10s
- Env vars: `OTEL_EXPORTER_OTLP_TIMEOUT` `OTEL_EXPORTER_OTLP_TRACES_TIMEOUT` `OTEL_EXPORTER_OTLP_METRICS_TIMEOUT` `OTEL_EXPORTER_OTLP_LOGS_TIMEOUT`

Expand Down
Loading