[configuration] Clarify that the boolean value environment variable guidance is not applicable to other configuration interfaces #4723
+147
−85
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,126 @@ | ||
| <!--- Hugo front matter used to generate the website version of this page: | ||
| title: Common Configuration Specification | ||
| linkTitle: Env var | ||
| aliases: | ||
| - /docs/reference/specification/common | ||
| - /docs/specs/otel/common-configuration | ||
| ---> | ||
|
|
||
| # OpenTelemetry Common Configuration Specification | ||
|
|
||
| **Status**: [Stable](../document-status.md) except where otherwise specified | ||
|
|
||
| <details> | ||
| <summary>Table of Contents</summary> | ||
|
|
||
| <!-- toc --> | ||
|
|
||
| - [Type-specific guidance](#type-specific-guidance) | ||
| * [Numeric](#numeric) | ||
| + [Integer](#integer) | ||
| + [Duration](#duration) | ||
| + [Timeout](#timeout) | ||
| * [String](#string) | ||
| + [Enum](#enum) | ||
|
|
||
| <!-- tocstop --> | ||
|
|
||
| </details> | ||
|
|
||
| The goal of this specification is to describe common guidance that is applicable | ||
| to all OpenTelemetry SDK configuration sources. | ||
|
|
||
| Implementations MAY choose to allow configuration via any source in this specification, but are not required to. | ||
| If they do, they SHOULD follow the guidance listed in this document. | ||
|
|
||
| ## Type-specific guidance | ||
|
|
||
| ### Numeric | ||
|
|
||
| Configuration sources accepting numeric values are sub-classified into: | ||
|
|
||
| * [Integer](#integer) | ||
| * [Duration](#duration) | ||
| * [Timeout](#timeout) | ||
|
|
||
| The following guidance applies to all numeric types. | ||
|
|
||
| > 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. | ||
|
|
||
| For sources 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 generate a warning and gracefully | ||
| ignore the setting, i.e., treat them as not set. In particular, implementations | ||
| SHOULD NOT assign a custom interpretation e.g. to negative values if a negative | ||
| value does not naturally apply to a configuration and does not have an | ||
| explicitly specified meaning, but treat it like any other invalid value. | ||
|
|
||
| For example, a value specifying a buffer size must naturally be non-negative. | ||
| Treating a negative value as "buffer everything" would be an example of such a | ||
| discouraged custom interpretation. Instead the default buffer size should be | ||
| used. | ||
|
|
||
| Note that this could make a difference even if the custom interpretation is | ||
| identical with the default value, because it might reset a value set from other | ||
| configuration sources with the default. | ||
|
|
||
| #### Integer | ||
|
|
||
| If an implementation chooses to support an integer-valued configuration source, | ||
| 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 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: | ||
|
|
||
| * [Enum][]. | ||
|
|
||
| Normally, string values include notes describing how they are interpreted by | ||
| implementations. | ||
|
|
||
| #### Enum | ||
|
|
||
| Enum values SHOULD be interpreted in a case-insensitive manner. | ||
|
||
|
|
||
| For configuration sources which accept a known value out of a set, i.e., an enum | ||
| value, implementations MAY support additional values not listed here. | ||
|
|
||
| For sources accepting an enum value, if the user provides a value | ||
| the implementation does not recognize, the implementation MUST generate | ||
| a warning and gracefully ignore the setting. | ||
mx-psi marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
| When reporting configuration errors, implementations SHOULD display the original | ||
| user-provided value to aid debugging. | ||
|
|
||
| If a null object (empty, no-op) value is acceptable, then the enum value | ||
| representing it MUST be `"none"`. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"via any source in this specification" What does this refer to? The other configuration interfaces?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It appears that this sentence was adapted from the env var spec:
In which case, "source" refers to a data type?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Any 'configuration source' was the intended meaning. Do you have suggestions on how to reword this to make it clearer?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I added 'configuration' to that sentence let me know if that is clearer