@grafana/faro-react-native 1.3.0 → 1.4.0

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

@@ -0,0 +1,155 @@
+import { NativeModules, Platform } from 'react-native';
+
+import { initializeFaro, type MeasurementEvent, type TransportItem } from '@grafana/faro-core';
+import { mockConfig, MockTransport } from '@grafana/faro-test-utils';
+
+import { FrameMonitoringInstrumentation } from './instrumentation';
+
+jest.mock('react-native', () => ({
+  Platform: { OS: 'android' },
+  NativeModules: {
+    FaroReactNativeModule: {
+      startFrameMonitoring: jest.fn(),
+      getFrameMetrics: jest.fn(),
+      getRefreshRate: jest.fn().mockResolvedValue(null),
+      stopFrameMonitoring: jest.fn(),
+    },
+  },
+  NativeEventEmitter: jest.fn().mockImplementation(() => ({
+    addListener: jest.fn(() => ({ remove: jest.fn() })),
+  })),
+}));
+
+const POLL_INTERVAL_MS = 1000;
+
+function getNativeModule() {
+  return NativeModules.FaroReactNativeModule as {
+    startFrameMonitoring: jest.Mock;
+    getFrameMetrics: jest.Mock;
+    getRefreshRate: jest.Mock;
+    stopFrameMonitoring: jest.Mock;
+  };
+}
+
+function getFrozenFrameMeasurements(transport: MockTransport): MeasurementEvent[] {
+  return transport.items
+    .map((item) => item as TransportItem<MeasurementEvent>)
+    .filter((item) => item.type === 'measurement' && item.payload.type === 'app_frozen_frame')
+    .map((item) => item.payload);
+}
+
+describe('FrameMonitoringInstrumentation', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    jest.useFakeTimers();
+    getNativeModule().getFrameMetrics.mockResolvedValue(null);
+    getNativeModule().getRefreshRate.mockResolvedValue(null);
+  });
+
+  afterEach(() => {
+    jest.useRealTimers();
+  });
+
+  it('sends app_frozen_frame once per poll when frozen frames are reported', async () => {
+    const transport = new MockTransport();
+    getNativeModule().getFrameMetrics.mockResolvedValue({
+      refreshRate: 60,
+      slowFrames: 0,
+      frozenFrames: 2,
+      frozenDurationMs: 1550,
+    });
+
+    initializeFaro(
+      mockConfig({
+        refreshRateVitals: true,
+        transports: [transport],
+        instrumentations: [new FrameMonitoringInstrumentation({ refreshRatePollingInterval: POLL_INTERVAL_MS })],
+      })
+    );
+
+    await jest.advanceTimersByTimeAsync(POLL_INTERVAL_MS);
+
+    const measurements = getFrozenFrameMeasurements(transport);
+    expect(measurements).toHaveLength(1);
+    expect(measurements[0].values).toEqual({
+      frozen_frames: 2,
+      frozen_duration: 1550,
+    });
+  });
+
+  it('skips app_frozen_frame when frozen frame count is zero', async () => {
+    const transport = new MockTransport();
+    getNativeModule().getFrameMetrics.mockResolvedValue({
+      refreshRate: 60,
+      slowFrames: 0,
+      frozenFrames: 0,
+      frozenDurationMs: 0,
+    });
+
+    initializeFaro(
+      mockConfig({
+        refreshRateVitals: true,
+        transports: [transport],
+        instrumentations: [new FrameMonitoringInstrumentation({ refreshRatePollingInterval: POLL_INTERVAL_MS })],
+      })
+    );
+
+    await jest.advanceTimersByTimeAsync(POLL_INTERVAL_MS);
+
+    expect(getFrozenFrameMeasurements(transport)).toHaveLength(0);
+  });
+
+  it('does not send app_frozen_frame when duration is zero even if count is positive', async () => {
+    const transport = new MockTransport();
+    getNativeModule().getFrameMetrics.mockResolvedValue({
+      refreshRate: 60,
+      slowFrames: 0,
+      frozenFrames: 1,
+      frozenDurationMs: 0,
+    });
+
+    initializeFaro(
+      mockConfig({
+        refreshRateVitals: true,
+        transports: [transport],
+        instrumentations: [new FrameMonitoringInstrumentation({ refreshRatePollingInterval: POLL_INTERVAL_MS })],
+      })
+    );
+
+    await jest.advanceTimersByTimeAsync(POLL_INTERVAL_MS);
+
+    expect(getFrozenFrameMeasurements(transport)).toHaveLength(0);
+  });
+
+  it('reports frozen frames through polling only on Android (no duplicate event path)', async () => {
+    const transport = new MockTransport();
+    getNativeModule()
+      .getFrameMetrics.mockResolvedValueOnce({
+        refreshRate: 60,
+        slowFrames: 0,
+        frozenFrames: 1,
+        frozenDurationMs: 850,
+      })
+      .mockResolvedValueOnce({
+        refreshRate: 60,
+        slowFrames: 0,
+        frozenFrames: 0,
+        frozenDurationMs: 0,
+      });
+
+    initializeFaro(
+      mockConfig({
+        refreshRateVitals: true,
+        transports: [transport],
+        instrumentations: [new FrameMonitoringInstrumentation({ refreshRatePollingInterval: POLL_INTERVAL_MS })],
+      })
+    );
+
+    await jest.advanceTimersByTimeAsync(POLL_INTERVAL_MS);
+    await jest.advanceTimersByTimeAsync(POLL_INTERVAL_MS);
+
+    expect(getFrozenFrameMeasurements(transport)).toHaveLength(1);
+    expect(Platform.OS).toBe('android');
+    expect(getNativeModule().startFrameMonitoring).toHaveBeenCalledTimes(1);
+  });
+});

package/src/instrumentations/frameMonitoring/instrumentation.ts

@@ -7,11 +7,11 @@ import type { ReactNativeConfig } from '../../config/types';
 import type { FrameMetrics, FrameMonitoringOptions } from './types';
 
 /**
- * Default configuration values matching Flutter SDK's hardcoded values.
- * These are React Native-specific advanced options for customization.
+ * Default configuration values. Frozen frame threshold aligns with Android Vitals
+ * and OpenTelemetry Android slow rendering instrumentation (700ms).
  */
 const DEFAULT_TARGET_FPS = 60;
-const DEFAULT_FROZEN_FRAME_THRESHOLD_MS = 100;
+const DEFAULT_FROZEN_FRAME_THRESHOLD_MS = 700;
 const DEFAULT_REFRESH_RATE_POLLING_INTERVAL = 30000;
 const DEFAULT_NORMALIZED_REFRESH_RATE = 60;
 
@@ -29,7 +29,7 @@ const DEFAULT_NORMALIZED_REFRESH_RATE = 60;
  * - Reports meaningful performance degradation that affects user experience
  *
  * ## Frozen Frame Detection
- * Frozen frames are individual frames exceeding `frozenFrameThresholdMs` (default 100ms).
+ * Frozen frames are individual frames exceeding `frozenFrameThresholdMs` (default 700ms).
  * These represent severe jank where the app appears unresponsive.
  *
  * Sends measurements via Faro API:
@@ -46,7 +46,7 @@ const DEFAULT_NORMALIZED_REFRESH_RATE = 60;
  *   instrumentations: [
  *     new FrameMonitoringInstrumentation({
  *       targetFps: 60,
- *       frozenFrameThresholdMs: 100,
+ *       frozenFrameThresholdMs: 700,
  *       refreshRatePollingInterval: 30000,
  *     }),
  *   ],
@@ -94,7 +94,7 @@ export class FrameMonitoringInstrumentation extends BaseInstrumentation {
     // Start native frame monitoring with configuration
     this.startNativeMonitoring(nativeModule);
 
-    // Set up event listeners for real-time frame events (Android pattern)
+    // Set up Android refresh rate events (throttled on native side); frozen/slow frames use polling
     this.setupEventListeners(nativeModule);
 
     // Set up polling for periodic metrics collection (iOS pattern)
@@ -127,35 +127,24 @@ export class FrameMonitoringInstrumentation extends BaseInstrumentation {
   }
 
   private setupEventListeners(nativeModule: typeof NativeModules.FaroReactNativeModule): void {
-    // Android uses event-based approach for frozen frames only
-    // Slow frames are retrieved via polling (like iOS) to avoid flooding
-    if (Platform.OS === 'android') {
+    // Android: refresh rate only. Slow and frozen frames are polled (same as iOS) to avoid duplicate reports.
+    if (Platform.OS === 'android' && this.refreshRateVitalsEnabled) {
       try {
         this.eventEmitter = new NativeEventEmitter(nativeModule);
 
-        // Listen for frozen frame events
-        const frozenFrameSubscription = this.eventEmitter.addListener(
-          'onFrozenFrame',
-          (data: number | { count: number; durationMs: number }) => {
-            // Support both formats: number (legacy) or object (with duration)
-            if (typeof data === 'number') {
-              this.handleFrozenFrame(data, 0);
-            } else {
-              this.handleFrozenFrame(data.count, data.durationMs || 0);
-            }
+        const refreshRateSubscription = this.eventEmitter.addListener('onRefreshRate', (...args: readonly Object[]) => {
+          const [refreshRate] = args;
+
+          if (typeof refreshRate !== 'number') {
+            this.logWarn('Ignoring onRefreshRate event without a numeric payload');
+            return;
           }
-        );
-        this.eventSubscriptions.push(frozenFrameSubscription);
 
-        // Listen for refresh rate events (only when refreshRateVitals is enabled in config)
-        if (this.refreshRateVitalsEnabled) {
-          const refreshRateSubscription = this.eventEmitter.addListener('onRefreshRate', (refreshRate: number) => {
-            this.handleRefreshRate(refreshRate);
-          });
-          this.eventSubscriptions.push(refreshRateSubscription);
-        }
+          this.handleRefreshRate(refreshRate);
+        });
+        this.eventSubscriptions.push(refreshRateSubscription);
 
-        this.logDebug('Set up Android frame event listeners');
+        this.logDebug('Set up Android refresh rate event listener');
       } catch (error) {
         this.logError('Failed to set up frame event listeners', error);
       }
@@ -163,8 +152,7 @@ export class FrameMonitoringInstrumentation extends BaseInstrumentation {
   }
 
   private startPolling(): void {
-    // Both iOS and Android use polling approach for slow frames
-    // This provides consistent behavior and avoids flooding with events
+    // Both iOS and Android use polling for slow and frozen frames (avoids duplicate reports on Android).
     this.pollingIntervalId = setInterval(() => {
       this.pollFrameMetrics();
     }, this.options.refreshRatePollingInterval);
@@ -230,14 +218,7 @@ export class FrameMonitoringInstrumentation extends BaseInstrumentation {
   }
 
   private handleFrozenFrame(count: number, durationMs: number): void {
-    // Only send frozen frame events if duration is greater than 0
-    // This filters out any erroneous 0ms frozen frames
     if (durationMs > 0) {
-      // 🔍 TEMP DEBUG LOG - Remove after analysis
-      console.log(
-        `[Faro DEBUG ${Platform.OS.toUpperCase()}] 🧊 SENDING frozen frame: count=${count}, duration=${durationMs}ms`
-      );
-
       this.api.pushMeasurement(
         {
           type: 'app_frozen_frame',

package/src/instrumentations/frameMonitoring/types.ts

@@ -1,9 +1,7 @@
 /**
  * Configuration options for Frame Monitoring instrumentation.
  *
- * These are React Native-specific advanced options. The Flutter SDK uses fixed values
- * for these parameters (not configurable). Defaults here match Flutter's hardcoded values
- * for cross-platform consistency.
+ * Frozen frame threshold (700ms).
  *
  * Note: To enable frame monitoring, set `refreshRateVitals: true` in ReactNativeConfig.
  */
@@ -11,14 +9,14 @@ export interface FrameMonitoringOptions {
   /**
    * Target frames per second for slow frame detection.
    * Frames rendering below this threshold are considered "slow".
-   * Default: 60 (Flutter SDK hardcoded value)
+   * Default: 60
    */
   targetFps?: number;
 
   /**
    * Threshold in milliseconds for detecting frozen frames.
    * Frames taking longer than this are considered "frozen".
-   * Default: 100ms (Flutter SDK uses 100_000_000 nanoseconds)
+   * Default: 700ms (Android Vitals and OpenTelemetry Android slow rendering instrumentation)
    */
   frozenFrameThresholdMs?: number;
 
@@ -31,7 +29,7 @@ export interface FrameMonitoringOptions {
   /**
    * Normalized refresh rate for ProMotion displays (120Hz, etc.).
    * Used to normalize frame rates for high-refresh-rate displays to a standard baseline.
-   * Default: 60 (Flutter SDK's backendSupportedFrameRate)
+   * Default: 60
    */
   normalizedRefreshRate?: number;
 }

package/src/instrumentations/performance/index.ts

@@ -13,8 +13,6 @@ const { FaroReactNativeModule } = NativeModules;
  * - iOS: task_info() for memory, host_statistics() for CPU
  * - Android: /proc/[pid]/status for memory, /proc/[pid]/stat for CPU
  *
- * Implementation ported from Faro Flutter SDK with feature parity.
- *
  * **Key Features**:
  * - ✅ NO manual setup required - OS tracks metrics automatically!
  * - ✅ Periodic collection (default: every 30 seconds)
@@ -143,16 +141,14 @@ export class PerformanceInstrumentation extends BaseInstrumentation {
       const cpuUsage = FaroReactNativeModule.getCpuUsage();
       this.logDebug(`CPU: raw value = ${cpuUsage}`);
 
-      // Validate CPU usage (Flutter SDK filters 0-100 range, but allows >100)
-      // Skip null, negative, or exactly 0 (baseline reading)
+      // Validate CPU usage. Skip null, negative, or exactly 0 (baseline reading).
       if (cpuUsage == null || cpuUsage <= 0) {
         this.logDebug('CPU: skipping - value is null or <= 0');
         return;
       }
 
       this.logDebug(`CPU: pushing measurement with cpu_usage = ${cpuUsage}`);
-      // Flutter SDK also filters values >= 100, but we allow them as they can be valid
-      // in multi-core scenarios where one core is maxed out
+      // Values >= 100 can be valid in multi-core scenarios where one core is maxed out.
       this.api.pushMeasurement({
         type: 'app_cpu_usage',
         values: { cpu_usage: cpuUsage },

package/src/instrumentations/session/FaroSessionActivityBoundary.test.ts

@@ -0,0 +1,60 @@
+import React from 'react';
+import { Text, View } from 'react-native';
+import { act, create, type ReactTestRenderer } from 'react-test-renderer';
+
+import * as directSessionActivity from './directSessionActivity';
+import { FaroSessionActivityBoundary } from './FaroSessionActivityBoundary';
+
+describe('FaroSessionActivityBoundary', () => {
+  let renderer: ReactTestRenderer | undefined;
+
+  afterEach(() => {
+    if (renderer != null) {
+      const mountedRenderer = renderer;
+      act(() => mountedRenderer.unmount());
+      renderer = undefined;
+    }
+    jest.restoreAllMocks();
+  });
+
+  it('renders a boundary that records a captured touch without claiming the responder', async () => {
+    const notifySpy = jest.spyOn(directSessionActivity, 'notifySessionActivity').mockImplementation();
+    const child = React.createElement(Text, null, 'Press me');
+    const event = { nativeEvent: {} } as never;
+    await act(async () => {
+      renderer = create(React.createElement(FaroSessionActivityBoundary, null, child));
+    });
+    if (renderer == null) {
+      throw new Error('Expected the activity boundary to render.');
+    }
+
+    const boundary = renderer.root.findByType(View);
+    const claimsResponder = boundary.props.onStartShouldSetResponderCapture(event);
+
+    expect(notifySpy).toHaveBeenCalledTimes(1);
+    expect(claimsResponder).toBe(false);
+    expect(renderer.root.findByType(Text).props.children).toBe('Press me');
+  });
+
+  it('preserves a caller responder decision and layout override', async () => {
+    const onStartShouldSetResponderCapture = jest.fn(() => true);
+    const event = { nativeEvent: {} } as never;
+    await act(async () => {
+      renderer = create(
+        React.createElement(FaroSessionActivityBoundary, {
+          onStartShouldSetResponderCapture,
+          style: { flex: 0, height: 40 },
+        })
+      );
+    });
+    if (renderer == null) {
+      throw new Error('Expected the activity boundary to render.');
+    }
+
+    const boundary = renderer.root.findByType(View);
+
+    expect(boundary.props.onStartShouldSetResponderCapture(event)).toBe(true);
+    expect(onStartShouldSetResponderCapture).toHaveBeenCalledWith(event);
+    expect(boundary.props.style).toEqual([{ flex: 1 }, { flex: 0, height: 40 }]);
+  });
+});

package/src/instrumentations/session/FaroSessionActivityBoundary.tsx

@@ -0,0 +1,41 @@
+import { type PropsWithChildren, useCallback } from 'react';
+import { type GestureResponderEvent, StyleSheet, View, type ViewProps } from 'react-native';
+
+import { notifySessionActivity } from './directSessionActivity';
+
+export type FaroSessionActivityBoundaryProps = PropsWithChildren<ViewProps>;
+
+/**
+ * Records touch activity for the React Native subtree without emitting a user
+ * action or taking ownership of the responder.
+ */
+export function FaroSessionActivityBoundary({
+  children,
+  onStartShouldSetResponderCapture,
+  style,
+  ...viewProps
+}: FaroSessionActivityBoundaryProps) {
+  const handleStartShouldSetResponderCapture = useCallback(
+    (event: GestureResponderEvent): boolean => {
+      notifySessionActivity();
+      return onStartShouldSetResponderCapture?.(event) ?? false;
+    },
+    [onStartShouldSetResponderCapture]
+  );
+
+  return (
+    <View
+      {...viewProps}
+      onStartShouldSetResponderCapture={handleStartShouldSetResponderCapture}
+      style={[styles.container, style]}
+    >
+      {children}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+  },
+});