@grafana/faro-react-native 1.3.1 → 1.4.0

package/android/src/main/java/com/grafana/faro/reactnative/FaroCrashTraceCache.kt

@@ -27,7 +27,10 @@ internal object FaroCrashTraceCache {
      * Returns a cached trace without clearing it so multiple ApplicationExitInfo
      * rows for the same crash can share the UncaughtExceptionHandler stack.
      */
-    fun peekPendingCrashTrace(context: Context): PendingTrace? {
+    fun peekPendingCrashTrace(
+        context: Context,
+        nowMs: Long = System.currentTimeMillis(),
+    ): PendingTrace? {
         val prefs = context.applicationContext.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
         val trace = prefs.getString(KEY_TRACE, null)?.trim().orEmpty()
         val cachedTimestamp = prefs.getLong(KEY_TIMESTAMP, 0L)
@@ -35,6 +38,13 @@ internal object FaroCrashTraceCache {
         if (trace.isEmpty() || cachedTimestamp == 0L) {
             return null
         }
+        if (
+            cachedTimestamp > nowMs ||
+            nowMs - cachedTimestamp > FaroCrashSessionStore.MAX_CONTEXT_AGE_MS
+        ) {
+            clearPendingCrashTrace(context)
+            return null
+        }
 
         return PendingTrace(trace, cachedTimestamp)
     }
@@ -45,7 +55,6 @@ internal object FaroCrashTraceCache {
         }
         val delta = kotlin.math.abs(exitTimestampMs - pending.timestampMs)
         if (delta > MAX_TIMESTAMP_DELTA_MS) {
-            clearPendingCrashTrace(context)
             return ""
         }
         return pending.trace

package/android/src/main/java/com/grafana/faro/reactnative/FaroReactNativeModule.kt

@@ -39,9 +39,39 @@ class FaroReactNativeModule(reactContext: ReactApplicationContext) :
     }
 
     private var anrTracker: ANRTracker? = null
+    private val sessionPersistenceOwner = Any()
 
     override fun getName(): String = NAME
 
+    /** Stable process name used to isolate persisted session chains. */
+    @ReactMethod(isBlockingSynchronousMethod = true)
+    fun getSessionProcessIdentifier(): String? {
+        return FaroSessionProcess.identifier()
+    }
+
+    /** Whether this module is running in the application's declared main process. */
+    @ReactMethod(isBlockingSynchronousMethod = true)
+    fun isMainSessionProcess(): Boolean? {
+        return FaroSessionProcess.isMainProcess(reactApplicationContext.applicationContext)
+    }
+
+    /** Allows only one React Native runtime in this process to write session state. */
+    @ReactMethod(isBlockingSynchronousMethod = true)
+    fun claimSessionPersistence(): Boolean {
+        return FaroSessionProcess.claimPersistence(sessionPersistenceOwner)
+    }
+
+    /** Releases session persistence when this React Native runtime is torn down. */
+    @ReactMethod(isBlockingSynchronousMethod = true)
+    fun releaseSessionPersistence(): Boolean {
+        return FaroSessionProcess.releasePersistence(sessionPersistenceOwner)
+    }
+
+    override fun invalidate() {
+        FaroSessionProcess.releasePersistence(sessionPersistenceOwner)
+        super.invalidate()
+    }
+
     /**
      * Gets app startup duration in milliseconds using Android OS APIs
      *
@@ -96,9 +126,9 @@ class FaroReactNativeModule(reactContext: ReactApplicationContext) :
      */
     @ReactMethod
     fun startFrameMonitoring(config: ReadableMap) {
-        val targetFps = if (config.hasKey("targetFps")) config.getDouble("targetFps") else 60.0
-        val frozenFrameThresholdMs = if (config.hasKey("frozenFrameThresholdMs")) config.getDouble("frozenFrameThresholdMs") else 100.0
-        val normalizedRefreshRate = if (config.hasKey("normalizedRefreshRate")) config.getDouble("normalizedRefreshRate") else 60.0
+        val targetFps = if (config.hasKey("targetFps")) config.getDouble("targetFps") else FrameMonitor.DEFAULT_TARGET_FPS
+        val frozenFrameThresholdMs = if (config.hasKey("frozenFrameThresholdMs")) config.getDouble("frozenFrameThresholdMs") else FrameMonitor.DEFAULT_FROZEN_FRAME_THRESHOLD_MS
+        val normalizedRefreshRate = if (config.hasKey("normalizedRefreshRate")) config.getDouble("normalizedRefreshRate") else FrameMonitor.DEFAULT_NORMALIZED_REFRESH_RATE
 
         FrameMonitor.configure(
             targetFps = targetFps,
@@ -106,17 +136,8 @@ class FaroReactNativeModule(reactContext: ReactApplicationContext) :
             normalizedRefreshRate = normalizedRefreshRate
         )
 
-        // Set up event callbacks to emit events to JavaScript
+        // Refresh rate events only; slow/frozen frames are read via getFrameMetrics polling
         FrameMonitor.setCallbacks(
-            onSlowFrames = { count -> sendEvent("onSlowFrames", count) },
-            onFrozenFrame = { count, durationMs -> 
-                // Send frozen frame event with count and duration
-                val data = WritableNativeMap().apply {
-                    putInt("count", count)
-                    putDouble("durationMs", durationMs)
-                }
-                sendEvent("onFrozenFrame", data)
-            },
             onRefreshRate = { rate -> sendEvent("onRefreshRate", rate) }
         )
 
@@ -154,11 +175,12 @@ class FaroReactNativeModule(reactContext: ReactApplicationContext) :
      */
     @ReactMethod
     fun getFrameMetrics(promise: Promise) {
+        val frozenMetrics = FrameMonitor.getAndResetFrozenMetrics()
         val metrics = WritableNativeMap().apply {
             putDouble("refreshRate", FrameMonitor.getRefreshRate())
             putInt("slowFrames", FrameMonitor.getAndResetSlowFrames())
-            putInt("frozenFrames", FrameMonitor.getAndResetFrozenFrames())
-            putDouble("frozenDurationMs", FrameMonitor.getAndResetFrozenDuration())
+            putInt("frozenFrames", frozenMetrics.count)
+            putDouble("frozenDurationMs", frozenMetrics.durationMs)
         }
         promise.resolve(metrics)
     }
@@ -298,10 +320,39 @@ class FaroReactNativeModule(reactContext: ReactApplicationContext) :
      */
     @ReactMethod
     fun getCrashReport(promise: Promise) {
+        resolveCrashReports(promise, acknowledgeImmediately = true)
+    }
+
+    /**
+     * Returns recovered crashes without marking them as processed. JavaScript
+     * must acknowledge each report after it has been handled.
+     */
+    @ReactMethod
+    fun getPendingCrashReports(promise: Promise) {
+        resolveCrashReports(promise, acknowledgeImmediately = false)
+    }
+
+    private fun resolveCrashReports(
+        promise: Promise,
+        acknowledgeImmediately: Boolean,
+    ) {
         val crashReports = FaroCrashReporter.getCrashReports(reactApplicationContext)
-        
+
         if (crashReports != null) {
-            val writableArray = com.facebook.react.bridge.Arguments.createArray()
+            if (acknowledgeImmediately) {
+                // Preserve eager acknowledgement for older JavaScript bundles
+                // that use the legacy bridge and cannot acknowledge per report.
+                val reportIds = crashReports.mapNotNull { report ->
+                    try {
+                        org.json.JSONObject(report).optString("reportId").trim().takeIf(String::isNotEmpty)
+                    } catch (_: Exception) {
+                        null
+                    }
+                }
+                FaroCrashReporter.acknowledgeCrashReports(reactApplicationContext, reportIds)
+            }
+
+            val writableArray = Arguments.createArray()
             for (report in crashReports) {
                 writableArray.pushString(report)
             }
@@ -311,6 +362,59 @@ class FaroReactNativeModule(reactContext: ReactApplicationContext) :
         }
     }
 
+    /**
+     * Persists the active Faro session independently of optional sticky-session storage.
+     * The synchronous write makes the context available even if the process crashes
+     * immediately after JavaScript observes a session change.
+     */
+    @ReactMethod(isBlockingSynchronousMethod = true)
+    fun recordCrashSessionContext(sessionContext: ReadableMap): Boolean {
+        return try {
+            val sessionId = sessionContext.getOptionalString("sessionId") ?: return false
+            val activatedAtMs = if (sessionContext.hasKey("activatedAt") && !sessionContext.isNull("activatedAt")) {
+                sessionContext.getDouble("activatedAt").toLong()
+            } else {
+                System.currentTimeMillis()
+            }
+            val isSampled = if (sessionContext.hasKey("isSampled") && !sessionContext.isNull("isSampled")) {
+                sessionContext.getBoolean("isSampled")
+            } else {
+                null
+            }
+
+            FaroUncaughtExceptionHandler.install(reactApplicationContext)
+            FaroCrashSessionStore.recordSessionContext(
+                context = reactApplicationContext,
+                sessionId = sessionId,
+                activatedAtMs = activatedAtMs,
+                isSampled = isSampled,
+                appVersion = sessionContext.getOptionalString("appVersion"),
+                appRelease = sessionContext.getOptionalString("appRelease"),
+                appBundleId = sessionContext.getOptionalString("appBundleId"),
+            )
+        } catch (_: Exception) {
+            false
+        }
+    }
+
+    /**
+     * Acknowledges only reports that JavaScript has finished handling.
+     */
+    @ReactMethod
+    fun acknowledgeCrashReports(reportIds: ReadableArray, promise: Promise) {
+        val ids = mutableListOf<String>()
+        for (index in 0 until reportIds.size()) {
+            if (!reportIds.isNull(index)) {
+                reportIds.getString(index)?.trim()?.takeIf(String::isNotEmpty)?.let(ids::add)
+            }
+        }
+        if (FaroCrashReporter.acknowledgeCrashReports(reactApplicationContext, ids)) {
+            promise.resolve(null)
+        } else {
+            promise.reject("E_CRASH_ACK_FAILED", "Failed to persist recovered crash acknowledgement")
+        }
+    }
+
     /**
      * Required for NativeEventEmitter on modern React Native versions.
      */
@@ -336,4 +440,11 @@ class FaroReactNativeModule(reactContext: ReactApplicationContext) :
             // Ignore errors when sending events
         }
     }
+
+    private fun ReadableMap.getOptionalString(key: String): String? {
+        if (!hasKey(key) || isNull(key)) {
+            return null
+        }
+        return getString(key)?.trim()?.takeIf(String::isNotEmpty)
+    }
 }

package/android/src/main/java/com/grafana/faro/reactnative/FaroSessionProcess.kt

@@ -0,0 +1,88 @@
+package com.grafana.faro.reactnative
+
+import android.app.Application
+import android.content.Context
+import android.os.Build
+import java.io.File
+import java.lang.ref.WeakReference
+
+/** Process identity and single-writer ownership for persisted session state. */
+internal object FaroSessionProcess {
+    private val persistenceLock = Any()
+    private var persistenceOwner: WeakReference<Any>? = null
+
+    fun identifier(): String? =
+        identifier(
+            sdkInt = Build.VERSION.SDK_INT,
+            currentProcessName = { Application.getProcessName() },
+            legacyProcessName = { File("/proc/self/cmdline").readText() },
+        )
+
+    internal fun identifier(
+        sdkInt: Int,
+        currentProcessName: () -> String?,
+        legacyProcessName: () -> String?,
+    ): String? {
+        val currentName = try {
+            if (sdkInt >= Build.VERSION_CODES.P) {
+                currentProcessName()
+            } else {
+                legacyProcessName()?.substringBefore('\u0000')
+            }
+        } catch (_: Exception) {
+            null
+        }
+
+        return normalizeIdentifier(currentName)
+    }
+
+    fun isMainProcess(context: Context): Boolean? {
+        return isMainProcess(
+            currentName = identifier(),
+            declaredMainName = context.applicationInfo.processName,
+            packageName = context.packageName,
+        )
+    }
+
+    fun claimPersistence(owner: Any): Boolean =
+        synchronized(persistenceLock) {
+            val currentOwner = persistenceOwner?.get()
+            if (currentOwner != null && currentOwner !== owner) {
+                false
+            } else {
+                persistenceOwner = WeakReference(owner)
+                true
+            }
+        }
+
+    fun releasePersistence(owner: Any): Boolean =
+        synchronized(persistenceLock) {
+            if (persistenceOwner?.get() !== owner) {
+                false
+            } else {
+                persistenceOwner = null
+                true
+            }
+        }
+
+    internal fun normalizeIdentifier(currentName: String?): String? =
+        currentName?.trim()?.takeIf { it.isNotEmpty() }
+
+    internal fun isMainProcess(
+        currentName: String?,
+        declaredMainName: String?,
+        packageName: String?,
+    ): Boolean? {
+        val normalizedCurrentName = normalizeIdentifier(currentName) ?: return null
+        val normalizedMainName = normalizeIdentifier(declaredMainName)
+            ?: normalizeIdentifier(packageName)
+            ?: return null
+        return normalizedCurrentName == normalizedMainName
+    }
+
+    internal fun resetPersistenceClaimForTest() {
+        synchronized(persistenceLock) {
+            persistenceOwner = null
+        }
+    }
+}

package/android/src/main/java/com/grafana/faro/reactnative/FrameMonitor.kt

@@ -21,20 +21,27 @@ object FrameMonitor {
     private const val NANOSECONDS_IN_MILLISECOND = 1_000_000L
 
     // Throttle refresh rate emits to avoid flooding the JS bridge (was ~60/sec).
-    // Aligns with refreshRatePollingInterval (30s) on iOS and Flutter SDK.
+    // Aligns with refreshRatePollingInterval (30s) on iOS.
     private const val REFRESH_RATE_EMIT_INTERVAL_MS = 30_000L
 
+    const val DEFAULT_TARGET_FPS = 60.0
+    const val DEFAULT_FROZEN_FRAME_THRESHOLD_MS = 700.0
+    const val DEFAULT_NORMALIZED_REFRESH_RATE = 60.0
+
+    data class FrozenFrameMetrics(val count: Int, val durationMs: Double)
+
     // Configuration
-    private var targetFps: Double = 60.0
-    private var frozenFrameThresholdNs: Long = 100 * NANOSECONDS_IN_MILLISECOND
-    private var normalizedRefreshRate: Double = 60.0
+    private var targetFps: Double = DEFAULT_TARGET_FPS
+    private var frozenFrameThresholdNs: Long =
+        (DEFAULT_FROZEN_FRAME_THRESHOLD_MS * NANOSECONDS_IN_MILLISECOND).toLong()
+    private var normalizedRefreshRate: Double = DEFAULT_NORMALIZED_REFRESH_RATE
 
     // State
     private var lastFrameTimeNanos: Long = 0
     private var lastRefreshRate: Double = 0.0
     private var lastRefreshRateEmitTimeMs: Long = 0
     private val slowFrameEventCount = AtomicInteger(0)
-    private val frozenFrameCount = AtomicInteger(0)
+    private var frozenFrameCount: Int = 0
     private var frozenFrameDurationMs: Double = 0.0
     private val isMonitoring = AtomicBoolean(false)
 
@@ -54,13 +61,13 @@ object FrameMonitor {
      * Configure monitoring parameters.
      *
      * @param targetFps Target FPS for slow frame detection (default 60)
-     * @param frozenFrameThresholdMs Threshold in ms for frozen frames (default 100)
+     * @param frozenFrameThresholdMs Threshold in ms for frozen frames (default 700)
      * @param normalizedRefreshRate Normalized rate for high-refresh displays (default 60)
      */
     fun configure(
-        targetFps: Double = 60.0,
-        frozenFrameThresholdMs: Double = 100.0,
-        normalizedRefreshRate: Double = 60.0
+        targetFps: Double = DEFAULT_TARGET_FPS,
+        frozenFrameThresholdMs: Double = DEFAULT_FROZEN_FRAME_THRESHOLD_MS,
+        normalizedRefreshRate: Double = DEFAULT_NORMALIZED_REFRESH_RATE
     ) {
         this.targetFps = targetFps
         this.frozenFrameThresholdNs = (frozenFrameThresholdMs * NANOSECONDS_IN_MILLISECOND).toLong()
@@ -91,7 +98,7 @@ object FrameMonitor {
             lastFrameTimeNanos = 0
             lastRefreshRateEmitTimeMs = 0
             slowFrameEventCount.set(0)
-            frozenFrameCount.set(0)
+            frozenFrameCount = 0
             frozenFrameDurationMs = 0.0
             inSlowFrameEvent = false
             slowFrameEventStartTimeNanos = 0
@@ -131,7 +138,7 @@ object FrameMonitor {
         // Reset state
         lastFrameTimeNanos = 0
         slowFrameEventCount.set(0)
-        frozenFrameCount.set(0)
+        frozenFrameCount = 0
         frozenFrameDurationMs = 0.0
     }
 
@@ -151,20 +158,22 @@ object FrameMonitor {
     }
 
     /**
-     * Get and reset frozen frame count.
-     */
-    fun getAndResetFrozenFrames(): Int {
-        return frozenFrameCount.getAndSet(0)
-    }
-
-    /**
-     * Get and reset frozen frame duration in milliseconds.
+     * Get and reset frozen frame count and duration atomically.
      */
     @Synchronized
-    fun getAndResetFrozenDuration(): Double {
+    fun getAndResetFrozenMetrics(): FrozenFrameMetrics {
+        val count = frozenFrameCount
         val duration = frozenFrameDurationMs
+        frozenFrameCount = 0
         frozenFrameDurationMs = 0.0
-        return duration
+        return FrozenFrameMetrics(count, duration)
+    }
+
+    @Synchronized
+    private fun recordFrozenFrame(durationMs: Double) {
+        frozenFrameCount += 1
+        frozenFrameDurationMs += durationMs
+        onFrozenFrame?.invoke(frozenFrameCount, durationMs)
     }
 
     /**
@@ -202,10 +211,7 @@ object FrameMonitor {
         // A slow frame "event" is a period of consecutive frames below target FPS
         // This groups consecutive slow frames to report meaningful jank, not microsecond variations
         val isSlow = fps < targetFps
-        if (isSlow) {
-            android.util.Log.d(TAG, "[Faro DEBUG ANDROID] 🐌 Slow frame detected: %.1f FPS (target: %.1f)".format(fps, targetFps))
-        }
-        
+
         if (isSlow) {
             if (!inSlowFrameEvent) {
                 // Start new slow frame event
@@ -216,18 +222,11 @@ object FrameMonitor {
             // Frame is good - check if we should end the current slow frame event
             if (inSlowFrameEvent) {
                 val eventDurationNs = frameTimeNanos - slowFrameEventStartTimeNanos
-                val eventDurationMs = eventDurationNs / NANOSECONDS_IN_MILLISECOND
-                val thresholdMs = slowFrameEventMinDurationNs / NANOSECONDS_IN_MILLISECOND
-                
+
                 // Only count as a slow frame event if it lasted long enough to be user-perceptible
                 // This filters out single-frame dips that don't affect user experience
                 if (eventDurationNs >= slowFrameEventMinDurationNs) {
-                    val newCount = slowFrameEventCount.incrementAndGet()
-                    // 🔍 TEMP DEBUG LOG - Remove after analysis
-                    android.util.Log.d(TAG, "[Faro DEBUG ANDROID] ✅ COUNTED as event (${eventDurationMs}ms)! Total events now: $newCount")
-                } else {
-                    // 🔍 TEMP DEBUG LOG - Remove after analysis
-                    android.util.Log.d(TAG, "[Faro DEBUG ANDROID] ❌ NOT counted (${eventDurationMs}ms is too short). Total events still: ${slowFrameEventCount.get()}")
+                    slowFrameEventCount.incrementAndGet()
                 }
                 
                 inSlowFrameEvent = false
@@ -237,15 +236,8 @@ object FrameMonitor {
 
         // Check for frozen frames (frame duration exceeds threshold)
         if (frameDuration > frozenFrameThresholdNs) {
-            val count = frozenFrameCount.incrementAndGet()
             val durationMs = frameDuration.toDouble() / NANOSECONDS_IN_MILLISECOND
-            
-            // Track duration (synchronized to avoid race conditions)
-            synchronized(this) {
-                frozenFrameDurationMs += durationMs
-            }
-            
-            onFrozenFrame?.invoke(count, durationMs)
+            recordFrozenFrame(durationMs)
         }
 
         lastFrameTimeNanos = frameTimeNanos

package/android/src/test/java/com/grafana/faro/reactnative/FaroCrashReporterBelowApi30Test.kt

@@ -0,0 +1,21 @@
+package com.grafana.faro.reactnative
+
+import android.content.Context
+import androidx.test.core.app.ApplicationProvider
+import org.junit.Assert.assertNull
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.annotation.Config
+
+@RunWith(RobolectricTestRunner::class)
+@Config(manifest = Config.NONE, sdk = [29])
+class FaroCrashReporterBelowApi30Test {
+
+    @Test
+    fun getCrashReports_isNoOpBeforeApi30() {
+        val context = ApplicationProvider.getApplicationContext<Context>()
+
+        assertNull(FaroCrashReporter.getCrashReports(context))
+    }
+}

package/android/src/test/java/com/grafana/faro/reactnative/FaroCrashReporterTest.kt

@@ -0,0 +1,59 @@
+package com.grafana.faro.reactnative
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertNotEquals
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+class FaroCrashReporterTest {
+
+    @Test
+    fun reportId_isStableForSameProcessCrash() {
+        val first = FaroCrashIds.reportId(
+            packageName = "com.example.app",
+            timestampMs = 1_000L,
+            pid = 101,
+            processName = "com.example.app",
+        )
+        val second = FaroCrashIds.reportId(
+            packageName = "com.example.app",
+            timestampMs = 1_000L,
+            pid = 101,
+            processName = "com.example.app",
+        )
+
+        assertEquals(first, second)
+        assertTrue(first.startsWith("v1:"))
+        assertEquals(67, first.length)
+    }
+
+    @Test
+    fun reportId_distinguishesProcessesAtSameTimestamp() {
+        val first = FaroCrashIds.reportId(
+            packageName = "com.example.app",
+            timestampMs = 1_000L,
+            pid = 101,
+            processName = "com.example.app",
+        )
+        val second = FaroCrashIds.reportId(
+            packageName = "com.example.app",
+            timestampMs = 1_000L,
+            pid = 202,
+            processName = "com.example.app:worker",
+        )
+
+        assertNotEquals(first, second)
+    }
+
+    @Test
+    fun replayWindow_includesExactSevenDayBoundary() {
+        val nowMs = 1_000_000_000L
+        val sevenDays = FaroCrashSessionStore.MAX_CONTEXT_AGE_MS
+
+        assertTrue(FaroCrashReporter.isWithinReplayWindow(nowMs - sevenDays, nowMs))
+        assertFalse(FaroCrashReporter.isWithinReplayWindow(nowMs - sevenDays - 1L, nowMs))
+        assertFalse(FaroCrashReporter.isWithinReplayWindow(0L, nowMs))
+        assertFalse(FaroCrashReporter.isWithinReplayWindow(nowMs + 1L, nowMs))
+    }
+}