feat(svelte): Add Component Tracking (#5612)

Add component tracking to the Sentry Svelte SDK
- inject function calls into components by using a preprocessor
- add preprocessor and tests

Author: Lms24

packages/svelte/package.json

@@ -19,11 +19,15 @@
     "@sentry/browser": "7.11.1",
     "@sentry/types": "7.11.1",
     "@sentry/utils": "7.11.1",
+    "magic-string": "^0.26.2",
     "tslib": "^1.9.3"
   },
   "peerDependencies": {
     "svelte": "3.x"
   },
+  "devDependencies": {
+    "svelte": "3.49.0"
+  },
   "scripts": {
     "build": "run-p build:rollup build:types",
     "build:dev": "run-s build",

packages/svelte/rollup.npm.config.js

@@ -1,3 +1,8 @@
 import { makeBaseNPMConfig, makeNPMConfigVariants } from '../../rollup/index.js';
 
-export default makeNPMConfigVariants(makeBaseNPMConfig());
+export default makeNPMConfigVariants(
+  makeBaseNPMConfig({
+    // Prevent 'svelte/internal' stuff from being included in the built JS
+    packageSpecificConfig: { external: ['svelte/internal'] },
+  }),
+);

packages/svelte/src/constants.ts

@@ -0,0 +1,5 @@
+export const UI_SVELTE_INIT = 'ui.svelte.init';
+
+export const UI_SVELTE_UPDATE = 'ui.svelte.update';
+
+export const DEFAULT_COMPONENT_NAME = 'Svelte Component';

packages/svelte/src/index.ts

@@ -1,3 +1,11 @@
+export type {
+  ComponentTrackingInitOptions as ComponentTrackingOptions,
+  TrackComponentOptions as TrackingOptions,
+} from './types';
+
 export * from '@sentry/browser';
 
 export { init } from './sdk';
+
+export { componentTrackingPreprocessor } from './preprocessors';
+export { trackComponent } from './performance';

packages/svelte/src/performance.ts

@@ -0,0 +1,96 @@
+import { getCurrentHub } from '@sentry/browser';
+import { Span, Transaction } from '@sentry/types';
+import { afterUpdate, beforeUpdate, onMount } from 'svelte';
+import { current_component } from 'svelte/internal';
+
+import { DEFAULT_COMPONENT_NAME, UI_SVELTE_INIT, UI_SVELTE_UPDATE } from './constants';
+import { TrackComponentOptions } from './types';
+
+const defaultTrackComponentOptions: {
+  trackInit: boolean;
+  trackUpdates: boolean;
+  componentName?: string;
+} = {
+  trackInit: true,
+  trackUpdates: true,
+};
+
+/**
+ * Tracks the Svelte component's intialization and mounting operation as well as
+ * updates and records them as spans.
+ * This function is injected automatically into your Svelte components' code
+ * if you are using the Sentry componentTrackingPreprocessor.
+ * Alternatively, you can call it yourself if you don't want to use the preprocessor.
+ */
+export function trackComponent(options?: TrackComponentOptions): void {
+  const mergedOptions = { ...defaultTrackComponentOptions, ...options };
+
+  const transaction = getActiveTransaction();
+  if (!transaction) {
+    return;
+  }
+
+  const customComponentName = mergedOptions.componentName;
+
+  // current_component.ctor.name is likely to give us the component's name automatically
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+  const componentName = `<${customComponentName || current_component.constructor.name || DEFAULT_COMPONENT_NAME}>`;
+
+  let initSpan: Span | undefined = undefined;
+  if (mergedOptions.trackInit) {
+    initSpan = recordInitSpan(transaction, componentName);
+  }
+
+  if (mergedOptions.trackUpdates) {
+    recordUpdateSpans(componentName, initSpan);
+  }
+}
+
+function recordInitSpan(transaction: Transaction, componentName: string): Span {
+  const initSpan = transaction.startChild({
+    op: UI_SVELTE_INIT,
+    description: componentName,
+  });
+
+  onMount(() => {
+    initSpan.finish();
+  });
+
+  return initSpan;
+}
+
+function recordUpdateSpans(componentName: string, initSpan?: Span): void {
+  let updateSpan: Span | undefined;
+  beforeUpdate(() => {
+    // We need to get the active transaction again because the initial one could
+    // already be finished or there is currently no transaction going on.
+    const transaction = getActiveTransaction();
+    if (!transaction) {
+      return;
+    }
+
+    // If we are initializing the component when the update span is started, we start it as child
+    // of the init span. Else, we start it as a child of the transaction.
+    const parentSpan =
+      initSpan && !initSpan.endTimestamp && initSpan.transaction === transaction ? initSpan : transaction;
+
+    updateSpan = parentSpan.startChild({
+      op: UI_SVELTE_UPDATE,
+      description: componentName,
+    });
+  });
+
+  afterUpdate(() => {
+    if (!updateSpan) {
+      return;
+    }
+    updateSpan.finish();
+    updateSpan = undefined;
+  });
+}
+
+function getActiveTransaction(): Transaction | undefined {
+  const currentHub = getCurrentHub();
+  const scope = currentHub && currentHub.getScope();
+  return scope && scope.getTransaction();
+}

packages/svelte/src/preprocessors.ts

@@ -0,0 +1,89 @@
+import MagicString from 'magic-string';
+
+import { ComponentTrackingInitOptions, PreprocessorGroup, TrackComponentOptions } from './types';
+
+export const defaultComponentTrackingOptions: Required<ComponentTrackingInitOptions> = {
+  trackComponents: true,
+  trackInit: true,
+  trackUpdates: true,
+};
+
+/**
+ * Svelte Preprocessor to inject Sentry performance monitoring related code
+ * into Svelte components.
+ */
+export function componentTrackingPreprocessor(options?: ComponentTrackingInitOptions): PreprocessorGroup {
+  const mergedOptions = { ...defaultComponentTrackingOptions, ...options };
+
+  const visitedFiles = new Set<string>();
+
+  return {
+    // This script hook is called whenever a Svelte component's <script>
+    // content is preprocessed.
+    // `content` contains the script code as a string
+    script: ({ content, filename, attributes }) => {
+      // TODO: Not sure when a filename could be undefined. Using this 'unknown' fallback for the time being
+      const finalFilename = filename || 'unknown';
+
+      if (!shouldInjectFunction(mergedOptions.trackComponents, finalFilename, attributes, visitedFiles)) {
+        return { code: content };
+      }
+
+      const { trackInit, trackUpdates } = mergedOptions;
+      const trackComponentOptions: TrackComponentOptions = {
+        trackInit,
+        trackUpdates,
+        componentName: getBaseName(finalFilename),
+      };
+
+      const importStmt = 'import { trackComponent } from "@sentry/svelte";\n';
+      const functionCall = `trackComponent(${JSON.stringify(trackComponentOptions)});\n`;
+
+      const s = new MagicString(content);
+      s.prepend(functionCall).prepend(importStmt);
+
+      const updatedCode = s.toString();
+      const updatedSourceMap = s.generateMap().toString();
+
+      return { code: updatedCode, map: updatedSourceMap };
+    },
+  };
+}
+
+function shouldInjectFunction(
+  trackComponents: Required<ComponentTrackingInitOptions['trackComponents']>,
+  filename: string,
+  attributes: Record<string, string | boolean>,
+  visitedFiles: Set<string>,
+): boolean {
+  // We do cannot inject our function multiple times into the same component
+  // This can happen when a component has multiple <script> blocks
+  if (visitedFiles.has(filename)) {
+    return false;
+  }
+  visitedFiles.add(filename);
+
+  // We can't inject our function call into <script context="module"> blocks
+  // because the code inside is not executed when the component is instantiated but
+  // when the module is first imported.
+  // see: https://svelte.dev/docs#component-format-script-context-module
+  if (attributes.context === 'module') {
+    return false;
+  }
+
+  if (!trackComponents) {
+    return false;
+  }
+
+  if (Array.isArray(trackComponents)) {
+    const componentName = getBaseName(filename);
+    return trackComponents.some(allowed => allowed === componentName);
+  }
+
+  return true;
+}
+
+function getBaseName(filename: string): string {
+  const segments = filename.split('/');
+  return segments[segments.length - 1].replace('.svelte', '');
+}

packages/svelte/src/types.ts

@@ -0,0 +1,77 @@
+// The following types were copied from 'svelte/compiler'-internal
+// type definitions
+// see: https://github.com/sveltejs/svelte/blob/master/src/compiler/preprocess/types.ts
+interface Processed {
+  code: string;
+  map?: string | Record<string, unknown>;
+  dependencies?: string[];
+  toString?: () => string;
+}
+
+type MarkupPreprocessor = (options: {
+  content: string;
+  filename?: string;
+}) => Processed | void | Promise<Processed | void>;
+
+type Preprocessor = (options: {
+  /**
+   * The script/style tag content
+   */
+  content: string;
+  attributes: Record<string, string | boolean>;
+  /**
+   * The whole Svelte file content
+   */
+  markup: string;
+  filename?: string;
+}) => Processed | void | Promise<Processed | void>;
+
+export interface PreprocessorGroup {
+  markup?: MarkupPreprocessor;
+  style?: Preprocessor;
+  script?: Preprocessor;
+}
+
+// Alternatively, we could use a direct from svelte/compiler/preprocess
+// TODO: figure out what's better and roll with that
+// import { PreprocessorGroup } from 'svelte/types/compiler/preprocess';
+
+export type SpanOptions = {
+  /**
+   * If true, a span is recorded between a component's intialization and its
+   * onMount lifecycle hook. This span tells how long it takes a component
+   * to be created and inserted into the DOM.
+   *
+   * Defaults to true if component tracking is enabled
+   */
+  trackInit?: boolean;
+
+  /**
+   * If true, a span is recorded between a component's beforeUpdate and afterUpdate
+   * lifecycle hooks.
+   *
+   * Defaults to true if component tracking is enabled
+   */
+  trackUpdates?: boolean;
+};
+
+/**
+ * Control which components and which operations should be tracked
+ * and recorded as spans
+ */
+export type ComponentTrackingInitOptions = {
+  /**
+   * Control if all your Svelte components should be tracked or only a specified list
+   * of components.
+   * If set to true, all components will be tracked.
+   * If you only want to track a selection of components, specify the component names
+   * as an array.
+   *
+   * Defaults to true if the preprocessor is used
+   */
+  trackComponents?: boolean | string[];
+} & SpanOptions;
+
+export type TrackComponentOptions = {
+  componentName?: string;
+} & SpanOptions;