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

Define OTEL_CONFIG_FILE environment variable #3805

Closed
wants to merge 6 commits into from
Closed

Define OTEL_CONFIG_FILE environment variable #3805

Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
7eca953
Define OTEL_CONFIG_FILE environment variable
jack-berg Jan 5, 2024
4f43181
Fix typo
jack-berg Jan 8, 2024
26e87df
Add changelog entry
jack-berg Jan 8, 2024
c6bb3de
Merge branch 'main' of https://github.com/open-telemetry/opentelemetr…
jack-berg Jan 18, 2024
ae19265
PR feedback
jack-berg Jan 18, 2024
b32c801
Add entry to spec compliance matrix
jack-berg Jan 18, 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
93 changes: 65 additions & 28 deletions specification/configuration/sdk-environment-variables.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,39 @@ aliases:

# OpenTelemetry Environment Variable Specification

**Status**: [Mixed](../document-status.md)
**Status**: [Stable](../document-status.md) except where otherwise specified
Copy link
Member

Choose a reason for hiding this comment

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

Wouldn't Mixed be the best fit in that case?

Copy link
Member

Choose a reason for hiding this comment

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

+1. Seems like explicitly specifying status for each section is clearer.

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 while back I extended the metrics API with the the ability to specify histogram bucket boundary advice in #3216. At that point, the document was completely stable, except for the newly introduced experimental hint API. I argued that calling the document "mixed" makes the document seem less stable than it deserves:

Adjusted this document to be "mixed" status to reflect one new experimental API seems heavy handed.
Instead, we might consider saying that the document status is "Stable, except where specified". This would allow us to add experimental annotations to only relevant sections. Also, doing so arguably inspires more confidence in the overall stability of the document since the whole thing isn't tainted with the somewhat ominous "mixed" status.

I think this is true in general for documents which are > 50% stable.

However, we should be consistent so however we land on this, we should update docs with the outcome.


<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)
- [Metrics SDK Configuration](#metrics-sdk-configuration)
* [Exemplar](#exemplar)
* [Periodic exporting MetricReader](#periodic-exporting-metricreader)
- [File Configuration](#file-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.

Expand All @@ -17,22 +49,16 @@ If they do, they SHOULD use the names listed in this document.

## Implementation guidelines

**Status**: [Stable](../document-status.md)

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

**Status**: [Stable](../document-status.md)

The SDK MUST interpret an empty value of an environment variable the same way as when the variable is unset.

## Special configuration types

**Status**: [Stable](../document-status.md)

### 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.
Expand All @@ -47,9 +73,9 @@ Renaming or changing the default value MUST NOT happen without a major version u
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.
> 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
Expand Down Expand Up @@ -83,8 +109,6 @@ For example, the value `12000` indicates 12000 milliseconds, i.e., 12 seconds.

## General SDK Configuration

**Status**: [Stable](../document-status.md)

| 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. |
Expand Down Expand Up @@ -129,8 +153,6 @@ Depending on the value of `OTEL_TRACES_SAMPLER`, `OTEL_TRACES_SAMPLER_ARG` may b

## Batch Span Processor

**Status**: [Stable](../document-status.md)

| Name | Description | Default | Notes |
| ------------------------------ | ---------------------------------------------------------------- | ------- | ----------------------------------------------------- |
| OTEL_BSP_SCHEDULE_DELAY | Delay interval (in milliseconds) between two consecutive exports | 5000 | |
Expand All @@ -140,8 +162,6 @@ Depending on the value of `OTEL_TRACES_SAMPLER`, `OTEL_TRACES_SAMPLER_ARG` may b

## Batch LogRecord Processor

**Status**: [Stable](../document-status.md)

| Name | Description | Default | Notes |
| ------------------------------- | ---------------------------------------------------------------- | ------- | ------------------------------------------------------ |
| OTEL_BLRP_SCHEDULE_DELAY | Delay interval (in milliseconds) between two consecutive exports | 1000 | |
Expand All @@ -163,8 +183,6 @@ See the SDK [Attribute Limits](../common/README.md#attribute-limits) section for

## Span Limits

**Status**: [Stable](../document-status.md)

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

| Name | Description | Default | Notes |
Expand All @@ -178,8 +196,6 @@ See the SDK [Span Limits](../trace/sdk.md#span-limits) section for the definitio

## LogRecord Limits

**Status**: [Stable](../document-status.md)

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

| Name | Description | Default | Notes |
Expand All @@ -193,8 +209,6 @@ See [OpenTelemetry Protocol Exporter Configuration Options](../protocol/exporter

## Zipkin Exporter

**Status**: [Stable](../document-status.md)

| Name | Description | Default |
| ----------------------------- | ---------------------------------------------------------------------------------- |------------------------------------- |
| OTEL_EXPORTER_ZIPKIN_ENDPOINT | Endpoint for Zipkin traces | `http://localhost:9411/api/v2/spans` |
Expand All @@ -220,8 +234,6 @@ _is no specified default, or configuration via environment variables_.

## Exporter Selection

**Status**: [Stable](../document-status.md)

We define environment variables for setting one or more exporters per signal.

| Name | Description | Default |
Expand Down Expand Up @@ -260,8 +272,6 @@ NOT be supported by new implementations.

## Metrics SDK Configuration

**Status**: [Mixed](../document-status.md)

### Exemplar

**Status**: [Experimental](../document-status.md)
Expand All @@ -278,8 +288,6 @@ Known values for `OTEL_METRICS_EXEMPLAR_FILTER` are:

### Periodic exporting MetricReader

**Status**: [Stable](../document-status.md)

Environment variables specific for the push metrics exporters (OTLP, stdout, in-memory)
that use [periodic exporting MetricReader](../metrics/sdk.md#periodic-exporting-metricreader).

Expand All @@ -288,6 +296,35 @@ that use [periodic exporting MetricReader](../metrics/sdk.md#periodic-exporting-
| `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 | |

## File Configuration

**Status**: [Experimental](../document-status.md)

Environment variables involved in [file configuration](file-configuration.md).

| Name | Description | Default | Notes |
|------------------|---------------------------------------------------------------|---------|-----------|
| OTEL_CONFIG_FILE | The path of the configuration file used to configure the SDK. | | See below |
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
| OTEL_CONFIG_FILE | The path of the configuration file used to configure the SDK. | | See below |
| OTEL_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 |

To make this very clear to all users.


If `OTEL_CONFIG_FILE` is set, the file at the specified path is used to
call [Parse](file-configuration.md#parse). The
resulting [configuration model](./file-configuration.md#configuration-model) is
used to call [Create](file-configuration.md#create) to produce fully configured
SDK components.

When `OTEL_CONFIG_FILE` is set, all other environment variables besides those
reference in the configuration file
jack-berg marked this conversation as resolved.
Show resolved Hide resolved
for [environment variable substitution](file-configuration.md#environment-variable-substitution)
MUST be ignored. Ignoring the environment variables is necessary because
Copy link
Contributor

Choose a reason for hiding this comment

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

If other env. vars. apart from the file are ignored then the file configuration has precedence over all other configuration methods.

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
Copy link
Contributor

@brunobat brunobat Jan 23, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

This seems to supperceed the programatic interface concept defined here: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk-configuration.md

All configuration methods should be built on top of a common programatic interface that grant similar configuration capabilities across the board, not just for file configurations.

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_CONFIG_FILE`.

## Language Specific Environment Variables

To ensure consistent naming across projects, this specification recommends that language specific environment variables are formed using the following convention:
Expand Down
Loading