From 73e11a24d34df020c992ca96fbe1952e8f116d46 Mon Sep 17 00:00:00 2001 From: Francesco Novy Date: Mon, 12 Feb 2024 17:14:53 +0100 Subject: [PATCH 1/3] feat: Add docs for custom browser tracing routing instrumentation --- ...browser-custom-routing-instrumentation.mdx | 36 ------------------- .../javascript.mdx | 24 +++++++++++++ .../javascript.mdx | 2 ++ .../javascript.react.mdx | 4 +-- 4 files changed, 28 insertions(+), 38 deletions(-) delete mode 100644 includes/performance/browser-custom-routing-instrumentation.mdx create mode 100644 platform-includes/performance/automatic-instrumentation-custom-routing/javascript.mdx diff --git a/includes/performance/browser-custom-routing-instrumentation.mdx b/includes/performance/browser-custom-routing-instrumentation.mdx deleted file mode 100644 index 4c1b309437edf..0000000000000 --- a/includes/performance/browser-custom-routing-instrumentation.mdx +++ /dev/null @@ -1,36 +0,0 @@ -If you use a custom client-side router, you can define your own custom router instrumentation. - -```TypeScript -export function customRoutingInstrumentation( - customStartTransaction: (context) => T | undefined, - startTransactionOnPageLoad: boolean = true, - startTransactionOnLocationChange: boolean = true, -): void { - // Track initial pageload - if (startTransactionOnPageLoad) { - customStartTransaction({ name: getCustomRouteName() }); - } - - // Track route changes - if (startTransactionOnLocationChange) { - // MyCustomRouter is a custom router that you define, you can use any router you want - MyCustomRouter.on('routeChange', (routeName) => { - customStartTransaction({ name: routeName }); - }); - } -} - -// Then later when you initialize Sentry - -Sentry.init({ - dsn: '__PUBLIC_DSN__', - tracesSampleRate: 1.0, - integrations: [ - new Sentry.BrowserTracing({ - routingInstrumentation: customRoutingInstrumentation, - }), - ], -}); -``` - -An example implementation for custom `routingInstrumentation` can be found in this example for [Inertia.js](https://github.com/getsentry/sentry-javascript/discussions/8528). diff --git a/platform-includes/performance/automatic-instrumentation-custom-routing/javascript.mdx b/platform-includes/performance/automatic-instrumentation-custom-routing/javascript.mdx new file mode 100644 index 0000000000000..a63e907f1cccc --- /dev/null +++ b/platform-includes/performance/automatic-instrumentation-custom-routing/javascript.mdx @@ -0,0 +1,24 @@ +### Custom routing + +By default, the `browserTracingIntegration()` will create a `pageload` span for when the page is initially loaded, as well as a `navigation` span whenever the URL changes afterwards. + +If you want to ensure navigation spans are created correctly for a custom routing setup, you can opt out of the default `navigation` span creation by setting `instrumentNavigation: false` in the `browserTracingIntegration()` options. Then, you can manually create navigation spans like this: + +```javascript +Sentry.init({ + integrations: [ + // disable default navigation spans + Sentry.browserTracingIntegration({ instrumentNavigation: false }), + ], +}); + +// Somewhere, instrument your router like this: +myRouter.on("routeChange", (route) => { + const client = Sentry.getClient(); + Sentry.startBrowserTracingNavigationSpan(client, { + op: "navigation", + name: route.name, // or what the name of the span should be + // you can add additional data to add to the span here + }); +}); +``` diff --git a/platform-includes/performance/enable-automatic-instrumentation/javascript.mdx b/platform-includes/performance/enable-automatic-instrumentation/javascript.mdx index 6181b5fd0f9d2..05f4c33b9652e 100644 --- a/platform-includes/performance/enable-automatic-instrumentation/javascript.mdx +++ b/platform-includes/performance/enable-automatic-instrumentation/javascript.mdx @@ -19,3 +19,5 @@ Sentry.init({ tracesSampleRate: 1.0, }); ``` + + \ No newline at end of file diff --git a/platform-includes/performance/enable-automatic-instrumentation/javascript.react.mdx b/platform-includes/performance/enable-automatic-instrumentation/javascript.react.mdx index e40063b6ad0fc..d60031cfb7abf 100644 --- a/platform-includes/performance/enable-automatic-instrumentation/javascript.react.mdx +++ b/platform-includes/performance/enable-automatic-instrumentation/javascript.react.mdx @@ -22,8 +22,6 @@ Sentry.init({ // * reactRouterV4BrowserTracingInstrumentation // * reactRouterV6BrowserTracingInstrumentation // or just browserTracingIntegration - routingInstrumentation: Sentry.reactRouterV5Instrumentation(history), - // ... other options }), ], @@ -34,3 +32,5 @@ Sentry.init({ ``` Now you should be generating `pageload`/`navigation` transactions from the `BrowserTracing` integration, using Sentry's [`react-router` instrumentation](/platforms/javascript/guides/react/configuration/integrations/react-router/). + + \ No newline at end of file From 27ca31c324a103f501b085f0466b86465924b53e Mon Sep 17 00:00:00 2001 From: Francesco Novy Date: Tue, 13 Feb 2024 15:41:50 +0100 Subject: [PATCH 2/3] better docs for pageload span --- .../javascript.mdx | 38 +++++++++++++++---- 1 file changed, 30 insertions(+), 8 deletions(-) diff --git a/platform-includes/performance/automatic-instrumentation-custom-routing/javascript.mdx b/platform-includes/performance/automatic-instrumentation-custom-routing/javascript.mdx index a63e907f1cccc..7bc1cbab062cc 100644 --- a/platform-includes/performance/automatic-instrumentation-custom-routing/javascript.mdx +++ b/platform-includes/performance/automatic-instrumentation-custom-routing/javascript.mdx @@ -2,23 +2,45 @@ By default, the `browserTracingIntegration()` will create a `pageload` span for when the page is initially loaded, as well as a `navigation` span whenever the URL changes afterwards. -If you want to ensure navigation spans are created correctly for a custom routing setup, you can opt out of the default `navigation` span creation by setting `instrumentNavigation: false` in the `browserTracingIntegration()` options. Then, you can manually create navigation spans like this: +If you want to ensure spans are created correctly for a custom routing setup, you can opt out of the default span creation by setting `instrumentNavigation: false` & `instrumentPageLoad: false` in the `browserTracingIntegration()` options. Then, you can manually create the spans like this: ```javascript Sentry.init({ integrations: [ - // disable default navigation spans - Sentry.browserTracingIntegration({ instrumentNavigation: false }), + Sentry.browserTracingIntegration({ + // disable automatic span creation + instrumentNavigation: false, + instrumentPageLoad: false, + }), ], }); +// We start the pageload span as early as possible! +let pageLoadSpan = Sentry.startBrowserTracingPageLoadSpan({ + name: window.location.pathname + attributes: { + [Sentry.SEMANTIC_ATTRIBUTE_SENTRY_SOURCE]: "url", + }, +}); + // Somewhere, instrument your router like this: myRouter.on("routeChange", (route) => { const client = Sentry.getClient(); - Sentry.startBrowserTracingNavigationSpan(client, { - op: "navigation", - name: route.name, // or what the name of the span should be - // you can add additional data to add to the span here - }); + + // We want to make sure to update the pageload span to use the route name + // After that, each route change should trigger a navigation span (which will automatically finish the previous one) + if (pageLoadSpan) { + pageloadSpan.updateName(route.name); + pageloadSpan.setAttribute(Sentry.SEMANTIC_ATTRIBUTE_SENTRY_SOURCE, "route"); + pageLoadSpan = undefined; + } else { + Sentry.startBrowserTracingNavigationSpan(client, { + op: "navigation", + name: route.name, // or what the name of the span should be + attributes: { + [Sentry.SEMANTIC_ATTRIBUTE_SENTRY_SOURCE]: "route", + }, + }); + } }); ``` From 66a7b99495a914e5930d126f014cd20ea7f2f19f Mon Sep 17 00:00:00 2001 From: Francesco Novy Date: Wed, 14 Feb 2024 10:37:13 +0100 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: Liza Mock --- .../javascript.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/platform-includes/performance/automatic-instrumentation-custom-routing/javascript.mdx b/platform-includes/performance/automatic-instrumentation-custom-routing/javascript.mdx index 7bc1cbab062cc..0eb3bfa0f410a 100644 --- a/platform-includes/performance/automatic-instrumentation-custom-routing/javascript.mdx +++ b/platform-includes/performance/automatic-instrumentation-custom-routing/javascript.mdx @@ -1,8 +1,8 @@ -### Custom routing +### Custom Routing -By default, the `browserTracingIntegration()` will create a `pageload` span for when the page is initially loaded, as well as a `navigation` span whenever the URL changes afterwards. +By default, the `browserTracingIntegration()` will create a `pageload` span for when the page is initially loaded, as well as a `navigation` span for whenever the URL changes afterwards. -If you want to ensure spans are created correctly for a custom routing setup, you can opt out of the default span creation by setting `instrumentNavigation: false` & `instrumentPageLoad: false` in the `browserTracingIntegration()` options. Then, you can manually create the spans like this: +To make sure that spans are created correctly for a custom routing setup, you'll need to opt out of the default span creation by setting `instrumentNavigation: false` and `instrumentPageLoad: false` in the `browserTracingIntegration()` options. You can then manually create spans like this: ```javascript Sentry.init({ @@ -27,7 +27,7 @@ let pageLoadSpan = Sentry.startBrowserTracingPageLoadSpan({ myRouter.on("routeChange", (route) => { const client = Sentry.getClient(); - // We want to make sure to update the pageload span to use the route name + // Make sure that the pageload span uses the route name // After that, each route change should trigger a navigation span (which will automatically finish the previous one) if (pageLoadSpan) { pageloadSpan.updateName(route.name);