new-api-faq.md

Armin's API TLDR

Here is how you use the new APIs.

What scopes exist?

• "current": points to the active span
• "isolation": points to the active request, tab, user etc.
• "global": points to the entire process

In some situations isolation and global scopes are almost the same or fully the same. Most manipulations are going onto the isolation scope, When you want to capture or read, you read from the current scope. For global reconfiguration after the fact, go to the global scope.

Global scope never changes, all other scopes follow the flow of execution via thread locals, async locals, context vars or else. The are copy on write.

How do I add tags?

// this
Sentry.setTag("my_stuff", "42");

// is a shortcut for this:
Sentry.isolationScope().setTag("my_stuff", "42");

How do I set the current user?

You typically want to set this per isolate. In cases where there is only one tab/one process this will be fine too since the isolation scope and global scope are matching.

// this
Sentry.setUser({"email": "john@example.com"});

// is a shortcut for this:
Sentry.isolationScope().setUser({"email": "john@example.com"});

How do reconfigure the active release?

You probably want to set this globally:

Sentry.globalScope().setRelease("blablabla@1.0.0");

How do I add a breadcrumb?

Very convenient.

// This
Sentry.addBreadcrumb("...");

// Does the following.  In most SDKs the breadcrumbs go to the
// isolation scope by default.
const scope = Sentry.currentScope();
switch (scope.client.options["breadcrumb_scope"]) {
  case "current":
    scope.addBreadcrumb("...");
    break;
  case "isolation":
    Sentry.isolationScope().addBreadcrumb("...");
    break;
  case "global":
    Sentry.globalScope().addBreadcrumb("...");
    break;
}

How do I add a scope?

Normal scope is done with withScope:

withScope((scope) => {
  scope.setTag("foo", "bar");
  ...
})

Note that scope in the argument is the currentScope.

How do I add an isolation scope?

You can use withIsolationScope:

withIsolationScope((scope) => {
  ...
});

You should never need to do this unless you write an integration for http frameworks or else. In that callback if you were to call isolationScope() you get that scope.

Question: do we need this API? do we want to hide this a way more?

How do I capture events?

Capturing (like reading) goes off the current scope:

// this
Sentry.captureException(err);

// is an alias for
Sentry.currentScope().captureException(err);

How do I capture events with custom tags?

We recommend passing them explicitly instead of using withScope:

// either this way
Sentry.captureException(err, {
  "tags": {"foo": "bar"}
});

// or this way:
const scope = new Scope();
scope.setTag("foo", "bar");
Sentry.captureException(err, scope);

How do I get the current span?

// this
Sentry.currentSpan()

// is an alias for
Sentry.currentScope().getSpan()