feat: Add docs for custom browser tracing routing instrumentation (#9113

)



---------

Co-authored-by: Liza Mock <[email protected]>

platform-includes/performance/automatic-instrumentation-custom-routing/javascript.mdx

@@ -0,0 +1,46 @@
+### Custom Routing
+
+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.
+
+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({
+  integrations: [
+    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();
+
+  // 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);
+    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",
+      },
+    });
+  }
+});
+```

platform-includes/performance/enable-automatic-instrumentation/javascript.mdx

@@ -19,3 +19,5 @@ Sentry.init({
   tracesSampleRate: 1.0,
 });
 ```
+
+<PlatformContent includePath="performance/automatic-instrumentation-custom-routing" />

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/).
+
+<PlatformContent includePath="performance/automatic-instrumentation-custom-routing" />