@grafana/faro-react-native 1.1.0 → 1.2.1

package/src/instrumentations/errors/index.ts

@@ -40,6 +40,12 @@ export interface ErrorsInstrumentationOptions {
    * Older errors are removed when this limit is reached
    */
   maxDeduplicationEntries?: number;
+
+  /**
+   * Bundle filename for Hermes/minified release lines (`func@line:col`).
+   * Must match the Metro plugin source map `file` field (default `bundle.js`).
+   */
+  releaseBundleFilename?: string;
 }
 
 interface ErrorFingerprint {
@@ -80,7 +86,9 @@ export class ErrorsInstrumentation extends BaseInstrumentation {
 
   private originalErrorHandler?: ErrorHandlerCallback;
   private unhandledRejectionListener?: (event: PromiseRejectionEvent) => void;
-  private options: Required<ErrorsInstrumentationOptions>;
+  private options: Required<Omit<ErrorsInstrumentationOptions, 'releaseBundleFilename'>> & {
+    releaseBundleFilename?: string;
+  };
   private errorFingerprints: ErrorFingerprint[] = [];
 
   constructor(options: ErrorsInstrumentationOptions = {}) {
@@ -90,6 +98,7 @@ export class ErrorsInstrumentation extends BaseInstrumentation {
       enableDeduplication: options.enableDeduplication ?? true,
       deduplicationWindow: options.deduplicationWindow ?? 5000,
       maxDeduplicationEntries: options.maxDeduplicationEntries ?? 50,
+      releaseBundleFilename: options.releaseBundleFilename,
     };
   }
 
@@ -123,10 +132,14 @@ export class ErrorsInstrumentation extends BaseInstrumentation {
           error: enhancedError,
           stackFrames,
           context,
-        } = enhanceErrorWithContext(error, {
-          mechanism: ErrorMechanism.UNCAUGHT,
-          isFatal: String(isFatal ?? false),
-        });
+        } = enhanceErrorWithContext(
+          error,
+          {
+            mechanism: ErrorMechanism.UNCAUGHT,
+            isFatal: String(isFatal ?? false),
+          },
+          { releaseBundleFilename: this.options.releaseBundleFilename }
+        );
 
         // Push error to Faro with enhanced data (type from error.name, matches Web SDK)
         this.api.pushError(enhancedError, {
@@ -182,9 +195,13 @@ export class ErrorsInstrumentation extends BaseInstrumentation {
           error: enhancedError,
           stackFrames,
           context,
-        } = enhanceErrorWithContext(error, {
-          mechanism: ErrorMechanism.UNHANDLED_REJECTION,
-        });
+        } = enhanceErrorWithContext(
+          error,
+          {
+            mechanism: ErrorMechanism.UNHANDLED_REJECTION,
+          },
+          { releaseBundleFilename: this.options.releaseBundleFilename }
+        );
 
         // Type: use actual error type for Error objects; 'UnhandledRejection' for primitives (Web SDK)
         const errorType = isPrimitiveRejection ? primitiveUnhandledType : enhancedError.name || 'Error';

package/src/instrumentations/errors/stackTraceParser.test.ts

@@ -65,6 +65,29 @@ describe('Stack Trace Parser', () => {
         filename: '<unknown>',
         lineno: 123,
         colno: 456,
+        releaseLine: true,
+      });
+    });
+
+    it('should normalize Hermes Android "address at index.android.bundle" file segment', () => {
+      const line = '  at someFunction (address at index.android.bundle:42:15)';
+      const frame = parseStackTraceLine(line);
+
+      expect(frame).toEqual({
+        function: 'someFunction',
+        filename: 'index.android.bundle',
+        lineno: 42,
+        colno: 15,
+      });
+    });
+
+    it('should parse Hermes-style parenthesis frame with bundle filename', () => {
+      const line = '  at reportError (index.android.bundle:1:849989)';
+      expect(parseStackTraceLine(line)).toEqual({
+        function: 'reportError',
+        filename: 'index.android.bundle',
+        lineno: 1,
+        colno: 849989,
       });
     });
 
@@ -165,6 +188,39 @@ describe('Stack Trace Parser', () => {
       const faroFrames = toFaroStackFrames([]);
       expect(faroFrames).toEqual([]);
     });
+
+    it('maps release placeholders to bundle.js in Faro frames', () => {
+      const parsed = parseStackTraceLine('a@123:456');
+      expect(parsed).not.toBeNull();
+      const faroFrames = toFaroStackFrames([parsed!]);
+      expect(faroFrames[0]?.filename).toBe('bundle.js');
+    });
+
+    it('maps release placeholders to a custom bundle filename', () => {
+      const parsed = parseStackTraceLine('a@123:456');
+      expect(parsed).not.toBeNull();
+      const faroFrames = toFaroStackFrames([parsed!], { releaseBundleFilename: 'index.android.bundle' });
+      expect(faroFrames[0]?.filename).toBe('index.android.bundle');
+    });
+
+    it('collapses Hermes absolute .app bundle path to basename so uploads match ingest keys', () => {
+      const iosPath =
+        '/Users/ci/Library/Developer/CoreSimulator/Devices/ABC/Data/Containers/Bundle/Application/62A2/QuickPizza.app/main.jsbundle';
+      const parsed = parseStackTraceLine(`  at reportHandledException (${iosPath}:1:1249030)`);
+      expect(parsed).not.toBeNull();
+      const faroFrames = toFaroStackFrames([parsed!], { releaseBundleFilename: 'main.jsbundle' });
+      expect(faroFrames[0]?.filename).toBe('main.jsbundle');
+      expect(faroFrames[0]?.lineno).toBe(1);
+      expect(faroFrames[0]?.colno).toBe(1249030);
+    });
+
+    it('collapses absolute Android artifact path ending in index.android.bundle', () => {
+      const apkPath = '/data/app/org.example.cp/base.apk/assets/index.android.bundle';
+      const parsed = parseStackTraceLine(`  at reportError (${apkPath}:1:849989)`);
+      expect(parsed).not.toBeNull();
+      const faroFrames = toFaroStackFrames([parsed!], { releaseBundleFilename: 'index.android.bundle' });
+      expect(faroFrames[0]?.filename).toBe('index.android.bundle');
+    });
   });
 
   describe('getStackFramesFromError', () => {
@@ -243,5 +299,14 @@ describe('Stack Trace Parser', () => {
       expect(result.context).toHaveProperty('customField', 'customValue');
       expect(result.context).toHaveProperty('platform');
     });
+
+    it('applies stack parse options for release frames', () => {
+      const error = new Error('Test');
+      error.stack = 'global@10:20';
+
+      const result = enhanceErrorWithContext(error, undefined, { releaseBundleFilename: 'main.jsbundle' });
+
+      expect(result.stackFrames[0]?.filename).toBe('main.jsbundle');
+    });
   });
 });

package/src/instrumentations/errors/stackTraceParser.ts

@@ -28,35 +28,85 @@ const REACT_NATIVE_RELEASE_REGEX = /^(.+?)@(\d+):(\d+)$/;
 const REACT_NATIVE_ANONYMOUS_REGEX = /^\s*at\s+anonymous\s+\((.+?):(\d+):(\d+)\)$/;
 const METRO_BUNDLER_REGEX = /^\s*at\s+(?:Object\.)?(.+?)\s+\((.+?):(\d+):(\d+)\)$/;
 
+/**
+ * Hermes (Android release) often reports the bundle segment as `address at index.android.bundle`
+ * inside parentheses. The collector hashes `frame.filename` for uploaded maps; it must match the
+ * source map `file` field (e.g. `index.android.bundle`), not the verbose Hermes label.
+ */
+export function normalizeHermesStackFilename(filename: string): string {
+  const trimmed = filename.trim();
+  const m = /^address\s+at\s+(.+)$/i.exec(trimmed);
+  return m?.[1]?.trim() ?? filename;
+}
+
+/**
+ * iOS Simulator (and Android) stacks often carry full filesystem paths such as
+ * `…/Foo.app/main.jsbundle` while uploaded maps are keyed by the bundle basename (`main.jsbundle`)
+ * that matches Metro’s source map `file` field — same as ingest’s bundle lookup hashes.
+ */
+function collapseBundledArtifactPath(filename: string, releaseBasename: string): string {
+  const key = releaseBasename.trim();
+  if (!key || filename === key) {
+    return filename;
+  }
+  const suffix = `/${key}`;
+  return filename.endsWith(suffix) ? key : filename;
+}
+
 export interface ParsedStackFrame {
   function?: string;
   filename?: string;
   lineno?: number;
   colno?: number;
   isNative?: boolean;
+  /** Set when the line matched Hermes/minified `func@line:col` (no path). */
+  releaseLine?: boolean;
+}
+
+/** Which parser branch handled a stack line (internal). */
+type ParsedStackLineKind =
+  | 'react_native_paren'
+  | 'metro_paren'
+  | 'anonymous_paren'
+  | 'native'
+  | 'release_func_at'
+  | 'unparsed';
+
+const UNKNOWN_RELEASE_FILENAME = '<unknown>';
+
+export interface StackFrameParseOptions {
+  /**
+   * Hermes / minified RN release lines use `func@line:col` with no file path. Those frames are tagged
+   * with `releaseLine` and use this as `filename` (default `bundle.js`). Match the Metro plugin’s
+   * source map `file` field (or `sourceMapFile` option there).
+   */
+  releaseBundleFilename?: string;
 }
 
 /**
- * Parse a single stack trace line into a structured frame
+ * Parse a single stack trace line into a structured frame and record how it was parsed.
  */
-export function parseStackTraceLine(line: string): ParsedStackFrame | null {
+function parseStackTraceLineDetailed(line: string): { frame: ParsedStackFrame | null; kind: ParsedStackLineKind } {
   if (!line || typeof line !== 'string') {
-    return null;
+    return { frame: null, kind: 'unparsed' };
   }
 
   const trimmedLine = line.trim();
   if (!trimmedLine) {
-    return null;
+    return { frame: null, kind: 'unparsed' };
   }
 
   // Try standard React Native format: at functionName (file.js:123:45)
   let match = trimmedLine.match(REACT_NATIVE_STACK_REGEX);
   if (match && match[2] && match[3] && match[4]) {
     return {
-      function: match[1] || '<anonymous>',
-      filename: match[2],
-      lineno: parseInt(match[3], 10),
-      colno: parseInt(match[4], 10),
+      kind: 'react_native_paren',
+      frame: {
+        function: match[1] || '<anonymous>',
+        filename: normalizeHermesStackFilename(match[2]),
+        lineno: parseInt(match[3], 10),
+        colno: parseInt(match[4], 10),
+      },
     };
   }
 
@@ -64,10 +114,13 @@ export function parseStackTraceLine(line: string): ParsedStackFrame | null {
   match = trimmedLine.match(METRO_BUNDLER_REGEX);
   if (match && match[2] && match[3] && match[4]) {
     return {
-      function: match[1] || '<anonymous>',
-      filename: match[2],
-      lineno: parseInt(match[3], 10),
-      colno: parseInt(match[4], 10),
+      kind: 'metro_paren',
+      frame: {
+        function: match[1] || '<anonymous>',
+        filename: normalizeHermesStackFilename(match[2]),
+        lineno: parseInt(match[3], 10),
+        colno: parseInt(match[4], 10),
+      },
     };
   }
 
@@ -75,10 +128,13 @@ export function parseStackTraceLine(line: string): ParsedStackFrame | null {
   match = trimmedLine.match(REACT_NATIVE_ANONYMOUS_REGEX);
   if (match && match[1] && match[2] && match[3]) {
     return {
-      function: '<anonymous>',
-      filename: match[1],
-      lineno: parseInt(match[2], 10),
-      colno: parseInt(match[3], 10),
+      kind: 'anonymous_paren',
+      frame: {
+        function: '<anonymous>',
+        filename: normalizeHermesStackFilename(match[1]),
+        lineno: parseInt(match[2], 10),
+        colno: parseInt(match[3], 10),
+      },
     };
   }
 
@@ -86,9 +142,12 @@ export function parseStackTraceLine(line: string): ParsedStackFrame | null {
   match = trimmedLine.match(REACT_NATIVE_NATIVE_REGEX);
   if (match) {
     return {
-      function: match[1] || '<native>',
-      filename: '<native>',
-      isNative: true,
+      kind: 'native',
+      frame: {
+        function: match[1] || '<native>',
+        filename: '<native>',
+        isNative: true,
+      },
     };
   }
 
@@ -96,15 +155,25 @@ export function parseStackTraceLine(line: string): ParsedStackFrame | null {
   match = trimmedLine.match(REACT_NATIVE_RELEASE_REGEX);
   if (match && match[2] && match[3]) {
     return {
-      function: match[1] || '<anonymous>',
-      filename: '<unknown>',
-      lineno: parseInt(match[2], 10),
-      colno: parseInt(match[3], 10),
+      kind: 'release_func_at',
+      frame: {
+        function: match[1] || '<anonymous>',
+        filename: UNKNOWN_RELEASE_FILENAME,
+        lineno: parseInt(match[2], 10),
+        colno: parseInt(match[3], 10),
+        releaseLine: true,
+      },
     };
   }
 
-  // Couldn't parse this line
-  return null;
+  return { frame: null, kind: 'unparsed' };
+}
+
+/**
+ * Parse a single stack trace line into a structured frame
+ */
+export function parseStackTraceLine(line: string): ParsedStackFrame | null {
+  return parseStackTraceLineDetailed(line).frame;
 }
 
 /**
@@ -119,7 +188,7 @@ export function parseStackTrace(stackTrace: string): ParsedStackFrame[] {
   const frames: ParsedStackFrame[] = [];
 
   for (const line of lines) {
-    const frame = parseStackTraceLine(line);
+    const { frame } = parseStackTraceLineDetailed(line);
     if (frame) {
       frames.push(frame);
     }
@@ -131,26 +200,40 @@ export function parseStackTrace(stackTrace: string): ParsedStackFrame[] {
 /**
  * Convert parsed stack frames to Faro's StackFrame format
  */
-export function toFaroStackFrames(parsedFrames: ParsedStackFrame[]): StackFrame[] {
-  return parsedFrames.map((frame, _index) => ({
-    filename: frame.filename || '<unknown>',
-    function: frame.function || '<anonymous>',
-    lineno: frame.lineno,
-    colno: frame.colno,
-  }));
+export function toFaroStackFrames(parsedFrames: ParsedStackFrame[], options?: StackFrameParseOptions): StackFrame[] {
+  const releaseName = options?.releaseBundleFilename ?? 'bundle.js';
+  const keyedBasename =
+    typeof options?.releaseBundleFilename === 'string' && options.releaseBundleFilename.trim() !== ''
+      ? options.releaseBundleFilename.trim()
+      : null;
+
+  return parsedFrames.map((frame, _index) => {
+    let filename = normalizeHermesStackFilename(frame.filename || '<unknown>');
+    if (frame.releaseLine) {
+      filename = releaseName;
+    } else if (keyedBasename) {
+      filename = collapseBundledArtifactPath(filename, keyedBasename);
+    }
+    return {
+      filename,
+      function: frame.function || '<anonymous>',
+      lineno: frame.lineno,
+      colno: frame.colno,
+    };
+  });
 }
 
 /**
  * Extract and parse stack frames from an Error object
  */
-export function getStackFramesFromError(error: Error): StackFrame[] {
+export function getStackFramesFromError(error: Error, options?: StackFrameParseOptions): StackFrame[] {
   if (!error || !error.stack) {
     return [];
   }
 
   try {
     const parsedFrames = parseStackTrace(error.stack);
-    return toFaroStackFrames(parsedFrames);
+    return toFaroStackFrames(parsedFrames, options);
   } catch (_e) {
     // If parsing fails, return empty array
     return [];
@@ -173,13 +256,14 @@ export function getPlatformErrorContext(): Record<string, string> {
  */
 export function enhanceErrorWithContext(
   error: Error,
-  additionalContext?: Record<string, string>
+  additionalContext?: Record<string, string>,
+  stackParseOptions?: StackFrameParseOptions
 ): {
   error: Error;
   stackFrames: StackFrame[];
   context: Record<string, string>;
 } {
-  const stackFrames = getStackFramesFromError(error);
+  const stackFrames = getStackFramesFromError(error, stackParseOptions);
   const platformContext = getPlatformErrorContext();
 
   return {