From 623df224082e907b72cdb5dd134091b2eff63695 Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Thu, 31 Oct 2024 11:03:29 +0100 Subject: [PATCH 1/4] feat(js): Add `skipBrowserExtensionCheck` documentation --- .../best-practices/shared-environments.mdx | 47 +++++++++++++++---- 1 file changed, 37 insertions(+), 10 deletions(-) diff --git a/docs/platforms/javascript/common/best-practices/shared-environments.mdx b/docs/platforms/javascript/common/best-practices/shared-environments.mdx index 5de050f9b9330..58f02044da252 100644 --- a/docs/platforms/javascript/common/best-practices/shared-environments.mdx +++ b/docs/platforms/javascript/common/best-practices/shared-environments.mdx @@ -39,16 +39,18 @@ These best practices are relevant for you if you set up Sentry in one of the fol - Libraries - Any other scenario where you might have multiple Sentry instances running in the same environment - + When setting up Sentry in a shared environment where multiple Sentry instances may run, you should **not use `Sentry.init()`**, as this will pollute the global state. If your browser extension uses `Sentry.init()`, and a website also uses Sentry, the extension may send events to the website's Sentry project, or vice versa. - + -For such scenarios, you have to set up a client manually as seen in the example below. -In addition, you should also avoid adding any integrations that use global state, like `Breadcrumbs` or `GlobalHandlers`. Furthermore, some default integrations that use the global state have to be filtered as in the example below. -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. +## Shared Environment Setup +For the use cases listed above, set up a client manually as seen in the example below. +In addition, avoid adding any integrations that use global state, like `Breadcrumbs` or `GlobalHandlers`. +Furthermore, some default integrations that use the global state have to be filtered as in the example below. +As a rule of thumb, it's best to avoid using any integrations and to rely on manually capturing errors only in such scenarios. ```javascript import { @@ -61,11 +63,9 @@ import { // filter integrations that use the global variable const integrations = getDefaultIntegrations({}).filter((defaultIntegration) => { - return ![ - "BrowserApiErrors", - "Breadcrumbs", - "GlobalHandlers", - ].includes(defaultIntegration.name); + return !["BrowserApiErrors", "Breadcrumbs", "GlobalHandlers"].includes( + defaultIntegration.name + ); }); const client = new BrowserClient({ @@ -104,3 +104,30 @@ If you notice that Sentry is not capturing error events from the browser extensi You can disable that by going to your **Project Settings > Inbound Filters** and disabling filtering out errors known to be caused by browser extensions. Read more about Inbound Filters in the product documentation under [Inbound filters](/concepts/data-management/filtering/#inbound-data-filters). + +## Skipping the Browser Extension Check + +_Available in all browser-based SDKs since version `8.37.0`_ + +If for some reason, the SDK wrongfully detects that it's initialized in a browser extension, you can skip the check by specifying the `skipBrowserExtensionCheck` option when initializing the SDK: + +```javascript +import * as Sentry from "@sentry/browser"; + +Sentry.init({ + dsn: "___PUBLIC_DSN___", + skipBrowserExtensionCheck: true, + // ... +}); +``` + + + +Don't use this option light-hearted if you're in fact using the SDK in a browser extension or another shared environment. +Initializing the SDK via `Sentry.init` has no advantages over manually setting up the client and scope as described on this page. +You'd risk quota increases with unactionable issues, interference with other Sentry SDKs and data leakage by doing so. + + + +This option is purely meant as an escape hatch if our browser extension check is incorrectly detecting a browser extension. +An example for this might be a From 273c1484f76aea2d1af22a7bba31fa1ac28a0487 Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Thu, 31 Oct 2024 16:59:38 +0100 Subject: [PATCH 2/4] continue example :D --- .../javascript/common/best-practices/shared-environments.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/javascript/common/best-practices/shared-environments.mdx b/docs/platforms/javascript/common/best-practices/shared-environments.mdx index 58f02044da252..7a8f6b9df5679 100644 --- a/docs/platforms/javascript/common/best-practices/shared-environments.mdx +++ b/docs/platforms/javascript/common/best-practices/shared-environments.mdx @@ -130,4 +130,4 @@ You'd risk quota increases with unactionable issues, interference with other Sen This option is purely meant as an escape hatch if our browser extension check is incorrectly detecting a browser extension. -An example for this might be a +An example for this might be a cross-platform application framework that exposes similar global APIs like browser a browser extension environment. From c9db40627c3b65b53247b2a88b087e3bc7f6533a Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Mon, 4 Nov 2024 10:03:47 +0100 Subject: [PATCH 3/4] Update docs/platforms/javascript/common/best-practices/shared-environments.mdx --- .../javascript/common/best-practices/shared-environments.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/javascript/common/best-practices/shared-environments.mdx b/docs/platforms/javascript/common/best-practices/shared-environments.mdx index 7a8f6b9df5679..2b4f8681282de 100644 --- a/docs/platforms/javascript/common/best-practices/shared-environments.mdx +++ b/docs/platforms/javascript/common/best-practices/shared-environments.mdx @@ -130,4 +130,4 @@ You'd risk quota increases with unactionable issues, interference with other Sen This option is purely meant as an escape hatch if our browser extension check is incorrectly detecting a browser extension. -An example for this might be a cross-platform application framework that exposes similar global APIs like browser a browser extension environment. +An example for this might be a cross-platform application framework that exposes similar global APIs like browser extensions. From ce6b381a22ad99eee6c735781fe9f7687b4642b8 Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Thu, 7 Nov 2024 12:59:14 +0100 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: Alex Krawiec --- .../common/best-practices/shared-environments.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/platforms/javascript/common/best-practices/shared-environments.mdx b/docs/platforms/javascript/common/best-practices/shared-environments.mdx index 2b4f8681282de..064d7dfb7be66 100644 --- a/docs/platforms/javascript/common/best-practices/shared-environments.mdx +++ b/docs/platforms/javascript/common/best-practices/shared-environments.mdx @@ -50,7 +50,7 @@ When setting up Sentry in a shared environment where multiple Sentry instances m For the use cases listed above, set up a client manually as seen in the example below. In addition, avoid adding any integrations that use global state, like `Breadcrumbs` or `GlobalHandlers`. Furthermore, some default integrations that use the global state have to be filtered as in the example below. -As a rule of thumb, it's best to avoid using any integrations and to rely on manually capturing errors only in such scenarios. +In these scenarios, it's a best practice to avoid using any integrations and to rely on manually capturing errors. ```javascript import { @@ -123,9 +123,9 @@ Sentry.init({ -Don't use this option light-hearted if you're in fact using the SDK in a browser extension or another shared environment. +You shouldn't use this option if you're in fact using the SDK in a browser extension or another shared environment. Initializing the SDK via `Sentry.init` has no advantages over manually setting up the client and scope as described on this page. -You'd risk quota increases with unactionable issues, interference with other Sentry SDKs and data leakage by doing so. +You'd risk quota increases with unactionable issues, interference with other Sentry SDKs, and data leakage by doing so.