feat(sveltekit): Add SvelteKit routing instrumentation

packages/sveltekit/package.json

@@ -30,6 +30,7 @@
   },
   "devDependencies": {
     "@sveltejs/kit": "^1.11.0",
+    "svelte": "^3.44.0",
     "typescript": "^4.9.3",
     "vite": "4.0.0"
   },

packages/sveltekit/rollup.npm.config.js

@@ -1,14 +1,10 @@
 import { makeBaseNPMConfig, makeNPMConfigVariants } from '../../rollup/index.js';
 
-export default
-  makeNPMConfigVariants(
-    makeBaseNPMConfig({
-      entrypoints: [
-        'src/index.server.ts',
-        'src/index.client.ts',
-        'src/client/index.ts',
-        'src/server/index.ts',
-      ],
-    }),
-  )
-;
+export default makeNPMConfigVariants(
+  makeBaseNPMConfig({
+    entrypoints: ['src/index.server.ts', 'src/index.client.ts', 'src/client/index.ts', 'src/server/index.ts'],
+    packageSpecificConfig: {
+      external: ['$app/stores'],
+    },
+  }),
+);

packages/sveltekit/src/client/router.ts

@@ -0,0 +1,111 @@
+import { getActiveTransaction } from '@sentry/core';
+import { WINDOW } from '@sentry/svelte';
+import type { Span, Transaction, TransactionContext } from '@sentry/types';
+
+import { navigating, page } from '$app/stores';
+
+const DEFAULT_TAGS = {
+  'routing.instrumentation': '@sentry/sveltekit',
+};
+
+/**
+ * Automatically creates pageload and navigation transactions for the client-side SvelteKit router.
+ *
+ * This instrumentation makes use of SvelteKit's `page` and `navigating` stores which can be accessed
+ * anywhere on the client side.
+ *
+ * @param startTransactionFn the function used to start (idle) transactions
+ * @param startTransactionOnPageLoad controls if pageload transactions should be created (defaults to `true`)
+ * @param startTransactionOnLocationChange controls if navigation transactions should be created (defauls to `true`)
+ */
+export function svelteKitRoutingInstrumentation<T extends Transaction>(
+  startTransactionFn: (context: TransactionContext) => T | undefined,
+  startTransactionOnPageLoad: boolean = true,
+  startTransactionOnLocationChange: boolean = true,
+): void {
+  if (startTransactionOnPageLoad) {
+    instrumentPageload(startTransactionFn);
+  }
+
+  if (startTransactionOnLocationChange) {
+    instrumentNavigations(startTransactionFn);
+  }
+}
+
+function instrumentPageload(startTransactionFn: (context: TransactionContext) => Transaction | undefined): void {
+  const initialPath = WINDOW && WINDOW.location && WINDOW.location.pathname;
+
+  const pageloadTransaction = startTransactionFn({
+    name: initialPath,
+    op: 'pageload',
+    description: initialPath,
+    tags: {
+      ...DEFAULT_TAGS,
+    },
+  });
+
+  page.subscribe(page => {
+    if (!page) {
+      return;
+    }
+
+    const routeId = page.route && page.route.id;
+
+    if (pageloadTransaction && routeId) {
+      pageloadTransaction.setName(routeId, 'route');
+    }
+  });
+}
+
+/**
+ * Use the `navigating` store to start a transaction on navigations.
+ */
+function instrumentNavigations(startTransactionFn: (context: TransactionContext) => Transaction | undefined): void {
+  let routingSpan: Span | undefined = undefined;
+  let activeTransaction: Transaction | undefined;
+
+  navigating.subscribe(navigation => {
+    if (!navigation) {
+      // `navigating` emits a 'null' value when the navigation is completed.
+      // So in this case, we can finish the routing span. If the transaction was an IdleTransaction,
+      // it will finish automatically and if it was user-created users also need to finish it.
+      if (routingSpan) {
+        routingSpan.finish();
+        routingSpan = undefined;
+      }
+      return;
+    }
+
+    const routeDestination = navigation.to && navigation.to.route.id;
+    const routeOrigin = navigation.from && navigation.from.route.id;
+
+    if (routeOrigin === routeDestination) {
+      return;
+    }
+
+    activeTransaction = getActiveTransaction();
+
+    if (!activeTransaction) {
+      activeTransaction = startTransactionFn({
+        name: routeDestination || (WINDOW && WINDOW.location && WINDOW.location.pathname),
+        op: 'navigation',
+        metadata: { source: 'route' },
+        tags: {
+          ...DEFAULT_TAGS,
+        },
+      });
+    }
+
+    if (activeTransaction) {
+      if (routingSpan) {
+        // If a routing span is still open from a previous navigation, we finish it.
+        routingSpan.finish();
+      }
+      routingSpan = activeTransaction.startChild({
+        op: 'ui.sveltekit.routing',
+        description: 'SvelteKit Route Change',
+      });
+      activeTransaction.setTag('from', routeOrigin);
+    }
+  });
+}

packages/sveltekit/src/client/sdk.ts

@@ -1,17 +1,18 @@
-import { defaultRequestInstrumentationOptions } from '@sentry-internal/tracing';
 import { hasTracingEnabled } from '@sentry/core';
 import type { BrowserOptions } from '@sentry/svelte';
 import { BrowserTracing, configureScope, init as initSvelteSdk } from '@sentry/svelte';
 import { addOrUpdateIntegration } from '@sentry/utils';
 
 import { applySdkMetadata } from '../common/metadata';
+import { svelteKitRoutingInstrumentation } from './router';
 
 // Treeshakable guard to remove all code related to tracing
 declare const __SENTRY_TRACING__: boolean;
 
 /**
+ * Initialize the client side of the Sentry SvelteKit SDK.
  *
- * @param options
+ * @param options Configuration options for the SDK.
  */
 export function init(options: BrowserOptions): void {
   applySdkMetadata(options, ['sveltekit', 'svelte']);
@@ -33,14 +34,11 @@ function addClientIntegrations(options: BrowserOptions): void {
   if (typeof __SENTRY_TRACING__ === 'undefined' || __SENTRY_TRACING__) {
     if (hasTracingEnabled(options)) {
       const defaultBrowserTracingIntegration = new BrowserTracing({
-        tracePropagationTargets: [...defaultRequestInstrumentationOptions.tracePropagationTargets],
-        // TODO: Add SvelteKit router instrumentations
-        // routingInstrumentation: sveltekitRoutingInstrumentation,
+        routingInstrumentation: svelteKitRoutingInstrumentation,
       });
 
       integrations = addOrUpdateIntegration(defaultBrowserTracingIntegration, integrations, {
-        // TODO: Add SvelteKit router instrumentations
-        // options.routingInstrumentation: sveltekitRoutingInstrumentation,
+        'options.routingInstrumentation': svelteKitRoutingInstrumentation,
       });
     }
   }

packages/sveltekit/test/client/router.test.ts

@@ -0,0 +1,139 @@
+/* eslint-disable @typescript-eslint/unbound-method */
+import type { Transaction } from '@sentry/types';
+import { writable } from 'svelte/store';
+import type { SpyInstance } from 'vitest';
+import { vi } from 'vitest';
+
+import { navigating, page } from '$app/stores';
+
+import { svelteKitRoutingInstrumentation } from '../../src/client/router';
+
+// we have to overwrite the global mock from `vitest.setup.ts` here to reset the
+// `navigating` store for each test.
+vi.mock('$app/stores', async () => {
+  return {
+    get navigating() {
+      return navigatingStore;
+    },
+    page: writable(),
+  };
+});
+
+let navigatingStore = writable();
+
+describe('sveltekitRoutingInstrumentation', () => {
+  let returnedTransaction: (Transaction & { returnedTransaction: SpyInstance }) | undefined;
+  const mockedStartTransaction = vi.fn().mockImplementation(txnCtx => {
+    returnedTransaction = {
+      ...txnCtx,
+      setName: vi.fn(),
+      startChild: vi.fn().mockImplementation(ctx => {
+        return { ...mockedRoutingSpan, ...ctx };
+      }),
+      setTag: vi.fn(),
+    };
+    return returnedTransaction;
+  });
+
+  const mockedRoutingSpan = {
+    finish: () => {},
+  };
+
+  const routingSpanFinishSpy = vi.spyOn(mockedRoutingSpan, 'finish');
+
+  beforeEach(() => {
+    navigatingStore = writable();
+    vi.clearAllMocks();
+  });
+
+  it("starts a pageload transaction when it's called with default params", () => {
+    svelteKitRoutingInstrumentation(mockedStartTransaction);
+
+    expect(mockedStartTransaction).toHaveBeenCalledTimes(1);
+    expect(mockedStartTransaction).toHaveBeenCalledWith({
+      name: '/',
+      op: 'pageload',
+      description: '/',
+      tags: {
+        'routing.instrumentation': '@sentry/sveltekit',
+      },
+    });
+
+    // We emit an update to the `page` store to simulate the SvelteKit router lifecycle
+    // @ts-ignore This is fine because we testUtils/stores.ts defines `page` as a writable store
+    page.set({ route: { id: 'testRoute' } });
+
+    // This should update the transaction name with the parameterized route:
+    expect(returnedTransaction?.setName).toHaveBeenCalledTimes(1);
+    expect(returnedTransaction?.setName).toHaveBeenCalledWith('testRoute', 'route');
+  });
+
+  it("doesn't start a pageload transaction if `startTransactionOnPageLoad` is false", () => {
+    svelteKitRoutingInstrumentation(mockedStartTransaction, false);
+    expect(mockedStartTransaction).toHaveBeenCalledTimes(0);
+  });
+
+  it("doesn't starts a navigation transaction when `startTransactionOnLocationChange` is false", () => {
+    svelteKitRoutingInstrumentation(mockedStartTransaction, false, false);
+
+    // We emit an update to the `navigating` store to simulate the SvelteKit navigation lifecycle
+    // @ts-ignore This is fine because we testUtils/stores.ts defines `navigating` as a writable store
+    navigating.set(
+      { from: { route: { id: 'testNavigationOrigin' } } },
+      { to: { route: { id: 'testNavigationDestination' } } },
+    );
+
+    // This should update the transaction name with the parameterized route:
+    expect(mockedStartTransaction).toHaveBeenCalledTimes(0);
+  });
+
+  it('starts a navigation transaction when `startTransactionOnLocationChange` is true', () => {
+    svelteKitRoutingInstrumentation(mockedStartTransaction, false, true);
+
+    // We emit an update to the `navigating` store to simulate the SvelteKit navigation lifecycle
+    // @ts-ignore This is fine because we testUtils/stores.ts defines `navigating` as a writable store
+    navigating.set({
+      from: { route: { id: 'testNavigationOrigin' } },
+      to: { route: { id: 'testNavigationDestination' } },
+    });
+
+    // This should update the transaction name with the parameterized route:
+    expect(mockedStartTransaction).toHaveBeenCalledTimes(1);
+    expect(mockedStartTransaction).toHaveBeenCalledWith({
+      name: 'testNavigationDestination',
+      op: 'navigation',
+      metadata: {
+        source: 'route',
+      },
+      tags: {
+        'routing.instrumentation': '@sentry/sveltekit',
+      },
+    });
+
+    expect(returnedTransaction?.startChild).toHaveBeenCalledWith({
+      op: 'ui.sveltekit.routing',
+      description: 'SvelteKit Route Change',
+    });
+
+    expect(returnedTransaction?.setTag).toHaveBeenCalledWith('from', 'testNavigationOrigin');
+
+    // We emit `null` here to simulate the end of the navigation lifecycle
+    // @ts-ignore this is fine
+    navigating.set(null);
+
+    expect(routingSpanFinishSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it("doesn't start a navigation transaction if navigation origin and destination are equal", () => {
+    svelteKitRoutingInstrumentation(mockedStartTransaction, false, true);
+
+    // We emit an update to the `navigating` store to simulate the SvelteKit navigation lifecycle
+    // @ts-ignore This is fine because we testUtils/stores.ts defines `navigating` as a writable store
+    navigating.set({
+      from: { route: { id: 'testRoute' } },
+      to: { route: { id: 'testRoute' } },
+    });
+
+    expect(mockedStartTransaction).toHaveBeenCalledTimes(0);
+  });
+});

packages/sveltekit/test/client/sdk.test.ts

@@ -5,6 +5,7 @@ import { SDK_VERSION, WINDOW } from '@sentry/svelte';
 import { vi } from 'vitest';
 
 import { BrowserTracing, init } from '../../src/client';
+import { svelteKitRoutingInstrumentation } from '../../src/client/router';
 
 const svelteInit = vi.spyOn(SentrySvelte, 'init');
 
@@ -87,6 +88,7 @@ describe('Sentry client SDK', () => {
         // This is the closest we can get to unit-testing the `__SENTRY_TRACING__` tree-shaking guard
         // IRL, the code to add the integration would most likely be removed by the bundler.
 
+        // @ts-ignore this is fine in the test
         globalThis.__SENTRY_TRACING__ = false;
 
         init({
@@ -100,24 +102,35 @@ describe('Sentry client SDK', () => {
         expect(integrationsToInit).not.toContainEqual(expect.objectContaining({ name: 'BrowserTracing' }));
         expect(browserTracing).toBeUndefined();
 
+        // @ts-ignore this is fine in the test
         delete globalThis.__SENTRY_TRACING__;
       });
 
-      // TODO: this test is only meaningful once we have a routing instrumentation which we always want to add
-      // to a user-provided BrowserTracing integration (see NextJS SDK)
-      it.skip('Merges the user-provided BrowserTracing integration with the automatically added one', () => {
+      it('Merges a user-provided BrowserTracing integration with the automatically added one', () => {
         init({
           dsn: 'https://[email protected]/1337',
-          integrations: [new BrowserTracing({ tracePropagationTargets: ['myDomain.com'] })],
+          integrations: [
+            new BrowserTracing({ tracePropagationTargets: ['myDomain.com'], startTransactionOnLocationChange: false }),
+          ],
           enableTracing: true,
         });
 
         const integrationsToInit = svelteInit.mock.calls[0][0].integrations;
-        const browserTracing = (getCurrentHub().getClient() as BrowserClient)?.getIntegrationById('BrowserTracing');
+
+        const browserTracing = (getCurrentHub().getClient() as BrowserClient)?.getIntegrationById(
+          'BrowserTracing',
+        ) as BrowserTracing;
+        const options = browserTracing.options;
 
         expect(integrationsToInit).toContainEqual(expect.objectContaining({ name: 'BrowserTracing' }));
         expect(browserTracing).toBeDefined();
-        expect((browserTracing as BrowserTracing).options.tracePropagationTargets).toEqual(['myDomain.com']);
+
+        // This shows that the user-configured options are still here
+        expect(options.tracePropagationTargets).toEqual(['myDomain.com']);
+        expect(options.startTransactionOnLocationChange).toBe(false);
+
+        // But we force the routing instrumentation to be ours
+        expect(options.routingInstrumentation).toEqual(svelteKitRoutingInstrumentation);
       });
     });
   });

packages/sveltekit/test/vitest.setup.ts

@@ -0,0 +1,13 @@
+import { writable } from 'svelte/store';
+import { vi } from 'vitest';
+
+export function setup() {
+  // mock $app/stores because vitest can't resolve this import from SvelteKit.
+  // Seems like $app/stores is only created at build time of a SvelteKit app.
+  vi.mock('$app/stores', async () => {
+    return {
+      navigating: writable(),
+      page: writable(),
+    };
+  });
+}