feat: Rework Browser JS integration docs #7648

mydea · 2023-08-16T10:52:03Z

This PR rewrites & reorganizes the integration docs for Browser JS SDKs.

Now, there is a single Integrations page that lists all integrations available for this SDK, with a short description & a note if it is enabled by default.

Each integration has it's own detail page with eventually available options.

The one special case is Electron, which does not have the same default integrations. I found a way to hide the parent pages for Electron, maybe a bit hacky (??) but it seems to work fine... 🤷

Another change I had to make to make this work/make sense is to move React/Vue Router & Redux pages, which have been inside of Integrations, into the React/Vue Features space. IMHO that makes more sense anyhow, as it is not really integrations this is about...?

Note that this does not touch Node.js yet, we can do that in a follow up.

vercel · 2023-08-16T10:52:07Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
sentry-docs	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Aug 24, 2023 0:01am

mydea · 2023-08-16T12:32:11Z

Note: We can/should also improve this page a bit, maybe: https://sentry-docs-git-fn-js-integrations.sentry.dev/platforms/javascript/configuration/integrations/custom/

AbhiPrasad

I like this change!! The individual pages make a lot more sense to me, and hopefully is easier to maintain as well

lizokm

Still working through this :)

lizokm · 2023-08-17T22:40:28Z

src/platforms/common/data-management/sensitive-data/index.mdx

@@ -99,6 +99,6 @@ As a best practice you should always avoid logging confidential information. If

 - Anonymize the confidential information within the log statements (for example, swap out email addresses -> for internal identifiers)
 - Use <PlatformIdentifier name="before-breadcrumb" /> to filter it out from breadcrumbs before it is attached
- Disable logging breadcrumb integration (for example, as described [here](/platforms/javascript/configuration/integrations/default/#breadcrumbs))
+- Disable logging breadcrumb integration (for example, as described [here](/platforms/javascript/configuration/integrations/breadcrumbs/))


Suggested change

- Disable logging breadcrumb integration (for example, as described [here](/platforms/javascript/configuration/integrations/breadcrumbs/))

- Disable the breadcrumb logging integration (read more [here](/platforms/javascript/configuration/integrations/breadcrumbs/))

There isn't anything on the Breadcrumbs page we're linking to that specifically says "how to disable the breadcrumb logging integration" - is it possible to write brief instructions for how to do it here and save our users an extra click? Is it as easy as disabling the Sentry.Integrations.Breadcrumbs integration?

well then you disable all breadcrumbs, you're gonna want to do this:

integrations: [ new Sentry.Integrations.Breadcrumbs({ console: false }) ]

to only disable console breadcrumbs. But based on this, let's add a sentence to the breadcrumbs integration page explicitly pointing out that the options below are meant to disable specific breadcrumbs, and why you may want to do this 👍

src/platforms/javascript/common/configuration/integrations/breadcrumbs.mdx

src/platforms/javascript/common/configuration/integrations/debug.mdx

lizokm · 2023-08-17T23:01:52Z

src/platforms/javascript/common/configuration/integrations/dedupe.mdx

+
+This integration deduplicates certain events. It can be helpful if you're receiving many duplicate errors. Note, that Sentry only compares stack traces and fingerprints.
+
+<PlatformContent includePath="configuration/dedupe" />


Suggested change

<PlatformContent includePath="configuration/dedupe" />

<PlatformContent includePath="configuration/dedupe" />

Heads up that the "logged in" link in the above note takes you to:

yeah that doesn't work in the preview! sentry always redirects back to docs.sentry.io and there the page does not exist 😅 (same for all of these)

Ah ok, that makes sense!

src/platforms/javascript/guides/electron/configuration/integrations/childprocess.mdx

src/platforms/javascript/guides/electron/configuration/integrations/electronbreadcrumbs.mdx

src/platforms/javascript/guides/electron/configuration/integrations/mainprocesssession.mdx

Lms24

I like this change! Makes the structure much more clear and easier to navigate between individual integrations! I have a few high-level comments. Feel free to apply/disregard as you see fit. We can also tackle them as a follow-up.

m: I'd like to see on first glance which integrations are enabled by default and which need to be added by users. Maybe we can put this directly under the title of the individual pages? Given that we're no longer distinguishing between default and pluggable integrations I think this is important. wdyt?
l: Great that we now have a dedicated Options section! More a cosmetic thing than anything but can we give the individual options a heading level? This way we can link to specific options and I guess it'd look a little better than the bullet points
l: Totally optional but wdyt about adding BrowserTracing and Replay to the list? We shouldn't duplicate information there but just link to the dedicated performance/replay docs.

src/includes/platforms/configuration/options/ignore-transactions.mdx

src/platforms/javascript/common/configuration/integrations/trycatch.mdx

Lms24 · 2023-08-18T07:53:06Z

Oh btw, great decision to move the Vue/React router stuff into the "[Framework] Features" section - I like it!

mydea · 2023-08-18T09:40:57Z

OK, I updated this based on feedback by @Lms24:

Added a note at the top of each default integration stating that it is default, + linking to the section telling you how to customize default integrations.
Refactored all options to be headings, to make it easier to link there etc.
Added a page for Replay and BrowserTracing integrations, which bascially link to performance/replay setup for more details.
Added the ContextLines integration which I forgot to add before 😅
I actually figured out there is a much nicer way to filter out integrations for electron, we can just provide notSupported to the page and it will be gone 🤦
Improved the Custom Integrations page a bit with an actual example for a custom integration

mydea · 2023-08-18T09:41:39Z

src/platforms/javascript/common/configuration/integrations/browsertracing.mdx

+description: "Capture performance data for the Browser."
+sidebar_order: 99
+notSupported:
+  - javascript.cordova


Hmm, not sure why cordova does not have a performance section? 🤔

mydea · 2023-08-18T09:41:58Z

src/platforms/javascript/common/configuration/integrations/replay.mdx

+description: "Capture a video-like reproduction of what was happening in the user's browser."
+sidebar_order: 99
+notSupported:
+  - javascript.cordova


Not sure if there is a reason cordova does not have a replay section?

Lms24

Thanks for applying my feedback!

lizokm

Phew!! Thanks for this amazing, labor-intensive PR!

lizokm · 2023-08-18T16:19:03Z

src/platforms/javascript/common/configuration/integrations/dedupe.mdx

+
+This integration deduplicates certain events. It can be helpful if you're receiving many duplicate errors. Note, that Sentry only compares stack traces and fingerprints.
+
+<PlatformContent includePath="configuration/dedupe" />


Ah ok, that makes sense!

src/platforms/javascript/guides/electron/configuration/integrations/childprocess.mdx

src/platforms/javascript/guides/electron/configuration/integrations/maincontext.mdx

src/platforms/javascript/guides/electron/configuration/integrations/net.mdx

src/platforms/javascript/guides/electron/configuration/integrations/onuncaughtexception.mdx

src/platforms/javascript/guides/electron/configuration/integrations/preloadinjection.mdx

src/platforms/javascript/guides/electron/configuration/integrations/sentryminidump.mdx

src/platforms/javascript/guides/vue/features/vue-router.mdx

src/platforms/react-native/troubleshooting.mdx

shanamatthews

Looks good, just a few questions from me here

shanamatthews · 2023-08-23T19:47:33Z

src/platforms/javascript/common/configuration/integrations/index.mdx

+## Available Integrations
+
+<PageGrid exclude={["custom"]} />


I wonder if we might want to move this below the instructions for adding/removing/custom integrations. That info is important and is very easy to miss with this long list of integrations folks won't scroll through.

These integrations are listed in the sidebar too.

👍 sure, I can move it down!

shanamatthews · 2023-08-23T19:53:28Z

src/platforms/javascript/guides/electron/configuration/integrations/maincontext.mdx

+description: "Adds app, operating system and runtime context to all events. (default)"
+sidebar_order: 10
+redirect_from:
+  - /platforms/javascript/guides/electron/configuration/integrations/default/


Could we add a better redirect to /platforms/javascript/guides/electron/configuration/integrations/ using vercel.json?

Good point, will replace this with a proper redirect for all!

shanamatthews · 2023-08-23T19:59:02Z

src/utils.ts

+    const aBase = a.context.sidebar_order ?? 10;
+    const bBase = b.context.sidebar_order ?? 10;
+    const aso = aBase >= 0 ? aBase : 10;
+    const bso = bBase >= 0 ? bBase : 10;


what is this?

Ah, forgot to mention this: I noticed that this was actually buggy before, because sidebar_order was sometimes null which lead to it not getting the default of 10, but null, leading to incorrect ordering etc.

Co-authored-by: Liza Mock <liza.mock@sentry.io>

Co-authored-by: Lukas Stracke <lukas.stracke@sentry.io>

Co-authored-by: Liza Mock <liza.mock@sentry.io>

mydea requested review from a team August 16, 2023 10:52

mydea self-assigned this Aug 16, 2023

mydea requested review from Lms24 and AbhiPrasad and removed request for a team August 16, 2023 10:52

vercel bot deployed to Preview August 16, 2023 11:41 View deployment

mydea force-pushed the fn/js-integrations branch from ad4a1c6 to c2f13a0 Compare August 16, 2023 12:07

mydea requested a review from a team as a code owner August 16, 2023 12:07

vercel bot deployed to Preview August 16, 2023 12:13 View deployment

mydea requested review from stephanie-anderson and lforst August 16, 2023 12:44

AbhiPrasad approved these changes Aug 16, 2023

View reviewed changes

lizokm approved these changes Aug 18, 2023

View reviewed changes

vercel bot deployed to Preview August 18, 2023 06:50 View deployment

mydea force-pushed the fn/js-integrations branch from 158d628 to f69ce5d Compare August 18, 2023 07:01

vercel bot deployed to Preview August 18, 2023 07:19 View deployment

Lms24 approved these changes Aug 18, 2023

View reviewed changes

src/includes/platforms/configuration/options/ignore-transactions.mdx Outdated Show resolved Hide resolved

src/platforms/javascript/common/configuration/integrations/trycatch.mdx Show resolved Hide resolved

vercel bot deployed to Preview August 18, 2023 09:04 View deployment

mydea commented Aug 18, 2023

View reviewed changes

vercel bot deployed to Preview August 18, 2023 09:48 View deployment

Lms24 approved these changes Aug 18, 2023

View reviewed changes

lizokm approved these changes Aug 21, 2023

View reviewed changes

shanamatthews approved these changes Aug 23, 2023

View reviewed changes

feat: Rework Browser JS integration docs

1fa43f3

mydea and others added 17 commits August 24, 2023 13:43

fix links

57db64b

Apply suggestions from code review

dcf17ed

Co-authored-by: Liza Mock <liza.mock@sentry.io>

Apply suggestions from code review

5aa3fd0

Co-authored-by: Liza Mock <liza.mock@sentry.io>

style(lint): Auto commit lint changes

f636a34

style(lint): Auto commit lint changes

5e5be8c

style(lint): Auto commit lint changes

c61c761

add sentence to breadcrumbs

07e6f2b

add more details to inbound filters integration page.

1e3a9af

Apply suggestions from code review

56bf8b0

Co-authored-by: Lukas Stracke <lukas.stracke@sentry.io>

streamline integration docs

59e7ba4

resturcture options & add default note

1021ee8

add browsertracing & replay integrations

8d16de1

improve dependencies

69ccac9

Apply suggestions from code review

60a235a

Co-authored-by: Liza Mock <liza.mock@sentry.io>

style(lint): Auto commit lint changes

9399eca

reorder sections

fb37995

fix linting & add vercel redirects

44f8e00

mydea force-pushed the fn/js-integrations branch from 67c63ce to 44f8e00 Compare August 24, 2023 11:43

vercel bot deployed to Preview August 24, 2023 12:01 View deployment

mydea closed this Aug 28, 2023

mydea reopened this Aug 28, 2023

mydea merged commit 1b46a11 into master Aug 28, 2023
11 checks passed

mydea deleted the fn/js-integrations branch August 28, 2023 13:37

github-actions bot locked and limited conversation to collaborators Sep 13, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: Rework Browser JS integration docs #7648

feat: Rework Browser JS integration docs #7648

mydea commented Aug 16, 2023

vercel bot commented Aug 16, 2023 •

edited

Loading

mydea commented Aug 16, 2023

AbhiPrasad left a comment

lizokm left a comment

lizokm Aug 17, 2023

mydea Aug 18, 2023

lizokm Aug 17, 2023

mydea Aug 18, 2023

lizokm Aug 18, 2023

Lms24 left a comment •

edited

Loading

Lms24 commented Aug 18, 2023

mydea commented Aug 18, 2023

mydea Aug 18, 2023

mydea Aug 18, 2023

Lms24 left a comment

lizokm left a comment

lizokm Aug 18, 2023

shanamatthews left a comment

shanamatthews Aug 23, 2023

mydea Aug 24, 2023

shanamatthews Aug 23, 2023

mydea Aug 24, 2023

shanamatthews Aug 23, 2023

mydea Aug 24, 2023

	- Disable logging breadcrumb integration (for example, as described [here](/platforms/javascript/configuration/integrations/breadcrumbs/))
	- Disable the breadcrumb logging integration (read more [here](/platforms/javascript/configuration/integrations/breadcrumbs/))


		This integration deduplicates certain events. It can be helpful if you're receiving many duplicate errors. Note, that Sentry only compares stack traces and fingerprints.

		<PlatformContent includePath="configuration/dedupe" />

feat: Rework Browser JS integration docs #7648

feat: Rework Browser JS integration docs #7648

Conversation

mydea commented Aug 16, 2023

vercel bot commented Aug 16, 2023 • edited Loading

mydea commented Aug 16, 2023

AbhiPrasad left a comment

Choose a reason for hiding this comment

lizokm left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Lms24 left a comment • edited Loading

Choose a reason for hiding this comment

Lms24 commented Aug 18, 2023

mydea commented Aug 18, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Lms24 left a comment

Choose a reason for hiding this comment

lizokm left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

shanamatthews left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vercel bot commented Aug 16, 2023 •

edited

Loading

Lms24 left a comment •

edited

Loading