semantic convention marker: stability

[anuraaga]

From open-telemetry/opentelemetry-specification#1497 (comment) there are cases we may want to stabilize a subset of attributes in a given category. It would be nice if we can just mark attributes as stable so the generator handles this for us. This is less important for MD generation and more for code, where stable attributes will need to be rendered differently (different packages for example).

[anuraaga]

@thisthat Filed an issue for it :)

[Oberon00]

Can the tag-mechanism be extended for that? E.g. if we allow multiple tags, we can just designate certain tags (stable, experimental?) for that use case.

[anuraaga]

TBH despite me maintaining this repo, I haven't looked into the details on how the Java generator works :P

https://github.com/open-telemetry/opentelemetry-java/blob/main/buildscripts/semantic-convention/templates/SemanticAttributes.java.j2

If the attributes processed by that template can be filtered by tag, then that would work fine I think. I guess it might still need a change, adding has_tag method around here?

build-tools/semantic-conventions/src/opentelemetry/semconv/model/semantic_attribute.py

Line 87 in b4f8bdd

def is_enum(self):

[Oberon00]

The generator would need to be updated anyway, as currently it allows only a single tag. has_tag might be useful too, although Jinja is basically a fully-fledged Python dialect and probably already has a contains method or "in" operator you could call on any exposed list attribute.

Maybe special support for stability declarations is warranted though. We could then e.g. declare a full group as stable and only mark certain attributes as experimental or vice-versa. Tags are not (yet) supported for groups.

[thisthat]

Given the special use case of this "tag", I would suggest adding it as its own field in the YAML definition.

[thisthat]

Discussing this with @Oberon00, we come up with changing the deprecated attribute to stability: deprecated|experimental|stable, where stable is the default one.
WDYT @anuraaga?

[anuraaga]

Sounds good, thanks!

[Oberon00]

Hmm, on the other hand, maybe we should keep deprecated separate after all. If we deprecate an attribute that was never stable, it would be different from deprecating a formerly stable attribute. Except if we say we have a strict policy of immediately removing experimental attributes worth deprecating. But given the wide use of our "experimental" semantic conventions, I'm not sure that works.