Rename Optional attribute requirement level to Opt-In

[trask]

Based on suggestion by @arminru and others.

Needed before we mark attribute-requirement-level.md as stable (which is needed before we mark HTTP semantic conventions stable, see open-telemetry/opentelemetry-specification#3219)

[yurishkuro]

+1

[yurishkuro]

I like the name change, but did we do an analysis that all usages of the optional level are actually opt-in`? Because the two are not exactly equivalent:

• optional is something that instrumentation may or may not support (fairly similar to recommended, but to lesser degree)
• opt-in is something that instrumentation MUST require an active opt-in before enabling the attribute

Is it possible that we need to keep both concepts and just do a once-over review if some currently optional attrs should really be opt-in? if we only need opt-in (given that optional ~= recommended), then I don't think this is how many people may actually understood optional previously, and as a result the attrs may be proactively emitted by instrumentation without asking user to enable them.

[trask]

I just sent a draft spec PR to explore that: open-telemetry/opentelemetry-specification#3228

Luckily, optional isn't used in many places yet, so only two I'm unsure about which meaning was intended, I left comments to try to get clarification on those two places.

[Oberon00]

Because the two are not exactly equivalent

There is actually a definition of our "optional" requirement level that says it's "opt-in": https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/common/attribute-requirement-level.md#optional

Optional

Instrumentations SHOULD populate the attribute if and only if the user configures the instrumentation to do so. Instrumentation that doesn't support configuration MUST NOT populate Optional attributes.

opt-in was also the original name this was proposed with in open-telemetry/opentelemetry-specification#2522 by @lmolkova, but @bogdandrutu requested reanaming it to "optional" in open-telemetry/opentelemetry-specification#2522 (comment):

I would actually consider to change "Opt-In" to "OPTIONAL", and say that instrumentation plugins must offers way to "opt-out" for any recommended attributes, and to "opt-in' for any available "optional" attributes. the required and conditional required cannot be disabled, this way we separate the 2 concerns about what is available and what is configurable for the user.

Personally, I would also still find "opt-in" clearer than "optional"

[Oberon00]

Maybe it would be better to just change the markdown output, as everything else is a breaking change.

[trask]

Maybe it would be better to just change the markdown output, as everything else is a breaking change.

I split out the markdown rendering into a separate PR #137 in case there's a preference to move forward with that first and then we can discuss the breaking change on its own.

[Oberon00]

I approved both PRs, depending on how you want to handle it in the spec and potentially code generators (I doubt anybody actually uses the requirement levels there though, except maybe for printing them out).

[trask]

I approved both PRs, depending on how you want to handle it in the spec and potentially code generators (I doubt anybody actually uses the requirement levels there though, except maybe for printing them out).

thx! I'd prefer to merge this PR and trigger a new release of build-tools, then I will proceed with open-telemetry/opentelemetry-specification#3228

[trask]

are there enough approvals on open-telemetry/opentelemetry-specification#3228 to merge this? thx!

[arminru]

@trask I believe so 🙂
If any strong disagreement comes up still we could revert build-tools before pulling it into the spec.