@grafana/faro-react-native 1.2.0 → 1.3.0

package/src/instrumentations/crashReporting/{instrumentation.ts → BaseCrashReportingInstrumentation.ts}

@@ -1,47 +1,28 @@
 import { NativeModules } from 'react-native';
 
-import { BaseInstrumentation, VERSION } from '@grafana/faro-core';
-
-import { ErrorMechanism } from '../errors/const';
+import { BaseInstrumentation } from '@grafana/faro-core';
 
+import { looksLikeNativeTombstoneTrace } from './android/nativeTombstoneTrace';
 import type { CrashReport, CrashReportingOptions } from './types';
 
 /**
- * Crash Reporting Instrumentation (Experimental).
- *
- * Retrieves crash reports from previous app sessions and sends them via Faro API.
- *
- * **Platform Support**:
- * - **Android**: Uses ApplicationExitInfo API (Android 11+ / API 30+)
- *   Captures: CRASH, CRASH_NATIVE, ANR, LOW_MEMORY, EXCESSIVE_RESOURCE_USAGE
- * - **iOS**: Uses PLCrashReporter (requires adding dependency to podspec)
- *   Captures: Signal crashes (SIGSEGV, SIGABRT, etc.) and Mach exceptions
+ * Abstract base class for platform-specific crash reporting implementations.
  *
- * **Note**: This instrumentation only retrieves crash data from previous sessions.
- * The crash itself terminates the app, so the report is sent on next app launch.
- *
- * @example
- * ```typescript
- * import { initializeFaro, CrashReportingInstrumentation } from '@grafana/faro-react-native';
- *
- * initializeFaro({
- *   url: 'https://collector.example.com',
- *   instrumentations: [
- *     new CrashReportingInstrumentation(),
- *   ],
- * });
- * ```
+ * Defines the common contract that both Android and iOS implementations must follow.
+ * Handles the shared logic for retrieving crash reports from native modules and
+ * processing them, while delegating platform-specific parsing and validation to subclasses.
  */
-export class CrashReportingInstrumentation extends BaseInstrumentation {
-  readonly name = '@grafana/faro-react-native:instrumentation-crash';
-  readonly version = VERSION;
+export abstract class BaseCrashReportingInstrumentation extends BaseInstrumentation {
+  abstract override readonly name: string;
+  abstract override readonly version: string;
 
-  private readonly options: Required<CrashReportingOptions>;
+  protected readonly options: { enabled: boolean; releaseBundleFilename?: string };
 
   constructor(options: CrashReportingOptions = {}) {
     super();
     this.options = {
       enabled: options.enabled ?? true,
+      releaseBundleFilename: options.releaseBundleFilename,
     };
   }
 
@@ -59,37 +40,56 @@ export class CrashReportingInstrumentation extends BaseInstrumentation {
 
     this.logDebug('Initializing crash reporting instrumentation');
 
-    // Wait for session attributes to be populated before sending crash reports
-    // This ensures crash reports include full session metadata
+    // Wait for session attributes before sending crash reports
     await this.waitForSessionAttributes();
 
-    // Get crash reports from previous session
+    // Get and process crash reports from previous session
     await this.processCrashReports(nativeModule);
   }
 
   /**
-   * Wait for session attributes to be populated.
-   *
-   * Crash reports are sent in a new session, so we need to wait for
-   * SessionInstrumentation to finish collecting device info, OS version, etc.
-   * before sending the crash report. Otherwise, the crash report will be missing
-   * session metadata.
-   *
-   * This checks for multiple device-specific attributes that are collected
-   * asynchronously (device_id, device_os_detail, device_model_name) to ensure
-   * the async getSessionAttributes() call has completed.
-   *
-   * @param maxWaitMs Maximum time to wait in milliseconds (default 10000ms)
+   * Platform-specific: Parse a crash trace string into structured stack frames.
+   */
+  protected abstract parseCrashTrace(trace: string): any | null;
+
+  /**
+   * Platform-specific: Resolve human-readable error message from crash data.
+   */
+  protected abstract resolveCrashErrorMessage(crash: CrashReport, parsedTrace: any | null): string;
+
+  /**
+   * Platform-specific: Determine if a crash report should be skipped.
+   */
+  protected abstract shouldSkipCrashReport(crash: CrashReport): boolean;
+
+  /**
+   * Platform-specific: Extract stack frames from parsed trace.
+   */
+  protected abstract getStackFrames(parsedTrace: any | null): any[];
+
+  /**
+   * Platform-specific: Build platform-specific context from parsed trace.
+   */
+  protected abstract buildPlatformContext(parsedTrace: any | null, context: Record<string, string>): void;
+
+  /**
+   * Platform-specific: Get warning message when trace parsing fails.
+   */
+  protected abstract getParseFailureWarning(): string;
+
+  /**
+   * Platform-specific: Get warning message when trace is unavailable.
    */
+  protected abstract getTraceUnavailableWarning(): string;
+
   private async waitForSessionAttributes(maxWaitMs = 10000): Promise<void> {
     const startTime = Date.now();
-    const pollInterval = 200; // Check every 200ms
+    const pollInterval = 200;
     let checkCount = 0;
 
     while (Date.now() - startTime < maxWaitMs) {
       checkCount++;
       try {
-        // Check if session attributes are populated
         const sessionAttrs = this.metas?.value?.session?.attributes;
 
         if (sessionAttrs) {
@@ -98,7 +98,7 @@ export class CrashReportingInstrumentation extends BaseInstrumentation {
 
           // Look for multiple device-specific attributes that indicate full async collection is done.
           // getSessionAttributes() collects these asynchronously:
-          // - device_id (async getDeviceId)
+          // - device_id (SDK installation id, kept as a flat attr during migration)
           // - device_os_detail (async getDeviceOsDetail)
           // - device_model_name (DeviceInfo.getDeviceNameSync)
           // All three should be present when collection is complete.
@@ -120,15 +120,12 @@ export class CrashReportingInstrumentation extends BaseInstrumentation {
           this.logDebug(`Check #${checkCount}: No session attributes available yet`);
         }
       } catch (error) {
-        // Continue waiting if we can't access metas yet
         this.logDebug(`Check #${checkCount}: Error accessing metas: ${error}`);
       }
 
-      // Wait before next check
       await new Promise((resolve) => setTimeout(resolve, pollInterval));
     }
 
-    // Timeout reached - log warning but continue
     const finalAttrs = this.metas?.value?.session?.attributes;
     const finalAttrCount = finalAttrs ? Object.keys(finalAttrs).length : 0;
     const finalAttrKeys = finalAttrs ? JSON.stringify(Object.keys(finalAttrs)) : 'none';
@@ -164,20 +161,37 @@ export class CrashReportingInstrumentation extends BaseInstrumentation {
 
       this.logDebug(`Processing ${crashReports.length} crash report(s) from previous session`);
 
+      const reportedTimestamps = new Set<number>();
+
       for (const crashJson of crashReports) {
         try {
           this.logDebug(`Parsing crash report JSON: ${crashJson.substring(0, 200)}...`);
           const crash = JSON.parse(crashJson) as CrashReport;
+
+          if (crash.timestamp && reportedTimestamps.has(crash.timestamp)) {
+            this.logDebug(`Skipping duplicate crash report at ${crash.timestamp}`);
+            continue;
+          }
+
+          if (this.shouldSkipCrashReport(crash)) {
+            this.logDebug(`Skipping crash report at ${crash.timestamp} (platform-specific skip logic)`);
+            continue;
+          }
+
+          if (crash.timestamp) {
+            reportedTimestamps.add(crash.timestamp);
+          }
+
           this.sendCrashReport(crash);
         } catch (parseError) {
-          // If parsing fails, still try to report something
           this.logError('Failed to parse crash report JSON', parseError);
           this.api.pushError(new Error('Application crash (parse error)'), {
             context: {
-              mechanism: ErrorMechanism.CRASH,
+              mechanism: 'crash',
               parseError: String(parseError),
-              raw: crashJson.substring(0, 500), // Limit size
+              raw: crashJson.substring(0, 500),
             },
+            fatal: true,
             type: 'crash',
           });
         }
@@ -188,12 +202,17 @@ export class CrashReportingInstrumentation extends BaseInstrumentation {
   }
 
   private sendCrashReport(crash: CrashReport): void {
-    const errorMessage = this.getErrorMessage(crash);
+    // Platform-specific parsing
+    const parsedTrace = crash.trace ? this.parseCrashTrace(crash.trace) : null;
+    const errorMessage = this.resolveCrashErrorMessage(crash, parsedTrace).trim() || 'Application crash';
+
+    // Use a message-only Error so pushError does not capture the JS reporter stack
     const error = new Error(errorMessage);
+    error.stack = undefined;
 
-    // Build context from crash data (matching Flutter pattern)
+    // Build context from crash data
     const context: Record<string, string> = {
-      mechanism: ErrorMechanism.CRASH,
+      mechanism: 'crash',
     };
 
     if (crash.trace) {
@@ -218,48 +237,55 @@ export class CrashReportingInstrumentation extends BaseInstrumentation {
       context['importance'] = String(crash.importance);
     }
 
-    // Push as error via Faro API (matching Flutter pattern)
+    // Platform-specific context
+    this.buildPlatformContext(parsedTrace, context);
+
+    // Platform-specific stack frames
+    const stackFrames = this.getStackFrames(parsedTrace);
+
+    // Warnings for missing/unparseable traces
+    if (!stackFrames.length && crash.trace) {
+      this.logWarn(this.getParseFailureWarning());
+    } else if (!crash.trace) {
+      this.logWarn(this.getTraceUnavailableWarning());
+    } else if (looksLikeNativeTombstoneTrace(crash.trace)) {
+      const framePreview = crash.trace
+        .split('\n')
+        .map((line) => line.trim())
+        .find((line) => /#\d+\s+pc\s+/i.test(line));
+      this.logInfo(
+        `[Faro crash native] Sending tombstone trace (${crash.trace.split('\n').length} lines) preview=${framePreview ?? 'n/a'}`
+      );
+    }
+
     this.api.pushError(error, {
-      type: 'crash',
+      stackFrames,
       context,
+      type: 'crash',
+      fatal: true,
     });
 
-    this.logDebug(`Reported crash: ${crash.reason} at ${crash.timestamp}`);
+    this.logDebug(`Sent crash report: ${errorMessage}`);
   }
 
-  /**
-   * Build error message matching Flutter SDK format:
-   * "{reason}: {description}, status: {status}"
-   */
-  private getErrorMessage(crash: CrashReport): string {
-    const reason = crash.reason || 'UNKNOWN';
-    const status = crash.status ?? 0;
-
-    let description: string;
-    switch (crash.reason) {
-      case 'ANR':
-        description = 'Application Not Responding';
-        break;
-      case 'CRASH':
-        description = 'Application crash (Java/Kotlin)';
-        break;
-      case 'CRASH_NATIVE':
-        description = 'Application crash (Native)';
-        break;
-      case 'LOW_MEMORY':
-        description = 'Application terminated due to low memory';
-        break;
-      case 'EXCESSIVE_RESOURCE_USAGE':
-        description = 'Application terminated due to excessive resource usage';
-        break;
-      case 'INITIALIZATION_FAILURE':
-        description = 'Application failed to initialize';
-        break;
-      default:
-        description = crash.description || 'Application crash';
-        break;
-    }
+  // Logging helpers
+  override logDebug(message: string, ...args: any[]): void {
+    this.internalLogger?.debug?.(message, ...args);
+  }
+
+  override logInfo(message: string, ...args: any[]): void {
+    this.internalLogger?.info?.(message, ...args);
+  }
+
+  override logWarn(message: string, ...args: any[]): void {
+    this.internalLogger?.warn?.(message, ...args);
+  }
+
+  override logError(message: string, ...args: any[]): void {
+    this.internalLogger?.error?.(message, ...args);
+  }
 
-    return `${reason}: ${description}, status: ${status}`;
+  unpatch(): void {
+    // No patching to undo
   }
 }

package/src/instrumentations/crashReporting/NoOpCrashReportingInstrumentation.ts

@@ -0,0 +1,23 @@
+import { BaseInstrumentation, VERSION } from '@grafana/faro-core';
+
+import type { CrashReportingOptions } from './types';
+
+/**
+ * Crash reporting stub for platforms other than Android and iOS (e.g. web, macOS, Windows).
+ */
+export class NoOpCrashReportingInstrumentation extends BaseInstrumentation {
+  readonly name = '@grafana/faro-react-native:instrumentation-crash-noop';
+  readonly version = VERSION;
+
+  constructor(_options: CrashReportingOptions = {}) {
+    super();
+  }
+
+  initialize(): void {
+    this.logDebug('Crash reporting is not supported on this platform');
+  }
+
+  unpatch(): void {
+    // No patching to undo
+  }
+}

package/src/instrumentations/crashReporting/android/AndroidCrashReportingInstrumentation.ts

@@ -0,0 +1,62 @@
+import { VERSION } from '@grafana/faro-core';
+
+import { BaseCrashReportingInstrumentation } from '../BaseCrashReportingInstrumentation';
+import type { CrashReport } from '../types';
+
+import { resolveCrashErrorMessage, shouldSkipCrashReport } from './crashErrorMessage';
+import { parseAndroidCrashTrace, type ParsedAndroidCrashTrace } from './parseAndroidCrashTrace';
+
+/**
+ * Android Crash Reporting Instrumentation.
+ *
+ * Uses ApplicationExitInfo API (Android 11+ / API 30+) to retrieve crash reports
+ * from previous sessions. Captures:
+ * - CRASH: Java/Kotlin exception crashes
+ * - CRASH_NATIVE: Native (NDK) crashes
+ * - LOW_MEMORY: App killed due to low memory
+ * - EXCESSIVE_RESOURCE_USAGE: App killed due to excessive resource usage
+ *
+ * ANRs are reported separately by ANRInstrumentation, not via ApplicationExitInfo replay.
+ */
+export class AndroidCrashReportingInstrumentation extends BaseCrashReportingInstrumentation {
+  readonly name = '@grafana/faro-react-native:instrumentation-crash-android';
+  readonly version = VERSION;
+
+  protected parseCrashTrace(trace: string): ParsedAndroidCrashTrace | null {
+    return parseAndroidCrashTrace(trace, {
+      releaseBundleFilename: this.options.releaseBundleFilename,
+    });
+  }
+
+  protected resolveCrashErrorMessage(crash: CrashReport, parsedTrace: ParsedAndroidCrashTrace | null): string {
+    return resolveCrashErrorMessage(crash, parsedTrace);
+  }
+
+  protected shouldSkipCrashReport(crash: CrashReport): boolean {
+    return shouldSkipCrashReport(crash);
+  }
+
+  protected getStackFrames(parsedTrace: ParsedAndroidCrashTrace | null): any[] {
+    if (!parsedTrace) {
+      return [];
+    }
+    // Android has JS frames, Java/Kotlin frames (R8 retrace), and NDK tombstone rows (.so retrace).
+    return [...(parsedTrace.jsFrames ?? []), ...(parsedTrace.frames ?? []), ...(parsedTrace.nativeFrames ?? [])];
+  }
+
+  protected buildPlatformContext(parsedTrace: ParsedAndroidCrashTrace | null, context: Record<string, string>): void {
+    // Store the native Java/Kotlin exception class separately for drill-down
+    // Plugin overview metrics key off exception_type = 'crash', so keep that stable
+    if (parsedTrace?.exceptionType) {
+      context['nativeExceptionType'] = parsedTrace.exceptionType;
+    }
+  }
+
+  protected getParseFailureWarning(): string {
+    return 'Native crash trace present but no frames parsed; check Android trace format or UncaughtExceptionHandler cache';
+  }
+
+  protected getTraceUnavailableWarning(): string {
+    return 'Native crash trace unavailable (ApplicationExitInfo traceInputStream was null at crash time)';
+  }
+}

package/src/instrumentations/crashReporting/android/crashErrorMessage.test.ts

@@ -0,0 +1,182 @@
+import type { CrashReport } from '../types';
+
+import {
+  buildFallbackCrashMessage,
+  isAnrTimeoutDescription,
+  resolveCrashErrorMessage,
+  shouldSkipCrashReport,
+  shouldSkipLowSignalCrashReport,
+} from './crashErrorMessage';
+import type { ParsedAndroidCrashTrace } from './parseAndroidCrashTrace';
+
+const baseCrash: CrashReport = {
+  reason: 'CRASH',
+  timestamp: 1_700_000_000_000,
+  status: 0,
+};
+
+describe('resolveCrashErrorMessage', () => {
+  it('prefers the parsed trace message', () => {
+    const parsed: ParsedAndroidCrashTrace = {
+      exceptionMessage: 'Intentional native crash from demo module',
+      exceptionType: 'java.lang.RuntimeException',
+      jsFrames: [],
+      frames: [],
+    };
+
+    expect(resolveCrashErrorMessage(baseCrash, parsed)).toBe('Intentional native crash from demo module');
+  });
+
+  it('uses ApplicationExitInfo description when the trace has no message', () => {
+    const crash: CrashReport = {
+      ...baseCrash,
+      description:
+        'Input dispatching timed out (com.example.app/.MainActivity is not responding. Waited 5002ms for FocusEvent)',
+    };
+
+    expect(resolveCrashErrorMessage(crash, null)).toBe(
+      'Input dispatching timed out (com.example.app/.MainActivity is not responding. Waited 5002ms for FocusEvent)'
+    );
+  });
+
+  it('extracts java exception types from non-generic ApplicationExitInfo descriptions', () => {
+    const crash: CrashReport = {
+      ...baseCrash,
+      description: 'java.lang.NullPointerException: null reference',
+    };
+
+    expect(resolveCrashErrorMessage(crash, null)).toBe('java.lang.NullPointerException');
+  });
+
+  it('prefers parsed exception type over generic ApplicationExitInfo descriptions such as "crash"', () => {
+    const parsed: ParsedAndroidCrashTrace = {
+      exceptionType: 'java.lang.NullPointerException',
+      jsFrames: [],
+      frames: [],
+    };
+    const crash: CrashReport = {
+      ...baseCrash,
+      description: 'crash',
+    };
+
+    expect(resolveCrashErrorMessage(crash, parsed)).toBe('java.lang.NullPointerException');
+  });
+
+  it('falls back to exception type for message-less traces such as NullPointerException', () => {
+    const parsed: ParsedAndroidCrashTrace = {
+      exceptionType: 'java.lang.NullPointerException',
+      jsFrames: [],
+      frames: [],
+    };
+
+    expect(resolveCrashErrorMessage(baseCrash, parsed)).toBe('java.lang.NullPointerException');
+  });
+
+  it('uses generic fallback when nothing else is available', () => {
+    expect(resolveCrashErrorMessage(baseCrash, null)).toBe('CRASH: Application crash (Java/Kotlin), status: 0');
+  });
+
+  it('does not treat version-like tokens as exception types', () => {
+    const parsed: ParsedAndroidCrashTrace = {
+      exceptionType: '18.2213',
+      jsFrames: [],
+      frames: [
+        {
+          module: 'com.example.CrashModule',
+          function: 'blockMainThread',
+          filename: 'CrashModule.kt',
+          lineno: 56,
+        },
+      ],
+    };
+
+    expect(resolveCrashErrorMessage(baseCrash, parsed)).toBe('CRASH: Application crash (Java/Kotlin), status: 0');
+  });
+
+  it('falls back when the trace has frames but no parseable message or exception type', () => {
+    const parsed: ParsedAndroidCrashTrace = {
+      jsFrames: [],
+      frames: [
+        {
+          module: 'com.example.CrashModule',
+          function: 'triggerNativeCrash',
+          filename: 'CrashModule.kt',
+          lineno: 60,
+        },
+      ],
+    };
+
+    expect(resolveCrashErrorMessage(baseCrash, parsed)).toBe('CRASH: Application crash (Java/Kotlin), status: 0');
+  });
+});
+
+describe('isAnrTimeoutDescription', () => {
+  it('detects Android ANR watchdog descriptions', () => {
+    expect(
+      isAnrTimeoutDescription(
+        'Input dispatching timed out (com.example.app/com.example.app.MainActivity is not responding. Waited 5002ms for FocusEvent)'
+      )
+    ).toBe(true);
+    expect(isAnrTimeoutDescription('Application Not Responding')).toBe(true);
+    expect(isAnrTimeoutDescription('java.lang.RuntimeException: something broke')).toBe(false);
+  });
+});
+
+describe('shouldSkipCrashReport', () => {
+  it('skips ApplicationExitInfo rows with ANR timeout descriptions', () => {
+    expect(
+      shouldSkipCrashReport({
+        ...baseCrash,
+        description:
+          'Input dispatching timed out (com.example.app/com.example.app.MainActivity is not responding. Waited 5002ms for FocusEvent)',
+      })
+    ).toBe(true);
+  });
+
+  it('does not skip real crashes with Java exception descriptions', () => {
+    expect(
+      shouldSkipCrashReport({
+        ...baseCrash,
+        description: 'java.lang.RuntimeException: Network failure',
+        trace: 'java.lang.RuntimeException: Network failure\n    at com.example.Foo.bar(Foo.kt:1)',
+      })
+    ).toBe(false);
+  });
+});
+
+describe('shouldSkipLowSignalCrashReport', () => {
+  it('skips trace-less rows with only generic descriptions', () => {
+    expect(
+      shouldSkipLowSignalCrashReport({
+        ...baseCrash,
+        description: 'Application crash (Java/Kotlin)',
+      })
+    ).toBe(true);
+  });
+
+  it('keeps rows that carry a native trace', () => {
+    expect(
+      shouldSkipLowSignalCrashReport({
+        ...baseCrash,
+        trace: 'java.lang.NullPointerException\n    at com.example.Foo.bar(Foo.kt:1)',
+      })
+    ).toBe(false);
+  });
+
+  it('keeps rows with a specific ApplicationExitInfo description', () => {
+    expect(
+      shouldSkipLowSignalCrashReport({
+        ...baseCrash,
+        description: 'java.lang.RuntimeException: intentional native crash',
+      })
+    ).toBe(false);
+  });
+});
+
+describe('buildFallbackCrashMessage', () => {
+  it('formats native crash reasons', () => {
+    expect(buildFallbackCrashMessage({ ...baseCrash, reason: 'CRASH_NATIVE' })).toBe(
+      'CRASH_NATIVE: Application crash (Native), status: 0'
+    );
+  });
+});