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

CHANGELOG.md

@@ -8,6 +8,10 @@
   URL structure (#1297)
 - chore(user actions): Rename `userActionEventType` to `userActionTrigger` for improved clarity (#1298)
 
+- 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)
+- chore(`@grafana/faro-web-sdk`): remove the setStackTraceParser function (#1316)
+
 ## 1.18.2
 
 - fix(user actions): 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/initialize.ts

@@ -23,9 +23,7 @@ import type { ApiMessageBusMessages } from '../types';
 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,
@@ -49,15 +47,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 getStacktraceParser: ExceptionsAPI['getStacktraceParser'] = () => config.parseStacktrace;
 
   const { ignoreErrors = [], preserveOriginalError } = config;
 
@@ -91,7 +81,7 @@ export function initializeExceptionsAPI({
         },
         type: TransportItemType.EXCEPTION,
       };
-
+      const stacktraceParser = getStacktraceParser();
       stackFrames = stackFrames ?? (error.stack ? stacktraceParser?.(error).frames : undefined);
 
       if (stackFrames?.length) {
@@ -128,10 +118,7 @@ export function initializeExceptionsAPI({
     }
   };
 
-  changeStacktraceParser(config.parseStacktrace);
-
   return {
-    changeStacktraceParser,
     getStacktraceParser,
     pushError,
   };

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

@@ -72,7 +72,6 @@ export type ErrorWithIndexProperties = Error & {
 };
 
 export interface ExceptionsAPI {
-  changeStacktraceParser: (stacktraceParser: StacktraceParser) => void;
   getStacktraceParser: () => StacktraceParser | undefined;
   pushError: (value: ErrorWithIndexProperties, options?: PushErrorOptions) => void;
 }

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

@@ -17,7 +17,6 @@ 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');

packages/core/src/config/types.ts

@@ -57,7 +57,7 @@ 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;
 

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';
@@ -65,6 +65,9 @@ export function makeCoreConfig(browserConfig: BrowserConfig): Config {
     ...restProperties
   }: BrowserConfig = browserConfig;
 
+  // use the default stacktrace parser (parseStacktrace) if no custom stacktrace parser is provided
+  const stackTraceParser = browserConfig.parseStacktrace ?? parseStacktrace;
+
   return {
     ...restProperties,
 
@@ -79,7 +82,7 @@ export function makeCoreConfig(browserConfig: BrowserConfig): Config {
     isolate,
     logArgsSerializer,
     metas,
-    parseStacktrace,
+    parseStacktrace: stackTraceParser,
     paused,
     preventGlobalExposure,
     transports,

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

@@ -1,6 +1,6 @@
 import type { Config, LogLevel } 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

@@ -5,13 +5,11 @@ export { defaultEventDomain } from './consts';
 
 export { initializeFaro } from './initialize';
 
+export { getDataFromSafariExtensions, getStackFramesFromError, parseStacktrace, newStackTraceParser, buildStackFrame } from './utils';
+
 export {
-  buildStackFrame,
   ConsoleInstrumentation,
   ErrorsInstrumentation,
-  getDataFromSafariExtensions,
-  getStackFramesFromError,
-  parseStacktrace,
   ViewInstrumentation,
   WebVitalsInstrumentation,
   SessionInstrumentation,

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, LogArgsSerializer, StacktraceParser } from '@grafana/faro-core';
+
+import { buildStackFrame, newStackTraceParser } 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: StacktraceParser = newStackTraceParser()
+): [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: StacktraceParser = newStackTraceParser()
+): 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.getStacktraceParser());
       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.getStacktraceParser());
     }
 
     if (value) {

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

@@ -3,13 +3,8 @@ export { SessionInstrumentation } from './session';
 export { ConsoleInstrumentation } from './console';
 export type { ConsoleInstrumentationOptions } 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,
+  newStackTraceParser,
+} from './stackFrames';

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

@@ -157,6 +157,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, newStackTraceParser } from './parseStacktrace';

packages/web-sdk/src/utils/stackFrames/parseStacktrace.ts

@@ -0,0 +1,18 @@
+import type { ExtendedError, Stacktrace, StacktraceParser } from '@grafana/faro-core';
+
+import { getStackFramesFromError } from './getStackFramesFromError';
+import type { StackframeParserOptions } from './types';
+
+export function parseStacktrace(error: ExtendedError): Stacktrace {
+  return {
+    frames: getStackFramesFromError(error),
+  };
+}
+
+export function newStackTraceParser(options?: StackframeParserOptions): StacktraceParser {
+  return (error: ExtendedError) => {
+    return {
+      frames: getStackFramesFromError(error, options),
+    };
+  };
+}

packages/web-sdk/src/utils/stackFrames/types.ts

@@ -0,0 +1,3 @@
+export interface StackframeParserOptions {
+  maximumLineLength?: number;
+}