Generate upgrade document based on deprecations #2601

[thompson-tomo]

Fixes #2601

Connected PR #2819 split rendering of deprecated

Changes

This introduces upgrade documents which documents how to upgrade the telemetry in that namespace to the latest version. These documents cover both the signals themselves as well as the attributes on the signals. Each change has an upgrade action which is determined based on the depreciation level. 3 factors influence how the action behaves:

• Deprecation reason ie renamed
• Instrumentation status ie unstable vs stable
• Should the change be gradual and user can control it or not.

Note the old attributes are needed to be added for potential code generation as we are needing a way to support side by side.

Note: if the PR is touching an area that is not listed in the existing areas, or the area does not have sufficient domain experts coverage, the PR might be tagged as experts needed and move slowly until experts are identified.

Merge requirement checklist

• CONTRIBUTING.md guidelines followed.
• Change log entry added, according to the guidelines in When to add a changelog entry.
  • If your PR does not need a change log, start the PR title with [chore]
• Links to the prototypes or existing instrumentations (when adding or changing conventions)

[jsuereth]

This is an interesting concept. I believe we were more thinking for things like this there would be a "major version release" that would have its own sub-migration, vs piecemeal / fine-grained migration.

Curious what other @open-telemetry/specs-semconv-maintainers + @open-telemetry/weaver-maintainers think there.

[thompson-tomo]

This approach focuses on improving the rendering of deprecated attributes by explaining what to do with them but more significantly reduces the ambiguity in the current solution. You could still have tagged releases with sub-migration.

[lmolkova]

it does not look like a real requirement level - it does not appear in the yaml schema and is not visible to code generation. I don't suggest to make it a requirement level though.

The goal seems to be to

• render a 'past' version of conventions
• provide migration instructions

That's what we're trying to do with migration guides.

I'd be happy to see them automated (it's possible now) and separate from the general conventions which tell how telemetry should look following the current version and nothing else.

[thompson-tomo]

Ok, based on that feedback i have changed it from a requirement level to a deprecation action which is now rendered in a separate table and requirement levels are not being touched.

The goal is to provide a single spot for a user to go to get an explaination of the attributes on their traces, metrics etc without needing to jump through many different documents. It can be used by new contributors to oss projects to know quickly know which attributes are from the spec and which one's have been added by other developers not following the spec.

It also helps to address the ambguity in how to update the signal definition being emitted when wanting to follow the published guidance which is especially important when the definitions being updated to are still not stable. Hence the clear definition of the actions.

As it currently stands if you were wanting to update an elasticsearch instrumentation to the latest spec from pre < 1.20 you end up in a massive grey area as:

• the migration guide says the OTEL_SEMCONV_STABILITY_OPT_IN variable is only when migrating to stable,
• the elasticsearch page has no warning on it and is defined as experimental,
• the database span page has a warning that you need the variable if upgrading from <= 1.24 so you could upgrade to 1.25 (also not stable) using the variable for the changed attributes but that introduces new grey area. Then any subsequent updates if not changing to a stable definition you don't need the stability opt in variable to control them.

With the approach here you can see which attributes need to be controlled via the stability environment variable, which one's dont and how the instrumentation stability impacts the behaviour.

The migration guide seems alot more like a changelog/revision history when you read it.

[lmolkova]

we can shape migration guides to provide any details.

with this proposal, we'd have more confusion:

• current and previous versions of semconv in the same page
• all previous versions squashed together into 'past attributes'
• no details on non-attribute parts of the past versions.

I don't see how it reduces any ambiguity around elasticsearch - it does not even change anything on its page. If there is a problem there, we better address it first without introducing new notions.

With current state in main:

• users can check past version via tags, e.g. https://github.com/open-telemetry/semantic-conventions/tree/v1.36.0. They should have schema-url in their telemetry to tell them which version they are in
• users can check the current version on main
• they can read the migration guide to learn how to get from version vPast to vCurrent and explore which attributes were used by the conventions in the past.

What I'm still suggesting is to build a better vision on what's included in the migration guides and automate their generation instead of squashing them into one page in actual conventions.

I would support adding a link to migration guide from the 'actual' semconv page

[thompson-tomo]

No where has it been stated by me that this would remove the migration guides, in fact I stated you could still have them.

all previous versions squashed together into 'past attributes'

This is No different to what you have now in migration guide for db for example.

no details on non-attribute parts of the past versions.

Migration Guide could & would still exist to cover those additional things.

I don't see how it reduces any ambiguity around elasticsearch - it does not even change anything on its page.

That's because the signals don't currently contain the past attributes which would need for codegen etc. Once they are added to the model, the docs get updated. I have only added a couple of attributes to verify it

If there is a problem there, we better address it first without introducing new notions.

It is a general problem which can be reproduced across the conventions and not restricted to the db namespace, but also applies to messaging etc.

They should have schema-url in their telemetry to tell them which version they are in

I have never encountered the schema-url being set in the implementations i have seen.

What I'm still suggesting is to build a better vision on what's included in the migration guides and automate their generation instead of squashing them into one page in actual conventions.

I agree with automating and improving the migration guides but I don't see it as an either or scenario but rather they complement each other. As such I would like to see both of them with the deprecation actions also appearing in the migration guides as a way to describe how to make the upgrade as that is where the grey area is.

[github-actions]

This PR was marked stale due to lack of activity. It will be closed in 7 days.