Api incompatibility caused by minor version change

[bastikempken]

Introduction

We use sentry in a microfrontend context, where the microfrontend applications are owned by different teams. Every team should build and run it's application mostly independent. This includes dependency management.

The entire appliction is assembled by the application shell architecture pattern which although provides central functions at runtime.

One of these functions is a central sentry hub reporting runtime errors from all the different microfrontend applications. To route error events depending on the responsible microfrontends, we use the concept of ModuleMetadata and makeMultiplexedTransport. The implementation follows the documented recommendations.

This works fine for unhandled errors and errors events from the CaptureConsole integration. In addition some teams have the usecases to use sentry specific apis like captureMessage.

For that reason the @sentry/browser dependency is installed in microfrontends beside the installation in the application shell. This means sentry apis like captureMessage are called from a different @sentry/browser version than the one which is used to init the central sentry hub in the application shell.

Problem

With the following pull request #9732 a much more restrictive version check was introduced to avoid api incompatibility. In the described context this is a hard to handle problem, because the used version of the @sentry/browser dependency in a microfrontend has always to be equal or lower than the one used in the application shell used to init the sentry hub. This is even the case for minor version changes. In case of an critical minor version difference no sentry error event is sent.

Question

Is it really necessary that the implemented version check, judges a minor version difference as a incompatibility? Should't that be the case only for major version changes, at least from a sematic versioning perspective ?

cc @AbhiPrasad

[AbhiPrasad]

Is it really necessary that the implemented version check, judges a minor version difference as a incompatibility? Should't that be the case only for major version changes, at least from a sematic versioning perspective ?

All Sentry SDKs used on a page should have the same version for the most correct behaviour. In the model you displayed above you are also increasing bundle size for your users by having two different versions of the SDK.

Although public API does not break in minor versions, improvements in instrumentation patching or event processing might be made, which is why we need to enforce this for correctness.

I recommend you build an abstraction over the sentry sdks to ensure that all your microfrontends use the same version whenever possible.

[davemyersworld]

Hi there @AbhiPrasad, and thanks @bastikempken for writing up this issue, as we're running into it as well. We have Microfrontends, each of which loads their own copy of @sentry/browser.

Being required to all be on the same version is unrealistic in our setup: We have individual teams that are on their own upgrade schedules, we cannot all coordinate upgrading at the same time (this is the reason these teams opted for Microfrontends in the first place).

Further, even if we did have some form of dependency sharing, we'd be unable to guarantee that Microfrontends could actually adopt the "shared" version at the time the host upgraded it. When Sentry APIs do change (for example, removing configureScope in v8), we'd need to make sure that the MFEs all adjusted their integration before we upgrade to ensure their code was compatible with the upgraded version. That wouldn't work, for example in a hypothetical scenario where Sentry changes the name of a method we depend upon (for example, if withScope were to change to withSentryScope... I know this won't happen, but something like it could).

Nothing in the Microfrontend documentation indicates that dependency sharing (or module federation) is required. We know the benefits, and have not yet decided that the tradeoffs are right for us.

So that makes every Sentry upgrade onerous for us, forcing us to coordinate all of the teams to upgrade at the same time...
And, even if we do coordinate all of that, we cannot control when the Microfrontend is loaded. Our users sometimes keep their browser tab open for weeks(and very commonly, days). If we roll out all of the new versions at exactly the same time on all Microfrontends, users will end up in a situation where Microfrontends will be on @sentry/browser@new while the host will have loaded @sentry/browser@old, which will lead to an observability gap.

While I understand the benefits of keeping Sentry versions isolated, I don't think the current approach fits well with the reality of Microfrontends.

[smeubank]

for example in a hypothetical scenario where Sentry changes the name of a method

Although public API does not break in minor versions

thanks for writing in @davemyersworld for us i don't think we are trying to say you must, but to achieve most correct. As with all things MFE, i understand version consistency is complicated though 😅

Do you have an example snippet of something which is not working for you between versions? I'm wondering if it is really an isolated bug you're running into.

Are you following our docs for MFE here, and using module federation or example?

[davemyersworld]

Hi @smeubank, thanks for your response.

Are you following our docs for MFE here, and using module federation or example?

Yes, we are following the docs for MFE, using the "Automatic" approach. We do not use module federation.

Do you have an example snippet of something which is not working for you between versions?

To be clear: In most cases, Events are not sent if they originated in the Microfrontend and the versions are mismatched.

I tested several combinations (pseudo code describing them below) over the weekend, trying to trigger events from the Microfrontend, and here are the results of my tests:

---

withScope/captureException

...
onClick={() = {
    withScope((scope) => {
        scope.setTag('testTag', 'microfrontend');
        captureException(new Error(errorMessage));
    });
}}
...

MFE Host: 8.37.1, MFE Remote: 8.38.0
No Event sent
MFE Host 8.37.1, MFE Remote: 8.37.1
Event sent, tag present
Host 8.37.1, Remote: 8.37.0
No Event sent

---

render error, bubbling up to Sentry.ErrorBoundary

const [ Comp, setComp ] = useState(</>);
...
onClick={() => {
  setComp(null);
}}
...
<Comp />

Host 8.37.1, Remote: 8.37.1
Event sent
Host 8.37.1, Remote: 8.37.0
No Event sent

---

Uncaught error in click handler, getCurrentScope().setTag()

...
onClick={() => {
  const scope = getCurrentScope();
  scope.setTag('testTag', 'microfrontend');
  throw new Error(errorMessage);
}}
...

Host: 8.37.1, Remote: 8.38.0
Event sent, no tags included
Host: 8.37.1, Remote: 8.37.1
Event sent, tags included

[Lms24]

Hey @davemyersworld I believe you're running into this change which was our attempt to isolate SDKs in different versions as well as possible. In your case, this can lead to the behaviour that although you're maybe just a patch version apart, the SDK parts won't communicate with each other.

Context

Why was this change made?

Besides the MFE use case, you typically don't want multiple SDKs to communicate with each other at all on the page. Think of a browser extension or some kind of 3rd party script using their own (maybe very outdated, e.g. v6) SDK version and your application using a very recent SDK version. Sentry JS SDKs store a lot of their state in window.__SENTRY__ (we call this the "carrier" object). So now you'd have a v6 SDK access this carrier as well as a recent v8 SDK. There will be a lot of mismatches between the two APIs, the two will leak data into each other or worst case, only one of them will send events captured from both SDKs. So in general, having carrier "isolation", based on the version, at least partially addresses this problem and is a good thing. Arguably, in your MFE use case though, it is problematic.

Breakage in Minor versions

Furthermore, to address the "breakage" aspect of this: We guarantee public API stability within a major version and will only apply public API breaking changes when shipping a new major. However, think of a case where we'd add a public method to BrowserClient for example, say in version 8.5.0. This is not a breaking change, because it only adds public API. If the shell or host app is still on a version prior to 8.5.0, say 8.4.1, it will instantiate BrowserClient but of course it will not include the new method. However, say one of your micro apps uses 8.5.0, and it would call something like getCurrentScope().getClient().newMethod(), things would break because the method is not available. So this "cross-version breakage" can be very subtle but it's something we can't avoid unless we stopped adding any public API within majors, which is pretty much impossible.

How to work around it?

Update: Here are some more workaround options in addition to the proposed option in this reply.

I gotta admit, this is untested because frankly, I don't have a MFE setup and it's extremely hard to find a 100% working solution in the MFE space due to the variety of ways how one can implement an MFE architecture.

As you can see from the PR I linked above, the MFE/micro apps need to be able to access the shell app's state on the carrier.
Let's say, the shell/host SDK is on version 8.40.0 and we have two MFE apps on 8.39.0 and 8.41.0. After all of these are initialized, we'll have a carrier looking something like this:

window.__SENTRY__ === {
  version: '8.40.0',
  '8.40.0': {...}, // state of shell
  '8.39.0': {...}, // state of MFE 1
  '8.41.0': {...} // state of MFE 2
}

What we need to do is to re-route the states of the two MFE apps to the host app, so do somthing like:

// in MFE 1
window.__SENTRY = {
  ...window.__SENTRY__,
  '8.39.0': window.__SENTRY['8.40.0'],
}

// in MFE 2
window.__SENTRY = {
  ...window.__SENTRY__,
  '8.41.0': window.__SENTRY['8.40.0'],
}

This should be enough that your two MFEs can send events again.

Why does this work?

Calling Sentry.captureException() under the hood actually does something like this:

// MFE 1
function captureException(e) {
  getCurrentScope().captureException(e)
}

The important part is that getCurrentScope() will access the global carrier object to find the scope. Meaning, at this point it'll get to this line of code:

sentry-javascript/packages/core/src/carrier.ts

Lines 56 to 58 in 9581a2e

	// Intentionally populating and returning the version of "this" SDK instance
	// rather than what's set in .version so that "this" SDK always gets its carrier
	return (__SENTRY__[SDK_VERSION] = __SENTRY__[SDK_VERSION] || {});

which will return the carrier of 8.39.0 by default and, if you rewrite the references as shown above, return the correct carrier of 8.40.0.

How to find the respective versions?

You can use the SDK_VERSION constant exported by your individual SDKs to find the correct version. This comes with the caveat that you need to ensure that all @sentry/* dependencies within one MFE app are on exactly the same version. This is because the constant is defined in the @sentry/core package and re-exported by higher level packages.

To find the version of the host/shell app, you can access window.__SENTRY__.version if and only if the shell SDK is initialized prior to the MFEs doing the carrier rewriting logic as outlined above.

Let me know if this works for you!

[davemyersworld]

Hi @Lms24, thanks for the detailed response. Yes, I am aware of the context, and I understand the reasoning behind the decision. The problem is how that decision impacts Sentry's Microfrontend support.

I have tested out the workaround you proposed: I made this function which handles pre-versioned carrier versions of Sentry as well, and call it in one of our Microfrontends.

This does indeed work! For a host on 8.37.1, I was successfully able to send events for a Microfrontend on 7.x, 8.37.1 and 8.40.0.

However, I'm concerned about relying on a deep reach into the Sentry object for our production integration. Can such a function be incorporated into @sentry/browser itself, such that it is testable alongside other changes throughout Sentry?

[Lms24]

Thanks for confirming that this works!

for a Microfrontend on 7.x, 8.37.1 and 8.40.0

I'd strongly recommend to not mix 7.x and 8.x versions as these two major versions have quite a few differences. So even if you'd get some things working, data could still be missing, and APIs as well as internals have also changed.

However, I'm concerned about relying on a deep reach into the Sentry object for our production integration. Can such a function be incorporated into @sentry/browser itself, such that it is testable alongside other changes throughout Sentry?

To be quite honest, we are concerned about this too. As I said before, we cannot guarantee that multiple SDK versions on one page work correctly. Which is why I'm very hesitant to add an API that abstracts this away because it would falsely convey that we support this use case officially. Whatever we'd implement in there would look very similar to the script you came up with. So I talked to the team and for the forseeable future, we won't add such an API.

The good news here is that we're not planning on making many changes around the main Sentry.capture* APIs and implementations and neither on our carrier object structure. So while not impossible that it'll break across versions, it's rather unlikely.

Further Workarounds

We also came up with some further workarounds:

Namespace on Global

Your host/shell app could write its Sentry namespace onto the global object. Which your MFE apps could access instead of relying on their own SDK version:

// host/shell app
import * as Sentry from '@sentry/browser'

Sentry.init({...});

+ window.Sentry = Sentry;

// MFE app
- import * as Sentry from '@sentry/browser'
- Sentry.captureException(...)
+ window.Sentry.captureException(...)

This way, the SDK version of the shell app is global and your MFEs can directly interact with it instead of importing the SDK package on their own in diverging versions.

SDK Loader

Instead of using the NPM packages, you could use our loader to always load the latest SDK version (within a major) as a CDN bundle, alleviating the need to manually update packages.

[davemyersworld]

I'd strongly recommend to not mix 7.x and 8.x versions as these two major versions have quite a few differences.

Right, sorry, I wasn't totally clear. We are currently on a mix of v7 versions amongst our microfrontends and host. We discovered this issue when attempting to upgrade to 8. In order to ensure that we don't have an observability gap during the upgrade to v8, we want to cover all the way back to v7. Our aim is to get everyone on latest.

we are concerned about this too. As I said before, we cannot guarantee that multiple SDK versions on one page work correctly.

I think our concerns are a little different. My concern is that we don't control Sentry, so if access to the version carrier somehow changes, our function would have to be updated in concert. I understand the team's concern regarding version compatibility, but I am hoping to identify a Sentry offering that doesn't require us to maintain a workaround.

---

We'll consider the other two offerings, though I'll share my initial thoughts/questions here:

• Namespace on Global
  • We actually do this already, but we explicitly avoid using it in Microfrontends, in part for the reason you've suggested (what happens when the host upgrades but the clients haven't, and they use unavailable functionality)
  • Also, we were avoiding changes to the way any code interacts with Sentry, such that teams can follow sentry docs to achieve what they want
  • If Microfrontends are used in two different hosts, this would add to the requirements on Hosts
  • A similar idea to this would be "Make the Sentry instance provided as part of the Microfrontend contract" which we've avoided for the same reasons
• SDK Loader
  • I'm not sure I understand how this one would work... The host loads the SDK with a DSN... are Microfrontends that subsequently load compatible with this approach?
  • Assuming they are, this approach implies a change to Sentry usages throughout our codebases

Thanks for the additional suggestions, we'll consider our options here.

[davemyersworld]

Couple more followup questions @Lms24:

1. Regarding your comment on the gist: Would the key for a prerelease Sentry version be window.__SENTRY__['9.0.0-rc4'] or would it be window.__SENTRY__['9.0.0']?
2. More broadly, is the key flexible or configurable? Internally, we were wondering if it'd be possible to make it configurable, which might open up a couple other alternatives:
   • We configure the host and all Microfrontends to use a specific custom key. This has all the same problems you've detailed above, but would be a built-in way to handle it
   • We instantiate Sentry separately in each microfrontend, initing each with a custom key per microfrontend, thereby keeping all interaction with the APIs separate per MFE (I know that Sentry prefers not doing this)

[Lms24]

1. The key would be window.__SENTRY__['9.0.0-rc4']. My concern was that calling parseInt on 0-rc4 would throw or return something invalid but turns out, it returns 0. Anyway, I missed that you're only looking at the major and minor parts, so the patch being coerced is irrelevant in this case.

2. The key is not flexible because the SDK internally takes carrier[SDK_VERSION].
   I thought about making the key configurable but this is a bit of a chicken-egg problem. We'd need to somehow read out the SDK options of the respective SDK to obtain the key that should be used. How can we obtain the options? By calling getClient().getOptions(). The problem: getClient() will invoke a call chain that accesses the carrier to get the correct client. So we've gone full circle and again need to obtain the custom key....

   What we could do (just as a thought experiment): Register one custom carrier key on the main __SENTRY__ like __SENTRY__.customCarrierKey. And let SDKs access this key, instead of SDK_VERSION if it is defined. But this would entail that the first SDK being initialized (which should be the host) needs to set this custom key and all other SDKs on the page would be forced to access it. This also includes all 3rd party scripts, browser extensions, etc. So isolation can no longer be guaranteed at all.

   We instantiate Sentry separately in each microfrontend

   As you already said, we don't recommend this. The problem here is that you'd end up with race conditions which MFE would register which Sentry integration. For example the global error handlers which automatically capture errors. Also if you use tracing at all, it's no longer clear which MFE would start spans and where they would get attached to. Tracing in MFE architecture is very much experimental but nevertheless something I want to call out would suffer deeply from this.