[configuration] Clarify that the boolean value environment variable guidance is not applicable to other configuration interfaces

CHANGELOG.md

@@ -35,6 +35,9 @@ release.
 
 ### SDK Configuration
 
+- Clarifies that guidance related to boolean environment variables is not applicable
+  to other configuration interfaces. ([#4723](https://github.com/open-telemetry/opentelemetry-specification/pull/4723))
+
 ### Common
 
 ### Supplementary Guidelines

specification/configuration/common.md

@@ -0,0 +1,122 @@
+<!--- 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 configuration 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 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
+
+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.
+
+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"`.

specification/configuration/sdk-environment-variables.md

@@ -17,14 +17,9 @@ aliases:
 
 - [Implementation guidelines](#implementation-guidelines)
 - [Parsing empty value](#parsing-empty-value)
-- [Configuration types](#configuration-types)
+- [Type-specific guidance](#type-specific-guidance)
   * [Boolean](#boolean)
   * [Numeric](#numeric)
-    + [Integer](#integer)
-    + [Duration](#duration)
-    + [Timeout](#timeout)
-  * [String](#string)
-    + [Enum](#enum)
 - [General SDK Configuration](#general-sdk-configuration)
 - [Batch Span Processor](#batch-span-processor)
 - [Batch LogRecord Processor](#batch-logrecord-processor)
@@ -46,10 +41,11 @@ aliases:
 
 </details>
 
-The goal of this specification is to unify the environment variable names between different OpenTelemetry implementations.
+The goal of this specification is to unify the environment variable names and value parsing between different OpenTelemetry implementations.
 
 Implementations 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.
+If they do, they SHOULD use the names and value parsing behavior specified in this document.
+They SHOULD also follow the [common configuration specification](common.md).
 
 ## Implementation guidelines
 
@@ -61,7 +57,7 @@ The environment-based configuration MUST have a direct code configuration equiva
 
 The SDK MUST interpret an empty value of an environment variable the same way as when the variable is unset.
 
-## Configuration types
+## Type-specific guidance
 
 ### Boolean
 
@@ -79,93 +75,34 @@ upgrade.
 
 ### Numeric
 
-Variables accepting numeric values are sub-classified into:
-
-* [Integer](#integer)
-* [Duration](#duration)
-* [Timeout](#timeout)
-
-The following guidance applies to all numeric types.
+The following guidance applies to all numeric types and extends the [common
+configuration specification 'Numeric' guidance](common.md#numeric).
 
 > 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 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 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 environment variable,
-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).
+implementation cannot parse, the implementation SHOULD generate a warning and gracefully
+ignore the setting, i.e., treat them as not set.
 
 ### 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.
+The following guidance extends the [common configuration specification 'Enum'
+guidance](common.md#enum).
 
-For variables which accept a known value out of a set, i.e., an enum value,
-implementations MAY support additional values not listed here.
+Enum values SHOULD be interpreted in a case-insensitive manner.
 
-For variables accepting an enum value, if the user provides a value
+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.
-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"`.
 
 ## General SDK Configuration
 
@@ -426,8 +363,8 @@ OTEL_{LANGUAGE}_{FEATURE}
 
 [Boolean]: #boolean
 [Float]: #float
-[Integer]: #integer
-[Duration]: #duration
-[Timeout]: #timeout
-[String]: #string
-[Enum]: #enum
+[Integer]: common.md#integer
+[Duration]: common.md#duration
+[Timeout]: common.md#timeout
+[String]: common.md#string
+[Enum]: common.md#enum

specification/metrics/sdk_exporters/otlp.md

@@ -72,4 +72,4 @@ The recognized (case-insensitive) values for `OTEL_EXPORTER_OTLP_METRICS_DEFAULT
 
 - [OTEP0131 OTLP Exporters Configurable Export Behavior](../../../oteps/metrics/0131-otlp-export-behavior.md)
 
-[Enum]: ../../configuration/sdk-environment-variables.md#enum
+[Enum]: ../../configuration/common.md#enum

specification/protocol/exporter.md

@@ -217,9 +217,9 @@ MyDistribution/x.y.z OTel-OTLP-Exporter-Python/1.2.3
 ```
 
 [Boolean]: ../configuration/sdk-environment-variables.md#boolean
-[Timeout]: ../configuration/sdk-environment-variables.md#timeout
-[String]: ../configuration/sdk-environment-variables.md#string
-[Enum]: ../configuration/sdk-environment-variables.md#enum
+[Timeout]: ../configuration/common.md#timeout
+[String]: ../configuration/common.md#string
+[Enum]: ../configuration/common.md#enum
 
 [resource-semconv]: https://github.com/open-telemetry/semantic-conventions/blob/main/docs/resource/README.md#telemetry-sdk
 [otlphttp-req]: https://github.com/open-telemetry/opentelemetry-proto/blob/main/docs/specification.md#otlphttp-request