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

Unset and empty environment variables are equivalent #2045

Merged
merged 16 commits into from
Nov 4, 2021
Merged

Unset and empty environment variables are equivalent #2045

Changes from 3 commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
745d500
Handling env var's empty value
pellared Oct 20, 2021
dd5d00d
Update sdk-environment-variables.md
pellared Oct 21, 2021
ce2381c
Update sdk-environment-variables.md
pellared Oct 21, 2021
83d6948
Update sdk-environment-variables.md
pellared Oct 21, 2021
cdaf5ac
Update sdk-environment-variables.md
pellared Oct 21, 2021
a83223b
Update specification/sdk-environment-variables.md
pellared Oct 22, 2021
0974a86
Update sdk-environment-variables.md
pellared Oct 22, 2021
d88b4ca
Update CHANGELOG.md
pellared Oct 22, 2021
c87bc4b
Fix lint
pellared Oct 22, 2021
57b8e6e
Merge branch 'main' into patch-1
pellared Oct 22, 2021
e73ecd2
Merge branch 'main' into patch-1
pellared Oct 22, 2021
3be87c4
Remove - for empty value as default
pellared Oct 26, 2021
5134e1d
Merge branch 'main' into patch-1
pellared Oct 26, 2021
66b4b52
Update sdk-environment-variables.md
pellared Nov 4, 2021
9fdf24b
Merge branch 'main' into patch-1
pellared Nov 4, 2021
10a3597
Merge branch 'main' into patch-1
carlosalberto Nov 4, 2021
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
36 changes: 24 additions & 12 deletions specification/sdk-environment-variables.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,18 +4,29 @@

The goal of this specification is to unify the environment variable names between different OpenTelemetry SDK implementations. SDKs MAY choose to allow configuration via the environment variables in this specification, but are not required to. If they do, they SHOULD use the names listed in this document.

## Parsing empty value

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

The SDK SHOULD interpret an empty value of an environment variable in the same way as if would be unset.

The `-` value in Default column in configuration table is interpreted as an empty value.

## Special configuration types

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

### Numeric value

If an SDK 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.
If an SDK chooses to support an integer-valued environment variable, it SHOULD support nonnegative values between `0`-`2³¹` and `-1` (inclusive).
`-1` MAY be often interpreted as an infinite value.
Individual SDKs MAY choose to support a larger range of values.

### Enum value

For variables which accept a known value out of a set, i.e., an enum value, SDK implementations MAY support additional values not listed here.
For variables accepting an enum value, if the user provides a value the SDK does not recognize, the SDK MUST generate a warning and gracefully ignore the setting.
`"none"` MAY be used as value that repesents an "empty" selection.

### Duration

Expand Down Expand Up @@ -47,6 +58,7 @@ Known values for OTEL_PROPAGATORS are:
- `"jaeger"`: [Jaeger](https://www.jaegertracing.io/docs/1.21/client-libraries/#propagation-format)
- `"xray"`: [AWS X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html#xray-concepts-tracingheader) (_third party_)
- `"ottrace"`: [OT Trace](https://github.com/opentracing?q=basic&type=&language=) (_third party_)
- `"none"`: No automatically configured propagator.

Known values for `OTEL_TRACES_SAMPLER` are:

Expand Down Expand Up @@ -75,7 +87,7 @@ Depending on the value of `OTEL_TRACES_SAMPLER`, `OTEL_TRACES_SAMPLER_ARG` may b
| Name | Description | Default | Notes |
| ------------------------------ | ---------------------------------------------- | ------- | ----------------------------------------------------- |
| OTEL_BSP_SCHEDULE_DELAY | Delay interval between two consecutive exports | 5000 | |
| OTEL_BSP_EXPORT_TIMEOUT | Maximum allowed time to export data | 30000 | |
| OTEL_BSP_EXPORT_TIMEOUT | Maximum allowed time to export data | 30000 | `-1` MAY be interpreted as an infinite value. |
| 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 |

Expand All @@ -88,8 +100,8 @@ See the SDK [Attribute Limits](common/common.md#attribute-limits) section for th

| Name | Description | Default | Notes |
| --------------------------------- | ------------------------------------ | ------- | ----- |
| OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT | Maximum allowed attribute value size | | Empty value is treated as infinity. Non-integer and negative values are invalid. |
| OTEL_ATTRIBUTE_COUNT_LIMIT | Maximum allowed span attribute count | 128 | |
| OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT | Maximum allowed attribute value size | - | Empty value is treated as infinity. `-1` MAY be interpreted as an infinite value. |
| OTEL_ATTRIBUTE_COUNT_LIMIT | Maximum allowed span attribute count | 128 | `-1` SHOULD be interpreted as an infinite value. |

## Span Limits <a name="span-collection-limits"></a>

Expand All @@ -99,12 +111,12 @@ See the SDK [Span Limits](trace/sdk.md#span-limits) section for the definition o

| Name | Description | Default | Notes |
| -------------------------------------- | ---------------------------------------------- | ------- | ----- |
| OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT | Maximum allowed attribute value size | | Empty value is treated as infinity. Non-integer and negative values are invalid. |
| 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 | |
| OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT | Maximum allowed attribute value size | - | Empty value is treated as infinity. `-1` MAY be interpreted as an infinite value. |
| OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT | Maximum allowed span attribute count | 128 | `-1` SHOULD be interpreted as an infinite value. |
| OTEL_SPAN_EVENT_COUNT_LIMIT | Maximum allowed span event count | 128 | `-1` SHOULD be interpreted as an infinite value. |
| OTEL_SPAN_LINK_COUNT_LIMIT | Maximum allowed span link count | 128 | `-1` SHOULD be interpreted as an infinite value. |
| OTEL_EVENT_ATTRIBUTE_COUNT_LIMIT | Maximum allowed attribute per span event count | 128 | `-1` SHOULD be interpreted as an infinite value. |
| OTEL_LINK_ATTRIBUTE_COUNT_LIMIT | Maximum allowed attribute per span link count | 128 | `-1` SHOULD be interpreted as an infinite value. |

## OTLP Exporter

Expand All @@ -119,7 +131,7 @@ See [OpenTelemetry Protocol Exporter Configuration Options](./protocol/exporter.
| OTEL_EXPORTER_JAEGER_AGENT_HOST | Hostname for the Jaeger agent | "localhost" |
| OTEL_EXPORTER_JAEGER_AGENT_PORT | Port for the Jaeger agent `compact` Thrift protocol | 6831 |
| OTEL_EXPORTER_JAEGER_ENDPOINT | HTTP endpoint for Jaeger traces | <!-- markdown-link-check-disable --> "http://localhost:14250"<!-- markdown-link-check-enable --> |
| OTEL_EXPORTER_JAEGER_TIMEOUT | Maximum time the Jaeger exporter will wait for each batch export | 10s |
| OTEL_EXPORTER_JAEGER_TIMEOUT | Maximum time the Jaeger exporter will wait for each batch export. `-1` MAY be interpreted as an infinite value. | 10s |
| OTEL_EXPORTER_JAEGER_USER | Username to be used for HTTP basic authentication | - |
| OTEL_EXPORTER_JAEGER_PASSWORD | Password to be used for HTTP basic authentication | - |

Expand All @@ -132,7 +144,7 @@ See [Jaeger Agent](https://www.jaegertracing.io/docs/latest/deployment/#agent) d
| Name | Description | Default |
| ----------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------ |
| OTEL_EXPORTER_ZIPKIN_ENDPOINT | Endpoint for Zipkin traces | <!-- markdown-link-check-disable --> "http://localhost:9411/api/v2/spans"<!-- markdown-link-check-enable --> |
| OTEL_EXPORTER_ZIPKIN_TIMEOUT | Maximum time the Zipkin exporter will wait for each batch export | 10s |
| OTEL_EXPORTER_ZIPKIN_TIMEOUT | Maximum time the Zipkin exporter will wait for each batch export. `-1` MAY be interpreted as an infinite value. | 10s |

Addtionally, the following environment variables are reserved for future
usage in Zipkin Exporter configuration:
Expand Down