Multiple Sentry Instances

Learn how to manage several Sentry instances by creating your own clients.

These best practices are relevant for you if you set up Sentry in one of the following use-cases:

  • Browser Extensions
  • VSCode Extensions
  • Third-Party Widgets
  • Libraries
  • Any other scenario where you might have multiple Sentry instances running in the same environment

Creating multiple Sentry clients is not recommended in general, as it can lead to unexpected behavior. In case you are using Micro Frontends or similar, multiplexing might be a better solution than using multiple clients. Check out Micro Frontends in the Best Practices for more information.

To be able to manage several Sentry instances without any conflicts between them you need to create your own Client. This also helps to prevent tracking of any parent application errors in case your application is integrated inside of it. To ensure you don't conflict with your parent application, you should also remove any integrations that rely on global state.

In this example we use BrowserClient from @sentry/browser but it's also applicable to NodeClient from @sentry/node.

Copied
import {
  BrowserClient,
  defaultStackParser,
  getDefaultIntegrations,
  makeFetchTransport,
  Scope,
} from "@sentry/browser";

// filter integrations that use the global variable
const integrations = getDefaultIntegrations({}).filter(
  (defaultIntegration) => {
    return ![
      "BrowserApiErrors",
      "TryCatch",
      "Breadcrumbs",
      "GlobalHandlers",
    ].includes(defaultIntegration.name);
  },
);

const client = new BrowserClient({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  transport: makeFetchTransport,
  stackParser: defaultStackParser,
  integrations: integrations,
});

const scope = new Scope();
scope.setClient(client);

client.init(); // initializing has to be done after setting the client on the scope

// You can capture exceptions manually for this client like this:
scope.captureException(new Error("example"));

You can now customize the scope to your liking, without affecting other hubs/clients.

Integrations are setup on the Client, if you need to deal with multiple clients and hubs you have to make sure to also do the integration handling correctly.

We do not recommend doing this if you are using Sentry in a browser extension or in similar scenarios. If you can't avoid using global integrations (e.g. in a micro frontend application), here is a working example of how to use multiple clients with multiple scopes running global integrations.

Copied
import * as Sentry from "@sentry/browser";

// Very happy integration that'll prepend and append very happy stick figure to the message
function happyIntegration() {
  return {
    name: "Happy",
    setupOnce() {
      Sentry.addEventProcessor((event) => {
        const self = Sentry.getClient().getIntegration(HappyIntegration);
        // Run the integration ONLY when it was installed on the current Hub
        if (self) {
          event.message = `\\o/ ${event.message} \\o/`;
        }
        return event;
      });
    },
  };
}

// filter integrations that use the global variable
const integrations = Sentry.getDefaultIntegrations({}).filter(
  (defaultIntegration) => {
    return ![
      "BrowserApiErrors",
      "TryCatch",
      "Breadcrumbs",
      "GlobalHandlers",
    ].includes(defaultIntegration.name);
  },
);

const client1 = new Sentry.BrowserClient({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  transport: Sentry.makeFetchTransport,
  stackParser: Sentry.defaultStackParser,
  integrations: [...integrations, happyIntegration()],
  beforeSend(event) {
    console.log("client 1", event);
    return null; // Returning `null` prevents the event from being sent
  },
});
const scope1 = new Sentry.Scope(client1);

const client2 = new Sentry.BrowserClient({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0", // Can be a different DSN
  transport: Sentry.makeFetchTransport,
  stackParser: Sentry.defaultStackParser,
  integrations: [...integrations, happyIntegration()],
  beforeSend(event) {
    console.log("client 2", event);
    return null; // Returning `null` prevents the event from being sent
  },
});
const scope2 = new Sentry.Scope(client2);

scope1.captureMessage("a");
scope1.setTag("a", "b");

scope2.captureMessage("x");
scope2.setTag("c", "d");
Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").