feat(node-experimental): Replace getCurrentHub with getCurrentScope

[mydea]

This removes getCurrentHub() & configureScope() from node-experimental, and instead exposes a few new APIs:

• getCurrentScope()
• getCurrentRootScope()
• withScope() - has the same API as before, uses OTEL under the hood
• withRootScope()
• getClient()

getClient()

IMHO this API we can/should add to all SDKs, it's annoying to have to do getCurrentHub().getClient() anyhow. This is just a short cut and a nicer API.

What is a root scope

This PR introduces the (tentative) concept of a root scope. A root scope is supposed to be the scope attached to an execution context, e.g. to a route handler:

const globalScope = Sentry.getCurrentRootScope();

app.get('/route1', () => {
  const scope = Sentry.getCurrentRootScope();
  Sentry.withScope(() => {
    Sentry.getCurrentRootScope() === scope;
  });
});

app.get('/route2', () => {
  const scope = Sentry.getCurrentRootScope();
  Sentry.withScope(() => {
    Sentry.getCurrentRootScope() === scope;
  });
});

The goal of the root scope is to make reasoning about scopes with the heavily nested scopes/contexts we have in otel easier. Since every change on the context creates a new hub & scope, you can quickly get into a scenario where it's impossible to actually get the correct scope to add stuff to.

Eventually, the idea is that the root scope is always applied to events in addition the the actual current scope. This is not yet implemented in this PR but will be done in a follow up PR. This will also streamline the breadcrumbs handling we have, as we'll be able to simply put the breadcrumbs on the root scope instead of on the root span.

The scenario we are solving is things like this:

fastify.addHook('preValidation', () => {
  Sentry.getCurrentRootScope().addEventProcessor(...);
});

Without this, it is basically impossible to add execution-context specific things, because the fastify otel instrumentation creates a span for each hook, which in turn creates a new context (and scope), which means that if you do this:

fastify.addHook('preValidation', () => {
  Sentry.getCurrentScope().addEventProcessor(...);
});

You'll only add this to the scope valid inside of this hook, not to the request.

For most user-land scenarios, this should not be necessary - you can still do e.g.:

app.get('/route', () => {
  const scope = Sentry.getCurrentScope();
  scope.setUser(user);
});

To mutate the current scope. But it gives more flexibility to integrations/plugins etc.

How do we detect/set the root scope

Here is where it gets tricky. Conceptually, in most cases it is relatively clear what we want the root scope to be - the scope for the http.server request. However, it is not necessarily easy to find this, nor to generalize this for all environments, as some may not have requests at all.

This PR takes the following approach:

1. The first scope that is forked from the global scope is considered a root scope:

const globalScope = getCurrentScope(); 
// globalScope is a root scope

withScope(scope1 => {
  // scope1 is a root scope!
});

withScope(scope2 => {
  // scope2 is a root scope!
  withScope(scope3 => {
    // scope3 is _not_  a root scope!
  });
});

2. A scope that has a root span is considered a root scope:

withScope(scope1 => {
  // scope1 is a root scope!
  startSpan({ name: 'root span' }, () => {
    const scope2 = getCurrentScope();
    // scope2 is a root scope!
    startSpan({ name: 'span' }, () => {
      const scope3 = getCurrentScope();
      // scope3 is _not_ a root scope!
    });
  });
});

3. You can also manually fork a root scope, no matter where you are:

withScope(scope1 => {
  // scope1 is a root scope!
  withRootScope(scope2 => {
    // scope2 is a root scope!
  });
});

4. We fall back to the current scope if we can't find anything else.

[AbhiPrasad]

The only thing on the hub that people may want to access is lastEventId. We need a similar analogue for that.

[mitsuhiko]

This generally looks reasonable to me, what is less clear to me yet is how to set truly global things. My understanding:

• getCurrentScope -> innermost span thing
• getRootScope -> root of the trace span thing

But do we have a truly global scope to which I can set global tags? Or do I need a different thing for this?

[mydea]

The only thing on the hub that people may want to access is lastEventId. We need a similar analogue for that.

The only thing on the hub that people may want to access is lastEventId. We need a similar analogue for that.

We already expose a lastEventId() method everywhere for this, which should continue to work as expected!

[AbhiPrasad]

lets do it