Sentry is full of engineers, so we know how painful it can be to deal with breaking changes caused by third party libraries. But we also know those third party libraries have to continually update and stay on top of their games, or they’ll become irrelevant.
For that reason, we try to only introduce breaking changes when they’re really (really) required. Especially when those changes are made to an API surface.
You can probably guess why we’re writing this: we’re announcing a breaking change. In Q2 2020 (or at least no earlier than that) we will deprecate our old
raven-js in favor of the newer
@sentry/browser on npm.
Deprecation doesn’t mean
raven-js will stop working. It will, in fact, work as long as Sentry exists (which has been prophesied to last until the sun is blotted out of the sky and the rivers run black with printer ink). It just means a message will pop up when you install the
raven-js package guiding you to use the
@sentry/browser SDK instead. This is, perhaps, the most gentle breaking change of all time.
If you really want to avoid upgrading, we can’t stop you, but there are lots of very good reasons to upgrade.
If you follow our blog closely or use a lot of our SDKs you may have already stumbled upon what we refer to as “Unified SDKs”. The whole idea behind them is bringing our SDKs closer together in terms of how they work and how they’re used.
Let’s look at
@sentry/browser to highlight some benefits of using our new SDKs over the older ones.
@sentry/browser is written in TypeScript it’s now impossible that the typings will be out of sync with the actual code. There are, of course, many more advantages to using TypeScript, but that’s a topic for a different blog post.
raven-js requires two arguments:
captureException: function(error, options)
While this seems perfectly ok at first glance (and certainly has worked very well for many years now) the second argument is a very ambiguous one.
It takes an object, some of the things you can set in there were merged in the event, some options changed the behavior of how we even create the event. It wasn’t clear what exactly is expected to happen without looking at the code, in cases where it worked, fine, but debugging this was a nightmare when it didn’t.
The unified SDKs now separate concerns in a more clear way, Scopes are responsible for enriching context in the event and SDK options alter behavior.
When it comes to supporting the latest, greatest and hippest new JS framework or new product features of Sentry like APM, moving forward if you want to use those new features they will only be introduced in the latest version. Talking about APM specifically the new SDKs were built with having support for APM in mind.
The most common and easy tasks using
@sentry/browser should be super obvious and shouldn’t require a lot of understanding of the internals of the SDK or even Sentry as a product. But when it comes to customizing the behavior of how the SDK works we wanted also to give the user as much power as ever before while making sure we not have to break our API contract in unforeseen ways. Writing your own integration or changing the transport is as easy as never before.
These are just some of the many examples we gave without even mentioning the countless bug fixes and minor improvements we shipped already in the newer SDKs.