open-telemetry · ADITYA-CODE-SOURCE · May 27, 2026 · Jun 3, 2026 · jack-berg · Jun 2, 2026
@@ -15,7 +15,7 @@ is the signal.
 |------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|
 | [build.md](build.md)                           | Always — build requirements and common tasks                                                                            |
 | [general-patterns.md](general-patterns.md)     | Always — style, nullability, visibility, AutoValue, locking, logging, internal & impl packages                          |
-| [api-design.md](api-design.md)                 | Public API additions, removals, renames, or deprecations or implementations; null guards; stable vs alpha compatibility |
+| [api-design.md](api-design.md)                 | Public API additions, removals, renames, or deprecations or implementations; configuration changes; null guards; stable vs alpha compatibility |
 | [gradle-conventions.md](gradle-conventions.md) | `build.gradle.kts` or `settings.gradle.kts` changes; new modules                                                        |
 | [testing-patterns.md](testing-patterns.md)     | Test files in scope — assertions, test utilities, test suites                                                           |
 | [other-tasks.md](other-tasks.md)               | Dev environment setup, benchmarks, composite builds, native image tests, OTLP protobuf updates                          |

@@ -17,6 +17,46 @@ Breaking changes are allowed in alpha modules but should still be approached car
 Breaking changes are not allowed in stable modules outside of a major version bump. The build
 enforces this via japicmp — see [japicmp](#japicmp) below.
 
+## Configuration
-## Configuration
+## Configuration
+
+There are [3 configuration interfaces](https://github.com/open-telemetry/opentelemetry-specification/tree/main/specification/configuration#configuration-interfaces):
+
+- Programmatic configuration: Invoke Java APIs to build components. This is the base of all other configuration interfaces.
+- Env var / system property configuration: Set flat env vars / system properties, which are interpreted to equivalent calls to the programmatic configuration interface
+- Declarative configuration: Structured, YAML based configuration, which is interpreted to equivalent calls to the programmatic configuration interface
+
+As a general rule, all configuration interfaces are bound by the spec. However, we make certain exceptions with java-specific additions in places where the lack of such features is detrimental to the OpenTelemetry Java ecosystem. For example:
+
+- The OTLP exporters have programmatic proxy configuration options, since despite not being part of the is a common enough use case that not supporting would be a glaring oversight.
+- Env var / system property configuration has a `otel.java.metrics.cardinality.limit` property for configuring a global cardinality limit. Not part of the spec, but an important / common enough use case that we added a java-specific property for it.
+
+Configuration options outside the spec are added at maintainers' discretion. If proposing an option outside the spec, please start with programmatic configuration, which we are much more likely to accept. 
+
+Declarative configuration is stable at the spec level and was designed to solve the expressiveness shortcomings of env var / system property configuration. Its the priority interface for current and future configuration enhancements. This means:
+
+- We are judicious about extending the env var / system property configuration interface with new options. Additions are at maintainers' discretion.
+- Declarative configuration must be a strict superset of env var / system property configuration. In the event new env var / system properties are added, there must be equivalent capabilities in declarative config, with the caveat that naming and structure do not need to be identical. 
+
+Configuration is part of our public API surface area, subject to our [versioning policy](https://github.com/open-telemetry/opentelemetry-java/blob/main/VERSIONING.md) unless explicitly marked unstable (i.e. `*.experimental.*` for env vars / system properties, `*/development` for declarative config).
-## Configuration
+## Configuration
+
+There are [3 configuration interfaces](https://github.com/open-telemetry/opentelemetry-specification/tree/main/specification/configuration#configuration-interfaces):
+
+- Programmatic configuration: Invoke Java APIs to build components. This is the base of all other configuration interfaces.
+- Env var / system property configuration: Set flat env vars / system properties, which are interpreted to equivalent calls to the programmatic configuration interface
+- Declarative configuration: Structured, YAML based configuration, which is interpreted to equivalent calls to the programmatic configuration interface
+
+As a general rule, all configuration interfaces are bound by the spec. However, we make certain exceptions with java-specific additions in places where the lack of such features is detrimental to the OpenTelemetry Java ecosystem. For example:
+
+- The OTLP exporters have programmatic proxy configuration options, since despite not being part of the is a common enough use case that not supporting would be a glaring oversight.
+- Env var / system property configuration has a `otel.java.metrics.cardinality.limit` property for configuring a global cardinality limit. Not part of the spec, but an important / common enough use case that we added a java-specific property for it.
+
+Configuration options outside the spec are added at maintainers' discretion. If proposing an option outside the spec, please start with programmatic configuration, which we are much more likely to accept. 
+
+Declarative configuration is stable at the spec level and was designed to solve the expressiveness shortcomings of env var / system property configuration. Its the priority interface for current and future configuration enhancements. This means:
+
+- We are judicious about extending the env var / system property configuration interface with new options. Additions are at maintainers' discretion.
+- Declarative configuration must be a strict superset of env var / system property configuration. In the event new env var / system properties are added, there must be equivalent capabilities in declarative config, with the caveat that naming and structure do not need to be identical. 
+
+Configuration is part of our public API surface area, subject to our [versioning policy](https://github.com/open-telemetry/opentelemetry-java/blob/main/VERSIONING.md) unless explicitly marked unstable (i.e. `*.experimental.*` for env vars / system properties, `*/development` for declarative config).
+
+There are [3 configuration interfaces](https://github.com/open-telemetry/opentelemetry-specification/tree/main/specification/configuration#configuration-interfaces):
+
+- Programmatic configuration: invoke Java APIs to build components. This is the base of all other
+  configuration interfaces.
+- Env var / system property configuration: set flat env vars / system properties, which are
+  interpreted to equivalent calls to the programmatic configuration interface.
+- Declarative configuration: structured, YAML-based configuration, which is interpreted to
+  equivalent calls to the programmatic configuration interface.
+
+As a general rule, all configuration interfaces are bound by the spec. However, we make certain
+exceptions with Java-specific additions in places where the lack of such features is detrimental to
+the OpenTelemetry Java ecosystem. For example:
+
+- The OTLP exporters have programmatic proxy configuration options. Despite not being part of the
+  spec, this is a common enough use case that not supporting it would be a glaring oversight.
+- Env var / system property configuration has an `otel.java.metrics.cardinality.limit` property for
+  configuring a global cardinality limit. This is not part of the spec, but it is an important and
+  common enough use case that we added a Java-specific property for it.
+
+Configuration options outside the spec are added at maintainers' discretion. If proposing an
+option outside the spec, start with programmatic configuration, which we are much more likely to
+accept.
+
+Declarative configuration is stable at the spec level and was designed to solve the expressiveness
+shortcomings of env var / system property configuration. It is the priority interface for current
+and future configuration enhancements. By default, new non-programmatic configuration options
+should target declarative configuration. This means:
+
+- We are judicious about extending the env var / system property configuration interface with new
+  options. Additions are at maintainers' discretion.
+- Declarative configuration must be a strict superset of env var / system property configuration.
+  In the event new env var / system properties are added, there must be equivalent capabilities in
+  declarative config, with the caveat that naming and structure do not need to be identical.
+
+Configuration is part of our public API surface area, subject to our
+[versioning policy](../../VERSIONING.md) unless explicitly marked unstable (for example,
+`*.experimental.*` for env vars / system properties and `*/development` for declarative config).
+
 ## Deprecating API
 
 Applies to both stable and alpha modules. Use plain `@Deprecated` — do **not** use