Proposal: include all removed/renamed/deprecated attribute keys in yaml

[dyladan]

Some (most?) SIGs including JS and Python consume the semconv yaml and generate a semantic convention helper package. When an attribute is renamed, this means the code generator no longer outputs it, resulting in a breaking change for the code generators. Especially now that the spec requires us to double-publish old and new semantic conventions when there is a stabilization effort which breaks semconv, it would be much easier if the generated packages contained deprecated/removed/renamed keys.

My proposal is simply to create a deprecated.yaml file which contains all removed attributes from all versions of the semconv for use by code generators. If a key is renamed, removed, or otherwise excluded from code generation it should be added to deprecated.yaml.

[aabmass]

What do you think of adding a deprecated flag for semconv entries? That would make it easier to keep generating them in the same place (code or markdown tables) but add some note they are deprecated.

[Oberon00]

This flag already exists and can be used.

(I think it would be worth considering adding some more meta-information to be able to generate all schemas from the latest YAML model, but thats off topic a bit, sorry)

[jsuereth]

We discussed this in the SiG. While there are many concerns, I think there's enough interest to more formally flesh out this proposal.

A few things brought up:

• If we needed to take down an attribute for some extreme reason (e.g. legal?) would this be allowed, and how would it happen.
• Would we have a "cleanup" process eventually, say every N years? Would this be of benefit?

[dyladan]

What do you think of adding a deprecated flag for semconv entries? That would make it easier to keep generating them in the same place (code or markdown tables) but add some note they are deprecated.

There is already a deprecated flag in the yaml schema which would be used for this purpose.

We discussed this in the SiG. While there are many concerns, I think there's enough interest to more formally flesh out this proposal.

Can you document the concerns here so I can respond to them?

• If we needed to take down an attribute for some extreme reason (e.g. legal?) would this be allowed, and how would it happen.

I think this is vanishingly unlikely to happen and the same question can be made of the existing semconv. I think if it ever did happen we would simply delete the attribute and follow the appropriate semver process.

• Would we have a "cleanup" process eventually, say every N years? Would this be of benefit?

I don't really see a benefit of cleanup. Even if we deprecated hundreds of attributes per sprint it would take a very long time for the file to grow beyond a few megabytes. Having the full history also has the benefit of ensuring we don't accidentally re-create an attribute which shares a name with a previously deprecated attribute which could potentially confuse consumers.

[rapphil]

For reference, the deprecated semantic attributes live here: https://github.com/open-telemetry/semantic-conventions/tree/main/model/deprecated

[joaopgrassi]

This was closed by mistake by the stale bot. Re-opening