@grafana/faro-react-native 1.2.1 → 1.3.1

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

@@ -0,0 +1,135 @@
+import type { CrashReport } from '../types';
+
+import { isPlausibleJavaExceptionIdentifier } from './parseAndroidCrashTrace';
+import type { ParsedAndroidCrashTrace } from './parseAndroidCrashTrace';
+
+/**
+ * Human-readable exception value for ApplicationExitInfo crash reports.
+ * Priority: parsed trace message → exception class → description → generic fallback.
+ */
+export function resolveCrashErrorMessage(crash: CrashReport, parsedTrace: ParsedAndroidCrashTrace | null): string {
+  const fromTrace = parsedTrace?.exceptionMessage?.trim();
+  if (fromTrace) {
+    return fromTrace;
+  }
+
+  const fromType = parsedTrace?.exceptionType?.trim();
+  if (fromType && isPlausibleJavaExceptionIdentifier(fromType)) {
+    return fromType;
+  }
+
+  const fromDescriptionType = exceptionTypeFromDescription(crash.description);
+  if (fromDescriptionType) {
+    return fromDescriptionType;
+  }
+
+  const fromDescription = crash.description?.trim();
+  if (fromDescription && !isGenericCrashDescription(fromDescription)) {
+    return fromDescription;
+  }
+
+  const fallback = buildFallbackCrashMessage(crash);
+  return fallback.trim() || crash.reason || 'Application crash';
+}
+
+const ANR_TIMEOUT_DESCRIPTION_PATTERN = /input dispatching timed out|not responding|application not responding/i;
+
+/**
+ * Android ANR watchdog descriptions from ApplicationExitInfo (any app).
+ */
+export function isAnrTimeoutDescription(description: string | undefined): boolean {
+  const trimmed = description?.trim();
+  if (!trimmed) {
+    return false;
+  }
+  return ANR_TIMEOUT_DESCRIPTION_PATTERN.test(trimmed);
+}
+
+/**
+ * Skip duplicate ApplicationExitInfo rows that have no stack and no useful title,
+ * and ANR incidents mis-tagged as previous-session crashes.
+ */
+export function shouldSkipCrashReport(crash: CrashReport): boolean {
+  if (isAnrTimeoutDescription(crash.description)) {
+    return true;
+  }
+
+  return shouldSkipLowSignalCrashReport(crash);
+}
+
+/**
+ * Skip duplicate ApplicationExitInfo rows that have no stack and no useful title.
+ * These surface in the plugin as a second generic `crash` row for a single button press.
+ */
+export function shouldSkipLowSignalCrashReport(crash: CrashReport): boolean {
+  if (crash.trace?.trim()) {
+    return false;
+  }
+
+  const description = crash.description?.trim();
+  if (description && !isGenericCrashDescription(description)) {
+    return false;
+  }
+
+  return true;
+}
+
+/** Extract `java.lang.NullPointerException` from ApplicationExitInfo description text. */
+function exceptionTypeFromDescription(description: string | undefined): string | undefined {
+  const trimmed = description?.trim();
+  if (!trimmed || isGenericCrashDescription(trimmed)) {
+    return undefined;
+  }
+
+  const match = trimmed.match(/^([\w.$]+)(?::(.*))?$/);
+  const candidate = match?.[1]?.trim();
+  if (!candidate || !isPlausibleJavaExceptionIdentifier(candidate)) {
+    return undefined;
+  }
+
+  return candidate;
+}
+
+function isGenericCrashDescription(description: string): boolean {
+  const normalized = description.trim().toLowerCase();
+  return (
+    normalized === 'crash' ||
+    normalized === 'native crash' ||
+    normalized === 'application crash' ||
+    normalized === 'application crash (java/kotlin)' ||
+    normalized === 'application crash (native)'
+  );
+}
+
+/** Generic fallback when the trace carries no parseable message or type. */
+export function buildFallbackCrashMessage(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;
+  }
+
+  return `${reason}: ${description}, status: ${status}`;
+}

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

@@ -0,0 +1,4 @@
+export { AndroidCrashReportingInstrumentation } from './AndroidCrashReportingInstrumentation';
+export { parseAndroidCrashTrace, normalizeJavaStackTraceForRetrace } from './parseAndroidCrashTrace';
+export type { ParsedAndroidCrashTrace, AndroidCrashStackFrame } from './parseAndroidCrashTrace';
+export { resolveCrashErrorMessage, shouldSkipCrashReport } from './crashErrorMessage';

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

@@ -0,0 +1,19 @@
+import { looksLikeNativeTombstoneTrace } from './nativeTombstoneTrace';
+
+describe('looksLikeNativeTombstoneTrace', () => {
+  it('detects Android tombstone backtrace lines', () => {
+    const trace = [
+      '*** *** *** *** *** *** ***',
+      "ABI: 'arm64'",
+      'backtrace:',
+      '      #00 pc 0000000000001234  /data/app/lib/arm64-v8a/libappmodules.so (nativeCrash+8)',
+    ].join('\n');
+
+    expect(looksLikeNativeTombstoneTrace(trace)).toBe(true);
+  });
+
+  it('returns false for Java stack traces', () => {
+    const trace = ['java.lang.RuntimeException: boom', '  at com.example.Foo.bar(Foo.kt:12)'].join('\n');
+    expect(looksLikeNativeTombstoneTrace(trace)).toBe(false);
+  });
+});

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

@@ -0,0 +1,8 @@
+/** Detect Android tombstone backtrace lines used for NDK native retrace. */
+export function looksLikeNativeTombstoneTrace(trace: string | undefined): boolean {
+  if (!trace?.trim()) {
+    return false;
+  }
+
+  return trace.split('\n').some((line) => /^\s*#\d+\s+pc\s+(?:0x)?[0-9a-fA-F]+\s+\S+/i.test(line));
+}

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

@@ -0,0 +1,232 @@
+import {
+  normalizeCrashTraceExceptionMessage,
+  normalizeJavaStackTraceForRetrace,
+  parseAndroidCrashTrace,
+} from './parseAndroidCrashTrace';
+
+describe('parseAndroidCrashTrace', () => {
+  it('parses obfuscated ApplicationExitInfo traces', () => {
+    const trace = [
+      'com.example.c: Intentional native crash',
+      '\tat com.example.c.a(SourceFile:33)',
+      '\tat com.example.c.b(SourceFile:45)',
+      '\tat com.example.c.d(SourceFile)',
+      '\tat com.unknown.x.y(SourceFile:7)',
+    ].join('\n');
+
+    const parsed = parseAndroidCrashTrace(trace);
+
+    expect(parsed).toEqual({
+      exceptionType: 'com.example.c',
+      exceptionMessage: 'Intentional native crash',
+      jsFrames: [],
+      nativeFrames: [],
+      frames: [
+        {
+          module: 'com.example.c',
+          function: 'a',
+          filename: 'SourceFile',
+          lineno: 33,
+        },
+        {
+          module: 'com.example.c',
+          function: 'b',
+          filename: 'SourceFile',
+          lineno: 45,
+        },
+        {
+          module: 'com.example.c',
+          function: 'd',
+          filename: 'SourceFile',
+          lineno: undefined,
+        },
+        {
+          module: 'com.unknown.x',
+          function: 'y',
+          filename: 'SourceFile',
+          lineno: 7,
+        },
+      ],
+    });
+  });
+
+  it('parses Android Log.getStackTraceString format', () => {
+    const trace = [
+      'java.lang.RuntimeException: Intentional native crash',
+      '    at com.example.CrashModule.raiseFailure(CrashModule.kt:60)',
+      '    at com.example.CrashModule.triggerRuntimeException(CrashModule.kt:33)',
+    ].join('\n');
+
+    const parsed = parseAndroidCrashTrace(trace);
+
+    expect(parsed?.exceptionType).toBe('java.lang.RuntimeException');
+    expect(parsed?.frames).toEqual([
+      {
+        module: 'com.example.CrashModule',
+        function: 'raiseFailure',
+        filename: 'CrashModule.kt',
+        lineno: 60,
+      },
+      {
+        module: 'com.example.CrashModule',
+        function: 'triggerRuntimeException',
+        filename: 'CrashModule.kt',
+        lineno: 33,
+      },
+    ]);
+  });
+
+  it('parses java.lang.RuntimeException headers', () => {
+    const trace = ['java.lang.RuntimeException: Intentional native crash', '\tat com.example.c.a(SourceFile:33)'].join(
+      '\n'
+    );
+
+    const parsed = parseAndroidCrashTrace(trace);
+
+    expect(parsed?.exceptionType).toBe('java.lang.RuntimeException');
+    expect(parsed?.frames).toHaveLength(1);
+  });
+
+  it('returns null for empty input', () => {
+    expect(parseAndroidCrashTrace('')).toBeNull();
+    expect(parseAndroidCrashTrace('   ')).toBeNull();
+  });
+
+  it('parses RN fatal JavascriptException ApplicationExitInfo traces', () => {
+    const trace = [
+      'com.facebook.react.common.JavascriptException: Error: Unhandled debug exception, stack:',
+      'anonymous@1:1390953',
+      '',
+      '\tat com.facebook.react.modules.core.ExceptionsManagerModule.reportException(ExceptionsManagerModule.kt:52)',
+      '\tat android.os.Handler.handleCallback(Handler.java:1070)',
+    ].join('\n');
+
+    const parsed = parseAndroidCrashTrace(trace, { releaseBundleFilename: 'index.android.bundle' });
+
+    expect(parsed?.exceptionType).toBe('com.facebook.react.common.JavascriptException');
+    expect(parsed?.exceptionMessage).toBe('Unhandled debug exception');
+    expect(parsed?.jsFrames).toEqual([
+      {
+        function: 'anonymous',
+        filename: 'index.android.bundle',
+        lineno: 1,
+        colno: 1390953,
+      },
+    ]);
+    expect(parsed?.frames[0]).toMatchObject({
+      module: 'com.facebook.react.modules.core.ExceptionsManagerModule',
+      function: 'reportException',
+      filename: 'ExceptionsManagerModule.kt',
+      lineno: 52,
+    });
+  });
+
+  it('parses dev-style JS frames embedded in Android crash traces', () => {
+    const trace = [
+      'com.facebook.react.common.JavascriptException: Error: Unhandled debug exception, stack:',
+      'at triggerUnhandledException (/Users/me/DebugScreen.tsx:133:7)',
+      'at com.facebook.react.modules.core.ExceptionsManagerModule.reportException(ExceptionsManagerModule.kt:52)',
+    ].join('\n');
+
+    const parsed = parseAndroidCrashTrace(trace);
+
+    expect(parsed?.jsFrames[0]).toMatchObject({
+      function: 'triggerUnhandledException',
+      filename: '/Users/me/DebugScreen.tsx',
+      lineno: 133,
+      colno: 7,
+    });
+  });
+
+  it('normalizes RN fatal JS error header shape without relying on exception type', () => {
+    expect(normalizeCrashTraceExceptionMessage('Error: Unhandled debug exception, stack:')).toBe(
+      'Unhandled debug exception'
+    );
+  });
+
+  it('leaves native exception messages unchanged', () => {
+    expect(normalizeCrashTraceExceptionMessage('Intentional native crash')).toBe('Intentional native crash');
+  });
+
+  it('parses ANRTracker Thread.getStackTrace lines without an "at " prefix', () => {
+    const trace = [
+      'com.example.CrashModule.blockMainThread(CrashModule.kt:42)',
+      'com.example.CrashModule.crash(CrashModule.kt:22)',
+    ].join('\n');
+
+    const parsed = parseAndroidCrashTrace(trace);
+
+    expect(parsed?.frames).toEqual([
+      {
+        module: 'com.example.CrashModule',
+        function: 'blockMainThread',
+        filename: 'CrashModule.kt',
+        lineno: 42,
+      },
+      {
+        module: 'com.example.CrashModule',
+        function: 'crash',
+        filename: 'CrashModule.kt',
+        lineno: 22,
+      },
+    ]);
+  });
+
+  it('normalizes thread stacks for ingest R8 retrace', () => {
+    const raw = 'com.example.c.a(SourceFile:33)';
+    expect(normalizeJavaStackTraceForRetrace(raw)).toBe('    at com.example.c.a(SourceFile:33)');
+  });
+
+  it('ignores version-like header lines such as 18.2213', () => {
+    const trace = ['18.2213', '    at com.example.CrashModule.blockMainThread(CrashModule.kt:56)'].join('\n');
+
+    const parsed = parseAndroidCrashTrace(trace);
+
+    expect(parsed?.exceptionType).toBeUndefined();
+    expect(parsed?.frames).toHaveLength(1);
+  });
+
+  it('parses NDK tombstone backtrace lines and ignores the backtrace: section label', () => {
+    const trace = [
+      "ABI: 'arm64'",
+      'signal SIGSEGV (11)',
+      'backtrace:',
+      '      #00 pc 000000782a48ce5c  /data/app/base.apk!libappmodules.so (Java_com_quickpizza_QuickPizzaNdkCrashModule_nativeCrash+8)',
+      '      #01 pc 0000000070ae9890  /system/framework/arm64/boot.oat (art_jni_trampoline+112)',
+    ].join('\n');
+
+    const parsed = parseAndroidCrashTrace(trace);
+
+    expect(parsed?.exceptionType).toBeUndefined();
+    expect(parsed?.nativeFrames).toEqual([
+      {
+        module: 'libappmodules.so',
+        function: 'Java_com_quickpizza_QuickPizzaNdkCrashModule_nativeCrash',
+        filename: 'libappmodules.so',
+      },
+      {
+        module: 'boot.oat',
+        function: 'art_jni_trampoline',
+        filename: 'boot.oat',
+      },
+    ]);
+  });
+
+  it('captures root cause from wrapped exceptions with "Caused by:" chain', () => {
+    const trace = [
+      'java.lang.RuntimeException: Wrapper exception',
+      '    at com.example.OuterClass.method(OuterClass.kt:10)',
+      'Caused by: java.lang.IllegalStateException: Middle exception',
+      '    at com.example.MiddleClass.method(MiddleClass.kt:20)',
+      'Caused by: java.lang.NullPointerException: Root cause',
+      '    at com.example.InnerClass.method(InnerClass.kt:30)',
+    ].join('\n');
+
+    const parsed = parseAndroidCrashTrace(trace);
+
+    // Should capture the root cause (last "Caused by:")
+    expect(parsed?.exceptionType).toBe('java.lang.NullPointerException');
+    expect(parsed?.exceptionMessage).toBe('Root cause');
+    expect(parsed?.frames).toHaveLength(3);
+  });
+});

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

@@ -0,0 +1,235 @@
+import type { ExceptionStackFrame } from '@grafana/faro-core';
+
+import { parseStackTraceLine, toFaroStackFrames } from '../../errors/stackTraceParser';
+
+/**
+ * Android ApplicationExitInfo traces use Java/Kotlin stack-trace formatting.
+ * Faro ingest expects structured frames with `module` (obfuscated class) so the
+ * collector can R8-retrace them — not the JS call stack from sendCrashReport().
+ *
+ * Fatal RN JS errors also embed a short Hermes/Metro stack before native frames
+ * (e.g. `anonymous@1:1390953`). Those lines are parsed as JS frames (no `module`)
+ * so the collector can source-map them to files like DebugScreen.tsx.
+ */
+export interface AndroidCrashStackFrame extends ExceptionStackFrame {
+  module: string;
+}
+
+export interface ParseAndroidCrashTraceOptions {
+  releaseBundleFilename?: string;
+}
+
+export interface NativeTombstoneStackFrame extends ExceptionStackFrame {
+  /** Unstripped .so basename (e.g. libappmodules.so) for NDK retrace on the collector. */
+  module: string;
+}
+
+export interface ParsedAndroidCrashTrace {
+  exceptionType?: string;
+  /** Human-readable message from the trace header (e.g. the JS error text). */
+  exceptionMessage?: string;
+  /** JS/Hermes frames from the embedded RN stack (source-map targets). */
+  jsFrames: ExceptionStackFrame[];
+  /** Native Java/Kotlin frames (Android R8 retrace targets). */
+  frames: AndroidCrashStackFrame[];
+  /** NDK tombstone #NN pc lines (server-side .so retrace targets). */
+  nativeFrames: NativeTombstoneStackFrame[];
+}
+
+// Mirrors pkg/exporter/androidretrace/mapping.go frameLine / exceptionHeader.
+const FRAME_LINE = /^\s*at\s+([\w$.]+)\.([\w$<>]+)\(([^):]*)(?::(\d+))?\)\s*$/;
+// Thread.getStackTrace() / legacy ANRTracker lines without the "at " prefix.
+const THREAD_STACK_FRAME_LINE = /^\s*([\w$.]+)\.([\w$<>]+)\(([^):]*)(?::(\d+))?\)\s*$/;
+const EXCEPTION_HEADER = /^\s*(?:Caused by:\s*)?([\w$.]+)(?::(.*))?$/;
+// Mirrors pkg/exporter/androidretrace/native_frame.go nativeFrameLine.
+const NATIVE_TOMBSTONE_FRAME_LINE = /^\s*#(\d+)\s+pc\s+(?:0x)?([0-9a-fA-F]+)\s+(\S+)(?:\s+\(([^)]+)\))?/i;
+
+const TOMBSTONE_SECTION_LABELS = new Set(['backtrace', 'stack', 'build id', 'memory map', 'memory near', 'abi']);
+
+/** Tombstone section headers and metadata must not become exception_type / nativeExceptionType. */
+export function isTombstoneSectionLabel(value: string): boolean {
+  return TOMBSTONE_SECTION_LABELS.has(value.trim().toLowerCase());
+}
+
+function isTombstoneMetadataLine(line: string): boolean {
+  const trimmed = line.trim();
+  if (!trimmed) {
+    return true;
+  }
+  if (trimmed.startsWith('***')) {
+    return true;
+  }
+  if (/^ABI:/i.test(trimmed)) {
+    return true;
+  }
+  if (/^signal\s+/i.test(trimmed)) {
+    return true;
+  }
+  if (/^pid:/i.test(trimmed)) {
+    return true;
+  }
+  if (isTombstoneSectionLabel(trimmed.replace(/:$/, ''))) {
+    return true;
+  }
+  return false;
+}
+
+function nativeLibBasename(token: string): string {
+  const bang = token.lastIndexOf('!');
+  if (bang >= 0) {
+    token = token.slice(bang + 1);
+  }
+  const slash = token.lastIndexOf('/');
+  return slash >= 0 ? token.slice(slash + 1) : token;
+}
+
+function parseNativeTombstoneFrameLine(line: string): NativeTombstoneStackFrame | null {
+  const match = line.match(NATIVE_TOMBSTONE_FRAME_LINE);
+  if (!match) {
+    return null;
+  }
+
+  const library = match[3] ?? '';
+  const suffix = match[4]?.trim();
+  let fn = '<unknown>';
+  if (suffix) {
+    const fnMatch = suffix.match(/^([A-Za-z_][A-Za-z0-9_]*)(?:\+(\d+))?$/);
+    if (fnMatch?.[1] && fnMatch[1] !== 'BuildId' && fnMatch[1] !== 'offset') {
+      fn = fnMatch[1];
+    }
+  }
+
+  return {
+    module: nativeLibBasename(library),
+    function: fn,
+    filename: nativeLibBasename(library),
+  };
+}
+
+/** Reject version tokens (e.g. "18.2213") and other non-class header lines. */
+export function isPlausibleJavaExceptionIdentifier(value: string): boolean {
+  const trimmed = value.trim();
+  if (!trimmed || !/[a-zA-Z]/.test(trimmed)) {
+    return false;
+  }
+  if (/^\d+(\.\d+)+$/.test(trimmed)) {
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Normalize raw Java thread stacks (e.g. ANRTracker) to Log.getStackTraceString shape
+ * so collector R8 retrace (mapping.RetraceText) can rewrite frame lines.
+ */
+export function normalizeJavaStackTraceForRetrace(trace: string): string {
+  return trace
+    .split('\n')
+    .map((line) => {
+      const trimmed = line.trim();
+      if (!trimmed) {
+        return line;
+      }
+      if (/^\s*at\s+/.test(line)) {
+        return line;
+      }
+      if (THREAD_STACK_FRAME_LINE.test(trimmed)) {
+        return `    at ${trimmed}`;
+      }
+      return line;
+    })
+    .join('\n');
+}
+
+/**
+ * Normalize exception text from ApplicationExitInfo / Log.getStackTraceString headers.
+ *
+ * React Native fatal JS errors embed the JS message in a fixed header shape
+ * (`Error: <message>, stack:`) regardless of the wrapping Java exception class.
+ * Match on that shape instead of the exception type name.
+ */
+const RN_FATAL_JS_ERROR_HEADER = /^Error:\s*(.+?),\s*stack:\s*$/i;
+
+export function normalizeCrashTraceExceptionMessage(rawMessage: string | undefined): string | undefined {
+  if (!rawMessage?.trim()) {
+    return undefined;
+  }
+
+  const message = rawMessage.trim();
+  const rnFatalMatch = message.match(RN_FATAL_JS_ERROR_HEADER);
+
+  return (rnFatalMatch?.[1] ?? message).trim() || undefined;
+}
+
+function parseJsFrameLine(line: string, options?: ParseAndroidCrashTraceOptions): ExceptionStackFrame | null {
+  const parsed = parseStackTraceLine(line);
+  if (!parsed) {
+    return null;
+  }
+
+  return toFaroStackFrames([parsed], options)[0] ?? null;
+}
+
+/**
+ * Parse a raw Android crash trace into structured stack frames for pushError().
+ */
+export function parseAndroidCrashTrace(
+  trace: string,
+  options?: ParseAndroidCrashTraceOptions
+): ParsedAndroidCrashTrace | null {
+  const trimmed = trace.trim();
+  if (!trimmed) {
+    return null;
+  }
+
+  const lines = trimmed.split('\n');
+  const jsFrames: ExceptionStackFrame[] = [];
+  const frames: AndroidCrashStackFrame[] = [];
+  const nativeFrames: NativeTombstoneStackFrame[] = [];
+  let exceptionType: string | undefined;
+  let exceptionMessage: string | undefined;
+
+  lines.forEach((line) => {
+    const nativeFrame = parseNativeTombstoneFrameLine(line);
+    if (nativeFrame) {
+      nativeFrames.push(nativeFrame);
+      return;
+    }
+
+    const frameMatch = line.match(FRAME_LINE) ?? line.trim().match(THREAD_STACK_FRAME_LINE);
+
+    if (frameMatch) {
+      const [, module, method, filename, lineNo] = frameMatch;
+      frames.push({
+        module: module ?? '',
+        function: method ?? '<unknown>',
+        filename: filename?.trim() || 'SourceFile',
+        lineno: lineNo ? parseInt(lineNo, 10) : undefined,
+      });
+      return;
+    }
+
+    const jsFrame = parseJsFrameLine(line, options);
+    if (jsFrame) {
+      jsFrames.push(jsFrame);
+      return;
+    }
+
+    const headerMatch = line.match(EXCEPTION_HEADER);
+    if (
+      !isTombstoneMetadataLine(line) &&
+      headerMatch?.[1] &&
+      isPlausibleJavaExceptionIdentifier(headerMatch[1]) &&
+      !isTombstoneSectionLabel(headerMatch[1])
+    ) {
+      exceptionType = headerMatch[1];
+      exceptionMessage = normalizeCrashTraceExceptionMessage(headerMatch[2]);
+    }
+  });
+
+  if (frames.length === 0 && jsFrames.length === 0 && nativeFrames.length === 0 && !exceptionType) {
+    return null;
+  }
+
+  return { exceptionType, exceptionMessage, jsFrames, frames, nativeFrames };
+}

package/src/instrumentations/crashReporting/index.ts

@@ -1,2 +1,43 @@
-export { CrashReportingInstrumentation } from './instrumentation';
-export type { CrashReport, CrashReportingOptions } from './types';
+import { Platform } from 'react-native';
+
+import { AndroidCrashReportingInstrumentation } from './android';
+import { IosCrashReportingInstrumentation } from './ios';
+import { NoOpCrashReportingInstrumentation } from './NoOpCrashReportingInstrumentation';
+
+function resolveCrashReportingInstrumentation() {
+  if (Platform.OS === 'android') {
+    return AndroidCrashReportingInstrumentation;
+  }
+
+  if (Platform.OS === 'ios') {
+    // React Native reports both iPhone and iPadOS as "ios".
+    return IosCrashReportingInstrumentation;
+  }
+
+  return NoOpCrashReportingInstrumentation;
+}
+
+/**
+ * Platform-aware crash reporting instrumentation export.
+ *
+ * At module load time, determines the platform and exports the correct implementation:
+ * - Android: Uses ApplicationExitInfo API to retrieve crashes
+ * - iOS: Uses PLCrashReporter to retrieve crashes
+ * - Other: No-op stub (web, macOS, Windows, etc.)
+ *
+ * Usage:
+ * ```ts
+ * import { CrashReportingInstrumentation } from '@grafana/faro-react-native/instrumentation-crash';
+ *
+ * const faro = initializeFaro({
+ *   // ...
+ *   instrumentations: [
+ *     new CrashReportingInstrumentation(),
+ *   ],
+ * });
+ * ```
+ */
+export const CrashReportingInstrumentation = resolveCrashReportingInstrumentation();
+
+// Export public API types
+export type { CrashReportingOptions } from './types';