@grafana/faro-react-native 1.2.0 → 1.3.0

package/src/instrumentations/anr/instrumentation.ts

@@ -1,9 +1,11 @@
-import { NativeModules, Platform } from 'react-native';
+import { NativeEventEmitter, NativeModules, Platform } from 'react-native';
 
 import { BaseInstrumentation, VERSION } from '@grafana/faro-core';
 
+import { normalizeJavaStackTraceForRetrace, parseAndroidCrashTrace } from '../crashReporting/android';
 import { ErrorMechanism } from '../errors/const';
 
+import { isInvalidAnrCaptureStack } from './anrStack';
 import type { ANREvent, ANRInstrumentationOptions } from './types';
 
 /**
@@ -12,38 +14,26 @@ import type { ANREvent, ANRInstrumentationOptions } from './types';
 const DEFAULT_TIMEOUT = 5000;
 
 /**
- * Default polling interval for ANR status (60 seconds, matching Flutter SDK)
+ * Default polling interval for ANR status. Kept short so debug ANRs surface without
+ * waiting a full minute; native also emits onANRDetected for immediate delivery.
  */
-const DEFAULT_POLLING_INTERVAL = 60000;
+const DEFAULT_POLLING_INTERVAL = 10000;
+
+/** Aligns with native FaroAnrCache.MAX_TIMESTAMP_DELTA_MS */
+const TIMESTAMP_DEDUP_WINDOW_MS = 10_000;
+
+/** ApplicationExitInfo ANR traces (Android 11 / API 30+). */
+const APP_EXIT_INFO_MIN_SDK = 30;
 
 /**
  * ANR (Application Not Responding) Detection Instrumentation.
  *
- * Detects when the main/UI thread is blocked for extended periods on Android.
- * Uses a background thread that posts tasks to the main thread and monitors
- * if they complete within the timeout.
- *
- * **Note**: ANR detection is only available on Android. iOS does not have
- * the same ANR concept as Android's system watchdog.
- *
- * Sends telemetry via Faro API:
- * - Measurement: `anr` with `anr_count` value (for dashboards)
- * - Error: Each ANR with `type: 'ANR'`, stack trace, duration, timestamp (Sentry-aligned)
+ * On Android 11+, historical ANRs are read from ApplicationExitInfo (Sentry AnrV2
+ * style) on the next launch. ANRTracker remains a pre-API-30 fallback and a
+ * persistence backup when the OS trace stream is empty.
  *
- * @example
- * ```typescript
- * import { initializeFaro, ANRInstrumentation } from '@grafana/faro-react-native';
- *
- * initializeFaro({
- *   url: 'https://collector.example.com',
- *   instrumentations: [
- *     new ANRInstrumentation({
- *       timeout: 5000,        // 5 second threshold
- *       pollingInterval: 60000, // Poll every 60 seconds
- *     }),
- *   ],
- * });
- * ```
+ * ANRs stay out of CrashReportingInstrumentation so they are not replayed as
+ * generic previous-session `crash` rows with empty messages.
  */
 export class ANRInstrumentation extends BaseInstrumentation {
   readonly name = '@grafana/faro-react-native:instrumentation-anr';
@@ -51,6 +41,9 @@ export class ANRInstrumentation extends BaseInstrumentation {
 
   private readonly options: Required<ANRInstrumentationOptions>;
   private pollingIntervalId: ReturnType<typeof setInterval> | null = null;
+  private anrEventSubscription: ReturnType<NativeEventEmitter['addListener']> | null = null;
+  private readonly reportedAnrTimestamps = new Set<number>();
+  private readonly preferAppExitInfoAnr: boolean;
 
   constructor(options: ANRInstrumentationOptions = {}) {
     super();
@@ -58,10 +51,10 @@ export class ANRInstrumentation extends BaseInstrumentation {
       timeout: options.timeout ?? DEFAULT_TIMEOUT,
       pollingInterval: options.pollingInterval ?? DEFAULT_POLLING_INTERVAL,
     };
+    this.preferAppExitInfoAnr = Platform.OS === 'android' && Number(Platform.Version) >= APP_EXIT_INFO_MIN_SDK;
   }
 
   initialize(): void {
-    // ANR detection is only available on Android
     if (Platform.OS !== 'android') {
       this.logDebug('ANR detection is only available on Android');
       return;
@@ -75,12 +68,18 @@ export class ANRInstrumentation extends BaseInstrumentation {
 
     this.logDebug('Initializing ANR detection instrumentation');
 
-    // Start native ANR tracking
+    void this.drainAllAnrSources(nativeModule);
+
     this.startNativeTracking(nativeModule);
 
-    // Set up polling for ANR status
+    const emitter = new NativeEventEmitter(nativeModule);
+    this.anrEventSubscription = emitter.addListener('onANRDetected', (anrJson: string) => {
+      void this.handleLiveAnrEvent(nativeModule, anrJson);
+    });
+
+    void this.checkANRStatus(nativeModule);
     this.pollingIntervalId = setInterval(() => {
-      this.checkANRStatus(nativeModule);
+      void this.checkANRStatus(nativeModule);
     }, this.options.pollingInterval);
   }
 
@@ -107,68 +106,303 @@ export class ANRInstrumentation extends BaseInstrumentation {
     }
   }
 
-  private async checkANRStatus(nativeModule: typeof NativeModules.FaroReactNativeModule): Promise<void> {
+  private async drainAllAnrSources(nativeModule: typeof NativeModules.FaroReactNativeModule): Promise<void> {
+    await this.drainHistoricalAnrs(nativeModule);
+    await this.drainPendingANRs(nativeModule);
+  }
+
+  private async drainHistoricalAnrs(nativeModule: typeof NativeModules.FaroReactNativeModule): Promise<void> {
+    if (typeof nativeModule.getHistoricalAnrReports !== 'function') {
+      return;
+    }
+
     try {
-      if (typeof nativeModule.getANRStatus !== 'function') {
+      const anrList = (await nativeModule.getHistoricalAnrReports()) as string[] | null;
+      if (!anrList?.length) {
         return;
       }
 
-      const anrList = (await nativeModule.getANRStatus()) as string[] | null;
+      const ackTimestamps: number[] = [];
+      let reportedCount = 0;
 
-      if (anrList && anrList.length > 0) {
-        // Push measurement for ANR count (matching Flutter pattern)
+      for (const anrJson of anrList) {
+        try {
+          const anr = JSON.parse(anrJson) as ANREvent;
+          if (this.reportANRIfNew(anr)) {
+            reportedCount += 1;
+          }
+          ackTimestamps.push(anr.timestamp);
+          await this.acknowledgeNearbyPendingAnrs(nativeModule, anr.timestamp);
+        } catch (error) {
+          this.logError('Failed to parse historical ANR report', error);
+        }
+      }
+
+      if (reportedCount > 0) {
         this.api.pushMeasurement(
           {
             type: 'anr',
-            values: { anr_count: anrList.length },
+            values: { anr_count: reportedCount },
           },
           { skipDedupe: true }
         );
+        this.logDebug(`Reported ${reportedCount} historical ANR event(s) from ApplicationExitInfo`);
+      }
+    } catch (error) {
+      this.logError('Failed to drain historical ANRs', error);
+    }
+  }
 
-        // Push each ANR as an error with type='ANR' for filtering (Sentry-aligned)
-        for (const anrJson of anrList) {
-          try {
-            const anr = JSON.parse(anrJson) as ANREvent;
-
-            this.api.pushError(new Error('ANR (Application Not Responding)'), {
-              context: {
-                duration: String(anr.duration),
-                mechanism: ErrorMechanism.ANR,
-                stacktrace: anr.stacktrace,
-                timestamp: String(anr.timestamp),
-              },
-              type: 'ANR',
-            });
-          } catch {
-            // If parsing fails, still log the raw ANR
-            this.api.pushError(new Error('ANR (Application Not Responding)'), {
-              context: {
-                mechanism: ErrorMechanism.ANR,
-                raw: anrJson,
-              },
-              type: 'ANR',
-            });
-          }
+  private async drainPendingANRs(nativeModule: typeof NativeModules.FaroReactNativeModule): Promise<void> {
+    const anrList = await this.fetchPendingANRs(nativeModule);
+    if (!anrList?.length) {
+      return;
+    }
+
+    await this.reportAndAcknowledgePendingANRs(nativeModule, anrList);
+    this.logDebug(`Processed ${anrList.length} persisted ANR event(s) from tracker cache`);
+  }
+
+  private async handleLiveAnrEvent(
+    nativeModule: typeof NativeModules.FaroReactNativeModule,
+    anrJson: string
+  ): Promise<void> {
+    try {
+      const anr = JSON.parse(anrJson) as ANREvent;
+
+      if (this.preferAppExitInfoAnr) {
+        // Process death + ApplicationExitInfo on next launch delivers the main-thread dump.
+        this.logDebug('Deferring live ANR to ApplicationExitInfo on next launch');
+        return;
+      }
+
+      if (!this.shouldReportTrackerAnr(anr)) {
+        await this.acknowledgeANRs(nativeModule, [anr.timestamp]);
+        return;
+      }
+
+      if (this.reportANRIfNew(anr)) {
+        this.api.pushMeasurement(
+          {
+            type: 'anr',
+            values: { anr_count: 1 },
+          },
+          { skipDedupe: true }
+        );
+      }
+      await this.acknowledgeANRs(nativeModule, [anr.timestamp]);
+    } catch (error) {
+      this.logError('Failed to parse native ANR event', error);
+    }
+  }
+
+  private async fetchPendingANRs(nativeModule: typeof NativeModules.FaroReactNativeModule): Promise<string[] | null> {
+    try {
+      if (typeof nativeModule.getPendingANRs === 'function') {
+        return (await nativeModule.getPendingANRs()) as string[] | null;
+      }
+
+      if (typeof nativeModule.getANRStatus === 'function') {
+        return (await nativeModule.getANRStatus()) as string[] | null;
+      }
+    } catch (error) {
+      this.logError('Failed to fetch pending ANRs', error);
+    }
+
+    return null;
+  }
+
+  private async acknowledgeANRs(
+    nativeModule: typeof NativeModules.FaroReactNativeModule,
+    timestamps: number[]
+  ): Promise<void> {
+    if (!timestamps.length || typeof nativeModule.acknowledgeANRs !== 'function') {
+      return;
+    }
+
+    try {
+      await nativeModule.acknowledgeANRs(timestamps);
+    } catch (error) {
+      this.logError('Failed to acknowledge ANRs', error);
+    }
+  }
+
+  private async acknowledgeNearbyPendingAnrs(
+    nativeModule: typeof NativeModules.FaroReactNativeModule,
+    exitTimestamp: number
+  ): Promise<void> {
+    const pending = await this.fetchPendingANRs(nativeModule);
+    if (!pending?.length) {
+      return;
+    }
+
+    const ackTimestamps: number[] = [];
+    for (const anrJson of pending) {
+      try {
+        const anr = JSON.parse(anrJson) as ANREvent;
+        if (this.isNearbyTimestamp(anr.timestamp, exitTimestamp)) {
+          ackTimestamps.push(anr.timestamp);
+        }
+      } catch {
+        // ignore malformed cache entries
+      }
+    }
+
+    if (ackTimestamps.length > 0) {
+      await this.acknowledgeANRs(nativeModule, ackTimestamps);
+    }
+  }
+
+  private async reportAndAcknowledgePendingANRs(
+    nativeModule: typeof NativeModules.FaroReactNativeModule,
+    anrList: string[]
+  ): Promise<void> {
+    const ackTimestamps: number[] = [];
+    let reportedCount = 0;
+
+    for (const anrJson of anrList) {
+      try {
+        const anr = JSON.parse(anrJson) as ANREvent;
+
+        if (this.shouldReportTrackerAnr(anr) && this.reportANRIfNew(anr)) {
+          reportedCount += 1;
         }
 
-        this.logDebug(`Recorded ${anrList.length} ANR event(s)`);
+        ackTimestamps.push(anr.timestamp);
+      } catch {
+        const error = new Error('ANR (Application Not Responding)');
+        error.stack = undefined;
+        this.api.pushError(error, {
+          context: {
+            mechanism: ErrorMechanism.ANR,
+            raw: anrJson,
+          },
+          fatal: true,
+          type: 'ANR',
+        });
+      }
+    }
+
+    if (reportedCount > 0) {
+      this.api.pushMeasurement(
+        {
+          type: 'anr',
+          values: { anr_count: reportedCount },
+        },
+        { skipDedupe: true }
+      );
+    }
+
+    if (ackTimestamps.length > 0) {
+      await this.acknowledgeANRs(nativeModule, ackTimestamps);
+    }
+  }
+
+  private shouldReportTrackerAnr(anr: ANREvent): boolean {
+    if (this.isNearbyReportedTimestamp(anr.timestamp)) {
+      return false;
+    }
+
+    if (isInvalidAnrCaptureStack(anr.stacktrace)) {
+      return false;
+    }
+
+    // On API 30+, ApplicationExitInfo is preferred on launch; tracker pending entries
+    // are reported only when historical did not already cover the same incident.
+    return true;
+  }
+
+  private reportANRIfNew(anr: ANREvent): boolean {
+    if (this.isNearbyReportedTimestamp(anr.timestamp)) {
+      return false;
+    }
+
+    if (isInvalidAnrCaptureStack(anr.stacktrace)) {
+      return false;
+    }
+
+    this.rememberReportedTimestamp(anr.timestamp);
+    this.reportANR(anr);
+    return true;
+  }
+
+  private rememberReportedTimestamp(timestamp: number): void {
+    this.reportedAnrTimestamps.add(timestamp);
+  }
+
+  private isNearbyReportedTimestamp(timestamp: number): boolean {
+    for (const reported of Array.from(this.reportedAnrTimestamps)) {
+      if (this.isNearbyTimestamp(timestamp, reported)) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  private isNearbyTimestamp(a: number, b: number): boolean {
+    if (a <= 0 || b <= 0) {
+      return false;
+    }
+    return Math.abs(a - b) <= TIMESTAMP_DEDUP_WINDOW_MS;
+  }
+
+  private reportANR(anr: ANREvent): void {
+    const rawStacktrace = anr.stacktrace?.trim() ?? '';
+    const traceForRetrace = rawStacktrace ? normalizeJavaStackTraceForRetrace(rawStacktrace) : '';
+    const parsed = traceForRetrace ? parseAndroidCrashTrace(traceForRetrace) : null;
+
+    const message = anr.description?.trim() || 'ANR (Application Not Responding)';
+    const error = new Error(message);
+    error.stack = undefined;
+
+    const context: Record<string, string> = {
+      duration: String(anr.duration),
+      mechanism: ErrorMechanism.ANR,
+      timestamp: String(anr.timestamp),
+    };
+    if (anr.source) {
+      context['source'] = anr.source;
+    }
+    if (traceForRetrace) {
+      context['stacktrace'] = traceForRetrace;
+    }
+
+    const stackFrames = parsed?.frames ?? [];
+    if (!stackFrames.length && rawStacktrace) {
+      this.logWarn('ANR main-thread stack present but no Java/Kotlin frames parsed');
+    }
+
+    this.api.pushError(error, {
+      type: 'ANR',
+      context,
+      fatal: true,
+      ...(stackFrames.length ? { stackFrames } : {}),
+    });
+  }
+
+  private async checkANRStatus(nativeModule: typeof NativeModules.FaroReactNativeModule): Promise<void> {
+    try {
+      const anrList = await this.fetchPendingANRs(nativeModule);
+
+      if (anrList && anrList.length > 0) {
+        await this.reportAndAcknowledgePendingANRs(nativeModule, anrList);
+        this.logDebug(`Polled ${anrList.length} ANR event(s) from pending cache`);
       }
     } catch (error) {
       this.logError('Failed to check ANR status', error);
     }
   }
 
-  /**
-   * Clean up resources when instrumentation is disabled.
-   */
   unpatch(): void {
-    // Stop polling
     if (this.pollingIntervalId !== null) {
       clearInterval(this.pollingIntervalId);
       this.pollingIntervalId = null;
     }
 
-    // Stop native tracking
+    this.anrEventSubscription?.remove();
+    this.anrEventSubscription = null;
+    this.reportedAnrTimestamps.clear();
+
     if (Platform.OS === 'android') {
       const nativeModule = this.getNativeModule();
       if (nativeModule && typeof nativeModule.stopANRTracking === 'function') {

package/src/instrumentations/anr/types.ts

@@ -11,7 +11,7 @@ export interface ANRInstrumentationOptions {
 
   /**
    * Interval in milliseconds for polling ANR status from native.
-   * Default: 60000 (60 seconds, matching Flutter SDK's default)
+   * Default: 10000 (10 seconds). Native also emits onANRDetected immediately.
    */
   pollingInterval?: number;
 }
@@ -39,4 +39,10 @@ export interface ANREvent {
    * Duration of the ANR in milliseconds
    */
   duration: number;
+
+  /** Human-readable ANR description from ApplicationExitInfo when available. */
+  description?: string;
+
+  /** `AppExitInfo` (preferred) or `ANRTracker` (fallback). */
+  source?: string;
 }

package/src/instrumentations/console/index.ts

@@ -68,11 +68,15 @@ export class ConsoleInstrumentation extends BaseInstrumentation {
 
             if (value && !type && !stackFrames) {
               // Simple error without stack frames
-              this.api.pushError(new Error(ConsoleInstrumentation.consoleErrorPrefix + value), { context });
+              this.api.pushError(new Error(ConsoleInstrumentation.consoleErrorPrefix + value), {
+                context,
+                fatal: false,
+              });
             } else {
               // Error with type and/or stack frames (type from error.name, matches Web SDK)
               this.api.pushError(new Error(ConsoleInstrumentation.consoleErrorPrefix + (value ?? '')), {
                 context,
+                fatal: false,
                 type,
                 stackFrames,
               });

package/src/instrumentations/console/instrumentation.test.ts

@@ -46,11 +46,13 @@ describe('ConsoleInstrumentation', () => {
     expect((mockTransport.items[0] as TransportItem<ExceptionEvent>)?.payload.value).toBe(
       'console.error: console.error no 1'
     );
+    expect((mockTransport.items[0] as TransportItem<ExceptionEvent>)?.payload.fatal).toBe(false);
     expect((mockTransport.items[0] as TransportItem<ExceptionEvent>)?.payload.context?.mechanism).toBe('console');
     expect((mockTransport.items[1] as TransportItem<ExceptionEvent>)?.payload.type).toBe('Error');
     expect((mockTransport.items[1] as TransportItem<ExceptionEvent>)?.payload.value).toBe(
       'console.error: with object {"foo":"bar","baz":"bam"}'
     );
+    expect((mockTransport.items[1] as TransportItem<ExceptionEvent>)?.payload.fatal).toBe(false);
   });
 
   it('sends a faro error serialized with error serializer when console.error is called', () => {
@@ -80,10 +82,12 @@ describe('ConsoleInstrumentation', () => {
     expect((mockTransport.items[0] as TransportItem<ExceptionEvent>)?.payload.value).toBe(
       'console.error: console.error no 1'
     );
+    expect((mockTransport.items[0] as TransportItem<ExceptionEvent>)?.payload.fatal).toBe(false);
     expect((mockTransport.items[1] as TransportItem<ExceptionEvent>)?.payload.type).toBe('Error');
     expect((mockTransport.items[1] as TransportItem<ExceptionEvent>)?.payload.value).toBe(
       'console.error: with object ' + stringifyExternalJson(context)
     );
+    expect((mockTransport.items[1] as TransportItem<ExceptionEvent>)?.payload.fatal).toBe(false);
   });
 
   it('Handles objects with circular references', () => {
@@ -244,6 +248,7 @@ describe('ConsoleInstrumentation', () => {
     expect((mockTransport.items[2] as TransportItem<ExceptionEvent>)?.payload.value).toBe(
       'console.error: ' + errorLogMessage
     );
+    expect((mockTransport.items[2] as TransportItem<ExceptionEvent>)?.payload.fatal).toBe(false);
   });
 
   it('unpatch restores original console methods', () => {