Planned SDK 2.0 Release (Important Dates and Information)

[pichlermarc]

Important

• 2.0.0/0.200.0 is now live.
• A migration guide can be found here.

Description

Quick Summary

We're planning to release a 2.0 version of stable SDK packages. This release will include breaking changes that aim to make the stable SDK packages easier to maintain and use - which will improve development velocity in the long run.

We plan to feature-freeze 1.x and 0.x on Dec 14 2024, any feature PRs merged later than that will target SDK 2.0.
We plan to release SDK 2.0 Mar 17, 2025 - between feature-freeze and SDK 2.0 release 1.x and 0.x packages will only receive bugfix releases.

Why we're bumping the SDK to 2.0

The 1.x SDK release supports Node.js versions that are out-of-date, such as Node.js v14/v16. As more and more of our dependencies and devDependencies drop support for these Node.js versions we amass more and more technical debt. It forces us to develop workarounds which take lots of time to maintain - this takes time away from feature development and is not sustainable long-term. Dropping support for Node versions is a breaking change and therefore requires us to bump the major version of our packages.

Similar to the outdated Node.js versions, we also support TypeScript >4.4, which limits us in which tools and language features we can use. Bumping TypeScript will cause our type-output to change and may break users that also use older TypeScript versions. Therefore this change requires us to bump the major version.

We have identified problems with our current exports. We usually export TypeScript classes, which, in the context of a library means that we expose private fields as part of the public API. This makes it extremely difficult to innovate as every small change is potentially breaking for our users. We also export some types that were unintentionally exported. Removing these types from the public API is a breaking change. It does, however, make it easier to make internal changes and reduces the risk for unintentional breaking changes for end-users.

We currently do not specify a minimum supported browser version this means that we have to deal with bugs that only occur on very old, and long-out-of-support browsers. Removing this support is a breaking change, but by dropping support for these old versions, we free up bandwidth to work on other things.

Some features are difficult for end-users to understand due to the way they are implemented and it is possible to do things in an incorrect order. However, in many cases we cannot change the public interface to make it easier to use without introducing a breaking change. In SDK 2.0 we aim to iron out some of these issues and make the SDK easier to use in these areas.

How (and when) we're moving forward

Important

@opentelemetry/api follows a different versioning scheme and is NOT included in the SDK 2.0 efforts and will therefore not receive any breaking changes. No pull-requests for breaking changes targeting the @opentelemetry/api package will be accepted.

Currently development for SDK 2.0 takes place on the main branch.

On Dec 14 2024 we will enter feature-freeze for 1.x. From this point onward:

• only bugfix back-ports will be accepted for 1.x (on the v1.x branch), and backported bugfixes have to be merged into main first.
• any unmerged features will only be accepted for 2.0, users will have to wait for the 2.0 release for these features.

Mar 17, 2025 we will release 2.0.

In the time from Dec 14 2024 to the date of release of SDK 2.0

• we may accept breaking changes to the SDK and other packages as long as these changes loosely follow the goals set out in the above sections and follow the specification.
• we will not release any new features, but we will still accept feature PRs to the 2.0 branch
• we will back-port and release bugfixes for the state that entered feature-freeze on Dec 14 2024 (the 1.x and 0.x line of packages)
• contrib development will continue as-usual

What this means for you

End-Users

You will still receive bugfixes, but new features merged after Dec 14 2024 will only be released Mar 17, 2025*.

There will be no breaking changes in @opentelemetry/api as it follows a different versioning scheme and has different stability guarantees then the SDK 2.0 packages. Any code written against @opentelemetry/api should continue to work as usual. You may have to update to the latest feature version of @opentelemetry/api to keep compatible with SDK 2.0 packages.

Upon release you may have to adjust your SDK setup code to the new interface. To prepare for this, we recommend you periodically update @opentelemetry/* packages to the latest version, and if you are using interfaces that are marked as @deprecated we recommend you take the transition path outlined for that feature.

Some changes may be breaking without prior deprecation; with the release of SDK 2.0 is, we will provide suggested upgrade paths for these breaking changes.

We will drop support for older versions of Node.js and Typescript, to prepare for this change, we recommend keeping Node.js, Typescript and other dependencies up-to-date leading up to the release of SDK 2.0.

Instrumentation authors

@opentelemetry/instrumentation may receive breaking changes, so you may have to update your instrumentation upon release to keep compatible with newer releases of the package. However, you will still be able to register your instrumentation with an older versions of @opentelemetry/instrumentation

@opentelemetry/api WILL NOT receive breaking changes. Your actual instrumentation code (writing metrics, traces, interacting with context and propagation) using @opentelemetry/api should remain the same even when SDK 2.0 is released.

If you're using any other @opentelemetry/* packages, please ensure that you're not using any deprecated features. You may still have to adjust some of your code to the new interface upon SDK 2.0 release. If you SDK components in testing, you may have to adjust tests when upgrading to SDK 2.0.

Thrid-party distributors of OpenTelemetry JavaScript SDKs

If you're a third-party distributor of OpenTelemetry JavaScript SDKs you should follow the same steps as outlined in the End-User section. Upon release, you may have to update your distribution's code to adjust to the new public interface of the OpenTelemetry JavaScript SDK. Depending on if your distribution exposes/accepts SDK 1.x types or not, this may also require you to bump the major version of your distribution.

If you implement a thrid-party SDK based on @opentelemetry/api, the planned changes in the SDK do not affect you.

[dyladan]

In the time from Dec 14 2024 to Feb 17 2025
...
we will not release any new features

We will not release new features, but we will still accept feature PRs to the 2.0 branch I think correct?

[mydea]

This sounds good! Are there plans to also release (some of?) the currently experimental packages - mainly thinking of @opentelemetry/instrumentation - as stable? IMHO this would be extremely helpful and important.

And to clarify, what are the exact versions you are looking to Support?

• Node 16+
• Typescript 5.0+

or others?

[pichlermarc]

This sounds good!

🙌

Are there plans to also release (some of?) the currently experimental packages - mainly thinking of @opentelemetry/instrumentation - as stable? IMHO this would be extremely helpful and important.

Please see #5149 for announcements of us starting to work on that. As stated in #5149 our priority is currently:

• ship SDK 2.0 in Feburary
• ship OTLP Exporters as GA (likely with 2.0) - work on that started a few months ago already and was needed to simplify some changes for SDK 2.0

Once any of these are done we'll chose another topic to move up into Focus Topics. We have been doing "everything at once" for a quite a while now and it's very clear to everybody that it's not working and we're not shipping things at the velocity we'd like. So focusing on fewer things is what we're doing deal with that.

I made a write-up of what we need to do to @opentelemetry/instrumentation to get it stable here (#4586) - it's already in the backlog in #5149 and it's going to be a lot of work.

And to clarify, what are the exact versions you are looking to Support?

Node 16+
Typescript 5.0+

or others?

We're looking to support Node 18+
Typescript 5.6 (ish) (update: #5148 (comment) still being decided - see #5145

Also plans for the future are to cut major releases more often (possibly on a yearly cadence) to drop support for old versions so that we don't fall back into the same problems that we're dealing with today.

[pichlermarc]

@mydea - update: we'll liklely adopt definetly-typed's policy, so that means typescript@5.0.x for the 2.0 SDK.
Edit: see #5145 (comment)