From b5df7fb88fc498b39ad112de4e1d918e9668c36d Mon Sep 17 00:00:00 2001 From: ADITYA-CODE-SOURCE Date: Wed, 27 May 2026 20:00:53 +0530 Subject: [PATCH 1/2] docs: add configuration policy guidance --- docs/knowledge/README.md | 2 +- docs/knowledge/api-design.md | 34 ++++++++++++++++++++++++++++++++++ 2 files changed, 35 insertions(+), 1 deletion(-) diff --git a/docs/knowledge/README.md b/docs/knowledge/README.md index d7409ca3fa9..d7e979f348c 100644 --- a/docs/knowledge/README.md +++ b/docs/knowledge/README.md @@ -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 | diff --git a/docs/knowledge/api-design.md b/docs/knowledge/api-design.md index 1299646468d..918971ba96e 100644 --- a/docs/knowledge/api-design.md +++ b/docs/knowledge/api-design.md @@ -17,6 +17,40 @@ 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 + +### Use judgment + +Not every capability needs a new environment variable or system property. Prefer smaller, +composable configuration surfaces over adding one-off toggles. + +### Adding environment variables and system properties + +Be judicious about adding new environment variables or system properties. + +- Prefer existing configuration when it can already express the behavior. +- Include a clear justification for any new config key, including why existing configuration is not + sufficient. +- Treat new config keys as a long-term compatibility and maintenance commitment. + +### Declarative config parity + +Declarative config should remain a strict superset of environment variable and system property +configuration. + +If a change adds a new environment variable or system property, it **must** also add equivalent +declarative config support. Equivalent does not require identical naming, but it must allow users +to express the same capability through declarative config. + +### PR expectations for configuration changes + +PRs that introduce new configuration options should include: + +- The motivation for introducing new configuration. +- The environment variable and system property names. +- The equivalent declarative config form. +- Tests and documentation updates covering the new configuration path. + ## Deprecating API Applies to both stable and alpha modules. Use plain `@Deprecated` — do **not** use From 710fb5dcf6ed1195cda02a5a9f86e3d42c4c868c Mon Sep 17 00:00:00 2001 From: ADITYA-CODE-SOURCE Date: Wed, 3 Jun 2026 08:22:07 +0530 Subject: [PATCH 2/2] docs: refine configuration API guidance --- docs/knowledge/api-design.md | 68 ++++++++++++++++++++---------------- 1 file changed, 37 insertions(+), 31 deletions(-) diff --git a/docs/knowledge/api-design.md b/docs/knowledge/api-design.md index 918971ba96e..943baa98fd3 100644 --- a/docs/knowledge/api-design.md +++ b/docs/knowledge/api-design.md @@ -19,37 +19,43 @@ enforces this via japicmp — see [japicmp](#japicmp) below. ## Configuration -### Use judgment - -Not every capability needs a new environment variable or system property. Prefer smaller, -composable configuration surfaces over adding one-off toggles. - -### Adding environment variables and system properties - -Be judicious about adding new environment variables or system properties. - -- Prefer existing configuration when it can already express the behavior. -- Include a clear justification for any new config key, including why existing configuration is not - sufficient. -- Treat new config keys as a long-term compatibility and maintenance commitment. - -### Declarative config parity - -Declarative config should remain a strict superset of environment variable and system property -configuration. - -If a change adds a new environment variable or system property, it **must** also add equivalent -declarative config support. Equivalent does not require identical naming, but it must allow users -to express the same capability through declarative config. - -### PR expectations for configuration changes - -PRs that introduce new configuration options should include: - -- The motivation for introducing new configuration. -- The environment variable and system property names. -- The equivalent declarative config form. -- Tests and documentation updates covering the new configuration path. +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