edit (2025-11-05): I am making a summary of the positions so far as well as the arguments in favor or against. The text on the issue before this date is left under the line. Verbatim quotes are formatted in italics.

Position A: Toggle fields (and other boolean fields) should be named so that the default is false

Description

This is what it is currently done for environment variables (see v1.50.0 version of the spec):

All Boolean environment variables SHOULD be named and defined such that false is the expected safe default behavior. Renaming or changing the default value MUST NOT happen without a major version upgrade.

The declarative configuration spec follows this guidance.

Usages

This convention is used in 9 places in the declarative configuration schema v1.0.0-rc.1 (see kitchen sink).

Some of the usages in the Collector, Java Agent and .NET instrumentation accidentally follow this guidance insofar as they are enabled-by-default. See #4344 (comment), #4344 (comment) and #4344 (comment) for full details.

Position B: Toggle fields should be named enabled, regardless of the default value

Description

All boolean configuration flags should be named enabled regardless of the default value.

Usages

The Collector, Java Agent and .NET instrumentation de facto follow this position. See #4344 (comment), #4344 (comment) and #4344 (comment) for full details. There is one exception for the Collector (but, I argue, it is an 'accident' and not intentional).

Position C: We should have a separate option that defines the default value of fields based on stability

Description

There should be a separate option (e.g. min_stability) that changes the defaults of instrumentations and other features depending on what stability level we consider them having.

Usages

Not currently used.

Arguments in favor and against different positions

Arguments in favor of Position A in the context of environment variables can be found mostly on #2755 (comment). As a summary the arguments espoused were the following (see full comment and context here):

• "User confusion around if they are or are not required to provide an environment variable diminishes when they know that by not providing it it will be assumed false"
• "It would be a huge frustration for a user to upgrade their system and all of a sudden they now need to set OTEL_SDK_DISABLED=false because we allowed the default to change."
• "If there does exist a valid example where a boolean variable needs to have it's default value changed, [...] it still makes sense from the user perspective to keep static defaults. A new variable would be defined and the old variable deprecated."

Arguments in favor of adopting Position A for non-environment variable (e.g. declarative configuration) usages are mentioned on this comment and this comment:

• The boolean env var convention is sensible enough, and following it when introducing new component properties (i.e. not env vars) is the path of least resistance for contributors.
• having different conventions for different configuration interfaces (env vars vs. programmatic) is a bad design. I'd like to see us consistent (to the extent it makes sense),

Arguments in favour of Position B include:

• This is inconsistent with other parts of the ecosystem including the Collector, the Java Agent and .NET (see below for usages). Some examples of 'enabled-by-default but not named disabled configuration toggles in the Collector are listed here.
• When exposing things as properties double negative seems way counter-intuitive for the end users (see [configuration] disabled boolean flags are inconsistent with other parts of the OpenTelemetry ecosystem #4344 (comment)). This was argued for in [configuration] Add exception for 'false default' when there is a double negation #4351.
• This leads to poorer discoverability: users don't know whether a configuration flag is named e.g. disabled or enabled if they don't also know what the value of it is.
• Position C may not make sense for all usages in the Collector since there may be 'no good default value' for all options or default values may not follow the stabilization framework (e.g. whether people want exemplars on their trace metrics is not a question of stability but rather of resource usage or backend support).

Arguments in favor of Position C were mostly discussed on the 2025-10-28 Specification SIG meeting, discussion starts at around 13:18:

• Mentioned around the 33 minute mark This option has the benefits of Position B but avoids changing the default value of settings, which is one of the arguments in favor of Position A.

Original text of the issue before 2025-11-05.

The MeterConfig's disabled parameter (introduced in #3877) conflicts with the Collector convention which is to use enabled (this is not documented, this search shows many places where this is used in the YAML configuration). Using enabled should be considered for consistency across the whole project.

Another argument against disabled: false is that it has a double negative which is harder to parse. IIRC this is the reason we use enabled instead in the Collector configuration.

disabled: false however is more idiomatic for Go because of false being the zero value of booleans.

cc @jack-berg @codeboten