feat(web-sdk): Properly allow users to override stack frame parsing settings

CHANGELOG.md

@@ -51,6 +51,12 @@ Breaking changes coming with Faro version 2
 - Chore (`@grafana/faro-*`): Remove Node.js 23 from build and test matrix as it's EoL (#1343)
 - Chore (`@grafana/faro-*`): upgrade to yarn 4
 
+- chore(`@grafana/faro web-sdk`): Move the stackFrames from the errors instrumentation package to the utils package (#1316)
+- improvement (`@grafana/faro-web-sdk`): Allow users to configure the stackTraceParser in the BrowserConfig (#1316)
+- improvement (`@grafana/faro-web-sdk`): Add `createStacktraceParser` function to create parsers with custom options (#1316)
+- chore(`@grafana/faro-web-sdk`): remove the setStackTraceParser function (#1316)
+- **BREAKING**: Remove `newStackTraceParser` function and `StacktraceParser` interface. Use `parseStacktrace` function directly or `createStacktraceParser` for custom options. Also simplified ExceptionsAPI by replacing `getStacktraceParser()` with direct `parseStacktrace` property (#1316)
+
 ## 1.18.2
 
 - Improvement (`@grafana/faro-web-sdk`): don't attach user action context to http request when in halt mode (#1249)

docs/sources/developer/architecture/components/api.md

@@ -24,7 +24,6 @@ like `web-sdk` or by the user.
 
 Methods:
 
-- `changeStacktraceParser` - replaces the existing stacktrace parser with a new one
 - `getStacktraceParser` - returns the current stacktrace parser
 - `pushError` - sends an exception
 

packages/core/src/api/exceptions/index.ts

@@ -9,7 +9,6 @@ export type {
   ExtendedError,
   PushErrorOptions,
   Stacktrace,
-  StacktraceParser,
   ErrorWithIndexProperties,
   ExceptionEventExtended,
 } from './types';

packages/core/src/api/exceptions/initialize.ts

@@ -21,9 +21,7 @@ import type { UserActionsAPI } from '../userActions';
 import { shouldIgnoreEvent } from '../utils';
 
 import { defaultExceptionType } from './const';
-import type { ErrorWithIndexProperties, ExceptionEvent, ExceptionsAPI, StacktraceParser } from './types';
-
-let stacktraceParser: StacktraceParser | undefined;
+import type { ErrorWithIndexProperties, ExceptionEvent, ExceptionsAPI } from './types';
 
 export function initializeExceptionsAPI({
   internalLogger,
@@ -45,15 +43,7 @@ export function initializeExceptionsAPI({
 
   let lastPayload: Pick<ExceptionEvent, 'type' | 'value' | 'stacktrace' | 'context'> | null = null;
 
-  stacktraceParser = config.parseStacktrace ?? stacktraceParser;
-
-  const changeStacktraceParser: ExceptionsAPI['changeStacktraceParser'] = (newStacktraceParser) => {
-    internalLogger.debug('Changing stacktrace parser');
-
-    stacktraceParser = newStacktraceParser ?? stacktraceParser;
-  };
-
-  const getStacktraceParser: ExceptionsAPI['getStacktraceParser'] = () => stacktraceParser;
+  const parseStacktrace = config.parseStacktrace;
 
   const { ignoreErrors = [], preserveOriginalError } = config;
 
@@ -87,8 +77,7 @@ export function initializeExceptionsAPI({
         },
         type: TransportItemType.EXCEPTION,
       };
-
-      stackFrames = stackFrames ?? (error.stack ? stacktraceParser?.(error).frames : undefined);
+      stackFrames = stackFrames ?? (error.stack ? parseStacktrace?.(error).frames : undefined);
 
       if (stackFrames?.length) {
         item.payload.stacktrace = {
@@ -124,11 +113,8 @@ export function initializeExceptionsAPI({
     }
   };
 
-  changeStacktraceParser(config.parseStacktrace);
-
   return {
-    changeStacktraceParser,
-    getStacktraceParser,
+    parseStacktrace,
     pushError,
   };
 }

packages/core/src/api/exceptions/types.ts

@@ -3,8 +3,6 @@ import type { SpanContext } from '@opentelemetry/api';
 import type { TraceContext } from '../traces';
 import type { UserAction } from '../types';
 
-export type StacktraceParser = (err: ExtendedError) => Stacktrace;
-
 export interface ExceptionStackFrame {
   filename: string;
   function: string;
@@ -72,7 +70,6 @@ export type ErrorWithIndexProperties = Error & {
 };
 
 export interface ExceptionsAPI {
-  changeStacktraceParser: (stacktraceParser: StacktraceParser) => void;
-  getStacktraceParser: () => StacktraceParser | undefined;
+  parseStacktrace: ((err: ExtendedError) => Stacktrace) | undefined;
   pushError: (value: ErrorWithIndexProperties, options?: PushErrorOptions) => void;
 }

packages/core/src/api/index.ts

@@ -11,7 +11,6 @@ export type {
   ExtendedError,
   PushErrorOptions,
   Stacktrace,
-  StacktraceParser,
   ExceptionEventExtended,
 } from './exceptions';
 

packages/core/src/api/initialize.test.ts

@@ -14,11 +14,10 @@ describe('initialize', () => {
     expect(api).toHaveProperty('pushMeasurement');
     expect(api).toHaveProperty('pushTraces');
     expect(api).toHaveProperty('pushEvent');
-    expect(api).toHaveProperty('changeStacktraceParser');
     expect(api).toHaveProperty('getOTEL');
     expect(api).toHaveProperty('getPage');
     expect(api).toHaveProperty('getSession');
-    expect(api).toHaveProperty('getStacktraceParser');
+    expect(api).toHaveProperty('parseStacktrace');
     expect(api).toHaveProperty('getTraceContext');
     expect(api).toHaveProperty('getView');
     expect(api).toHaveProperty('initOTEL');

packages/core/src/config/types.ts

@@ -1,4 +1,4 @@
-import type { APIEvent, LogArgsSerializer, StacktraceParser } from '../api';
+import type { APIEvent, ExtendedError, LogArgsSerializer, Stacktrace } from '../api';
 import type { Instrumentation } from '../instrumentations';
 import type { InternalLoggerLevel } from '../internalLogger';
 import type { Meta, MetaApp, MetaItem, MetaPage, MetaSession, MetaUser, MetaView } from '../metas';
@@ -57,9 +57,9 @@ export interface Config<P = APIEvent> {
   metas: MetaItem[];
 
   /**
-   * Custom function used to parse stack traces
+   * The stacktrace parser to use for parsing stack traces.
    */
-  parseStacktrace: StacktraceParser;
+  parseStacktrace?: (err: ExtendedError) => Stacktrace;
 
   /**
    * Pause sending data (default: false)

packages/core/src/index.ts

@@ -30,7 +30,6 @@ export type {
   PushLogOptions,
   PushMeasurementOptions,
   Stacktrace,
-  StacktraceParser,
   TraceContext,
   TraceEvent,
   TracesAPI,

packages/core/src/testUtils/mockStacktraceParser.ts

@@ -1,6 +1,6 @@
-import type { ExceptionStackFrame, StacktraceParser } from '../api';
+import type { ExceptionStackFrame, ExtendedError, Stacktrace } from '../api';
 
-export const mockStacktraceParser: StacktraceParser = (err) => {
+export const mockStacktraceParser = (err: ExtendedError): Stacktrace => {
   const frames: ExceptionStackFrame[] = [];
   const stack = err.stack ?? err.stacktrace;
 

packages/react/src/index.ts

@@ -182,7 +182,6 @@ export type {
   PushLogOptions,
   PushMeasurementOptions,
   Stacktrace,
-  StacktraceParser,
   TraceContext,
   TraceEvent,
   TracesAPI,

packages/web-sdk/src/config/makeCoreConfig.ts

@@ -12,13 +12,13 @@ import {
 import type { Config, Instrumentation, MetaItem, MetaSession, Transport } from '@grafana/faro-core';
 
 import { defaultEventDomain } from '../consts';
-import { parseStacktrace } from '../instrumentations';
 import { defaultSessionTrackingConfig } from '../instrumentations/session';
 import { userActionDataAttribute } from '../instrumentations/userActions/const';
 import { browserMeta } from '../metas';
 import { k6Meta } from '../metas/k6';
 import { createPageMeta } from '../metas/page';
 import { FetchTransport } from '../transports';
+import { parseStacktrace } from '../utils';
 
 import { getWebInstrumentations } from './getWebInstrumentations';
 import type { BrowserConfig } from './types';
@@ -79,7 +79,8 @@ export function makeCoreConfig(browserConfig: BrowserConfig): Config {
     isolate,
     logArgsSerializer,
     metas,
-    parseStacktrace,
+    // Use browser-provided parser or use parseStacktrace as default
+    parseStacktrace: browserConfig.parseStacktrace ?? parseStacktrace,
     paused,
     preventGlobalExposure,
     transports,

packages/web-sdk/src/config/types.ts

@@ -1,6 +1,6 @@
 import type { Config } from '@grafana/faro-core';
 
-export interface BrowserConfig extends Partial<Omit<Config, 'app' | 'parseStacktrace'>>, Pick<Config, 'app'> {
+export interface BrowserConfig extends Partial<Omit<Config, 'app'>>, Pick<Config, 'app'> {
   url?: string;
   apiKey?: string;
 }

packages/web-sdk/src/index.ts

@@ -6,12 +6,16 @@ export { defaultEventDomain } from './consts';
 export { initializeFaro } from './initialize';
 
 export {
-  buildStackFrame,
-  ConsoleInstrumentation,
-  ErrorsInstrumentation,
   getDataFromSafariExtensions,
   getStackFramesFromError,
   parseStacktrace,
+  createStacktraceParser,
+  buildStackFrame,
+} from './utils';
+
+export {
+  ConsoleInstrumentation,
+  ErrorsInstrumentation,
   ViewInstrumentation,
   WebVitalsInstrumentation,
   SessionInstrumentation,
@@ -151,7 +155,6 @@ export type {
   PushLogOptions,
   PushMeasurementOptions,
   Stacktrace,
-  StacktraceParser,
   TraceContext,
   TraceEvent,
   TracesAPI,

packages/web-sdk/src/instrumentations/errors/getErrorDetails.ts

@@ -1,12 +1,16 @@
 import { isDomError, isDomException, isError, isErrorEvent, isEvent, isObject, isString } from '@grafana/faro-core';
-import type { ExceptionStackFrame, LogArgsSerializer } from '@grafana/faro-core';
+import type { ExceptionStackFrame, ExtendedError, LogArgsSerializer, Stacktrace } from '@grafana/faro-core';
+
+import { buildStackFrame, parseStacktrace } from '../../utils/stackFrames';
 
 import { domErrorType, domExceptionType, objectEventValue, unknownSymbolString } from './const';
 import { getValueAndTypeFromMessage } from './getValueAndTypeFromMessage';
-import { buildStackFrame, getStackFramesFromError } from './stackFrames';
 import type { ErrorEvent } from './types';
 
-export function getErrorDetails(evt: ErrorEvent): [string | undefined, string | undefined, ExceptionStackFrame[]] {
+export function getErrorDetails(
+  evt: ErrorEvent,
+  stacktraceParser: (error: ExtendedError) => Stacktrace = parseStacktrace
+): [string | undefined, string | undefined, ExceptionStackFrame[]] {
   let value: string | undefined;
   let type: string | undefined;
   let stackFrames: ExceptionStackFrame[] = [];
@@ -16,15 +20,16 @@ export function getErrorDetails(evt: ErrorEvent): [string | undefined, string |
   if (isErrorEvent(evt) && evt.error) {
     value = evt.error.message;
     type = evt.error.name;
-    stackFrames = getStackFramesFromError(evt.error);
+    const { frames } = stacktraceParser(evt.error);
+    stackFrames = frames;
   } else if ((isDomErrorRes = isDomError(evt)) || isDomException(evt)) {
     const { name, message } = evt;
-
     type = name ?? (isDomErrorRes ? domErrorType : domExceptionType);
     value = message ? `${type}: ${message}` : type;
   } else if (isError(evt)) {
     value = evt.message;
-    stackFrames = getStackFramesFromError(evt);
+    const { frames } = stacktraceParser(evt);
+    stackFrames = frames;
   } else if (isObject(evt) || (isEventRes = isEvent(evt))) {
     type = isEventRes ? evt.constructor.name : undefined;
     value = `${objectEventValue} ${Object.keys(evt)}`;
@@ -39,7 +44,10 @@ export interface ErrorDetails {
   stackFrames?: ExceptionStackFrame[];
 }
 
-export function getDetailsFromErrorArgs(args: [any?, ...any[]]): ErrorDetails {
+export function getDetailsFromErrorArgs(
+  args: [any?, ...any[]],
+  stacktraceParser: (error: ExtendedError) => Stacktrace = parseStacktrace
+): ErrorDetails {
   const [evt, source, lineno, colno, error] = args;
 
   let value: string | undefined;
@@ -49,7 +57,7 @@ export function getDetailsFromErrorArgs(args: [any?, ...any[]]): ErrorDetails {
   const initialStackFrame = buildStackFrame(source, unknownSymbolString, lineno, colno);
 
   if (error || !eventIsString) {
-    [value, type, stackFrames] = getErrorDetails((error ?? evt) as Error | Event);
+    [value, type, stackFrames] = getErrorDetails((error ?? evt) as Error | Event, stacktraceParser);
 
     if (stackFrames.length === 0) {
       stackFrames = [initialStackFrame];

packages/web-sdk/src/instrumentations/errors/index.ts

@@ -1,5 +1,3 @@
 export { ErrorsInstrumentation } from './instrumentation';
 
-export { buildStackFrame, getDataFromSafariExtensions, getStackFramesFromError, parseStacktrace } from './stackFrames';
-
 export type { ErrorEvent, ExtendedPromiseRejectionEvent } from './types';

packages/web-sdk/src/instrumentations/errors/registerOnerror.ts

@@ -7,7 +7,7 @@ export function registerOnerror(api: API): void {
 
   window.onerror = (...args) => {
     try {
-      const { value, type, stackFrames } = getDetailsFromErrorArgs(args);
+      const { value, type, stackFrames } = getDetailsFromErrorArgs(args, api.parseStacktrace);
       const originalError = args[4];
 
       if (value) {

packages/web-sdk/src/instrumentations/errors/registerOnunhandledrejection.ts

@@ -22,7 +22,7 @@ export function registerOnunhandledrejection(api: API): void {
       value = `${primitiveUnhandledValue} ${String(error)}`;
       type = primitiveUnhandledType;
     } else {
-      [value, type, stackFrames] = getErrorDetails(error);
+      [value, type, stackFrames] = getErrorDetails(error, api.parseStacktrace);
     }
 
     if (value) {

packages/web-sdk/src/instrumentations/index.ts

@@ -2,13 +2,8 @@ export { SessionInstrumentation } from './session';
 
 export { ConsoleInstrumentation } from './console';
 
-export {
-  buildStackFrame,
-  ErrorsInstrumentation,
-  getDataFromSafariExtensions,
-  getStackFramesFromError,
-  parseStacktrace,
-} from './errors';
+export { ErrorsInstrumentation } from './errors';
+
 export type { ErrorEvent, ExtendedPromiseRejectionEvent } from './errors';
 
 export { ViewInstrumentation } from './view';

packages/web-sdk/src/utils/index.ts

@@ -11,3 +11,11 @@ export {
 export { throttle } from './throttle';
 
 export { getIgnoreUrls, getUrlFromResource } from './url';
+
+export {
+  buildStackFrame,
+  getDataFromSafariExtensions,
+  getStackFramesFromError,
+  parseStacktrace,
+  createStacktraceParser,
+} from './stackFrames';

packages/web-sdk/src/instrumentations/errors/stackFrames/getStackFramesFromError.test.ts → packages/web-sdk/src/utils/stackFrames/getStackFramesFromError.test.ts

@@ -181,6 +181,11 @@ describe('getStackFramesFromError', () => {
       buildStackFrame('http://path/to/file.js', 'bar', 108, 168),
     ]);
   });
+
+  it('should correctly skip lines if configured to', () => {
+    const result = getStackFramesFromError(CapturedExceptions.OPERA_25, { maximumLineLength: 36 });
+    expect(result).toEqual([buildStackFrame('http://path/to/file.js', undefined, 47, 22)]);
+  });
 });
 
 /* Taken from: https://github.com/stacktracejs/error-stack-parser/blob/master/spec/fixtures/captured-errors.js */

packages/web-sdk/src/instrumentations/errors/stackFrames/getStackFramesFromError.ts → packages/web-sdk/src/utils/stackFrames/getStackFramesFromError.ts

@@ -16,8 +16,12 @@ import {
   webkitLineRegex,
 } from './const';
 import { getDataFromSafariExtensions } from './getDataFromSafariExtensions';
+import type { StackframeParserOptions } from './types';
 
-export function getStackFramesFromError(error: ExtendedError): ExceptionStackFrame[] {
+export function getStackFramesFromError(
+  error: ExtendedError,
+  options: StackframeParserOptions = {}
+): ExceptionStackFrame[] {
   let lines: string[] = [];
 
   if (error.stacktrace) {
@@ -33,6 +37,13 @@ export function getStackFramesFromError(error: ExtendedError): ExceptionStackFra
     let lineno: string | undefined;
     let colno: string | undefined;
 
+    // skip attempting to parse stack frames over the limit, if it is set and above 0
+    if (options.maximumLineLength !== undefined && options.maximumLineLength > 0) {
+      if (line.length > options.maximumLineLength) {
+        return acc;
+      }
+    }
+
     if ((parts = webkitLineRegex.exec(line))) {
       func = parts[1];
       filename = parts[2];

packages/web-sdk/src/instrumentations/errors/stackFrames/index.ts → packages/web-sdk/src/utils/stackFrames/index.ts

@@ -4,4 +4,4 @@ export { getDataFromSafariExtensions } from './getDataFromSafariExtensions';
 
 export { getStackFramesFromError } from './getStackFramesFromError';
 
-export { parseStacktrace } from './parseStacktrace';
+export { parseStacktrace, createStacktraceParser } from './parseStacktrace';