From c36a69319e965b24fc666c01d9d9732ef550c75a Mon Sep 17 00:00:00 2001 From: Francesco Novy Date: Wed, 15 Nov 2023 10:48:03 +0100 Subject: [PATCH 1/2] fix: Update docs for manual client creation --- .../common/troubleshooting/index.mdx | 55 ++++++------------- 1 file changed, 17 insertions(+), 38 deletions(-) diff --git a/src/platforms/javascript/common/troubleshooting/index.mdx b/src/platforms/javascript/common/troubleshooting/index.mdx index 032eabf5aa96e0..282b240c6e4cdf 100644 --- a/src/platforms/javascript/common/troubleshooting/index.mdx +++ b/src/platforms/javascript/common/troubleshooting/index.mdx @@ -255,6 +255,7 @@ import { defaultStackParser, defaultIntegrations, makeFetchTransport, + Hub, } from "@sentry/browser"; const client = new BrowserClient({ @@ -264,53 +265,31 @@ const client = new BrowserClient({ integrations: defaultIntegrations, }); -client.captureException(new Error("example")); -``` - -While the above sample should work perfectly fine, some methods like `configureScope` and `withScope` are missing on the `Client` because the `Hub` takes care of the state management. That's why it may be easier to create a new `Hub` and bind your `Client` to it. The result is the same but you will also get state management with it. - - - -```javascript -import { - BrowserClient, - defaultStackParser, - defaultIntegrations, - makeFetchTransport, -} from "@sentry/browser"; - -const client = new BrowserClient({ - dsn: "___PUBLIC_DSN___", - transport: makeFetchTransport, - stackParser: defaultStackParser, - integrations: defaultIntegrations, -}); - +// You have to bind the client to a hub, otherwise integrations will not run! const hub = new Hub(client); +// Or, if you already have a hub you want to re-use, you can also do: +// hub.bindClient(client); -hub.configureScope(function (scope) { - scope.setTag("a", "b"); -}); +hub.captureException(new Error("example")); +``` -hub.addBreadcrumb({ message: "crumb 1" }); -hub.captureMessage("test"); +You can now customize the hub to your liking, without affecting other hubs/clients. -try { - a = b; -} catch (e) { - hub.captureException(e); -} +### Setting up Sentry in shared environments (e.g. Browser Extensions) -hub.withScope(function (scope) { - hub.addBreadcrumb({ message: "crumb 2" }); - hub.captureMessage("test2"); -}); -``` +When setting up Sentry in a shared environment - for example, in a browser extension or similar - where multiple Sentry instances may run, +you should under no circumstances use `Sentry.init()`, as this will pollute the global state. If your browser extension uses `Sentry.init()`, and the website the extension is running on also uses Sentry, the extension may send events to the website's Sentry project, or vice versa. + +For such scenarios, you _have to_ setup a client manually as seen in the example above. +In addition to this, you should also avoid adding any integrations that use global state, like `Breadcrumbs` or `TryCatch`. +As a rule of thumb, it's best to avoid using any integrations, and to rely on manual capture of errors only in such scenarios. ### Dealing with Integrations 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. -Here is a working example of how to use multiple clients with multiple hubs running global integrations. + +You should avoid doing this if you are using Sentry in a browser extension or in similar scenarios. +If you know what you are doing, and you want to use global integrations nonetheless (e.g. in a microfrontend application), here is a working example of how to use multiple clients with multiple hubs running global integrations. From 210ac2a59a15e714d8dd6d936172e331be41de0e Mon Sep 17 00:00:00 2001 From: Francesco Novy Date: Thu, 16 Nov 2023 09:15:25 +0100 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Shana Matthews --- .../javascript/common/troubleshooting/index.mdx | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/src/platforms/javascript/common/troubleshooting/index.mdx b/src/platforms/javascript/common/troubleshooting/index.mdx index 282b240c6e4cdf..d52e82323ec550 100644 --- a/src/platforms/javascript/common/troubleshooting/index.mdx +++ b/src/platforms/javascript/common/troubleshooting/index.mdx @@ -277,19 +277,18 @@ You can now customize the hub to your liking, without affecting other hubs/clien ### Setting up Sentry in shared environments (e.g. Browser Extensions) -When setting up Sentry in a shared environment - for example, in a browser extension or similar - where multiple Sentry instances may run, -you should under no circumstances use `Sentry.init()`, as this will pollute the global state. If your browser extension uses `Sentry.init()`, and the website the extension is running on also uses Sentry, the extension may send events to the website's Sentry project, or vice versa. +When setting up Sentry in a shared environment where multiple Sentry instances may run, for example, in a browser extension or similar, you should **not use `Sentry.init()`**, as this will pollute the global state. If your browser extension uses `Sentry.init()`, and the website the extension is running on also uses Sentry, the extension may send events to the website's Sentry project, or vice versa. -For such scenarios, you _have to_ setup a client manually as seen in the example above. -In addition to this, you should also avoid adding any integrations that use global state, like `Breadcrumbs` or `TryCatch`. -As a rule of thumb, it's best to avoid using any integrations, and to rely on manual capture of errors only in such scenarios. +For such scenarios, you have to set up a client manually as seen in the example above. +In addition, you should also avoid adding any integrations that use global state, like `Breadcrumbs` or `TryCatch`. +As a rule of thumb, it's best to avoid using any integrations and to rely on manual capture of errors only in such scenarios. ### Dealing with Integrations 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. -You should avoid doing this if you are using Sentry in a browser extension or in similar scenarios. -If you know what you are doing, and you want to use global integrations nonetheless (e.g. in a microfrontend application), here is a working example of how to use multiple clients with multiple hubs running global integrations. +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 hubs running global integrations.