@grafana/faro-react-native 1.0.0-alpha.1

package/dist/types/userPersistence/UserPersistence.d.ts

@@ -0,0 +1,65 @@
+import type { MetaUser } from '@grafana/faro-core';
+import type { UserPersistence, UserPersistenceOptions } from './types';
+/**
+ * UserPersistence implementation using AsyncStorage.
+ *
+ * Stores user information persistently so it can be restored on app restart.
+ * This ensures early telemetry events include user identification.
+ *
+ * Implementation follows Flutter SDK's UserPersistence pattern:
+ * - Uses AsyncStorage for persistence (matching Flutter's SharedPreferences)
+ * - Stores user as JSON
+ * - Handles null/cleared users
+ *
+ * @example
+ * ```typescript
+ * import { createUserPersistence } from '@grafana/faro-react-native';
+ *
+ * // Load user on app start
+ * const persistence = createUserPersistence();
+ * const user = await persistence.loadUser();
+ *
+ * if (user) {
+ *   faro.api.setUser(user);
+ * }
+ *
+ * // Save user when logged in
+ * const loggedInUser = { id: '123', email: 'user@example.com' };
+ * await persistence.saveUser(loggedInUser);
+ *
+ * // Clear on logout
+ * await persistence.clearUser();
+ * ```
+ */
+export declare class AsyncStorageUserPersistence implements UserPersistence {
+    private readonly storageKey;
+    constructor(options?: UserPersistenceOptions);
+    loadUser(): Promise<MetaUser | null>;
+    saveUser(user: MetaUser | null): Promise<void>;
+    clearUser(): Promise<void>;
+    hasPersistedUser(): Promise<boolean>;
+    /**
+     * Check if user is cleared (all fields empty/undefined).
+     */
+    private isCleared;
+    /**
+     * Validate that the parsed object is a valid MetaUser.
+     */
+    private isValidMetaUser;
+}
+/**
+ * Factory function to create a UserPersistence instance.
+ */
+export declare function createUserPersistence(options?: UserPersistenceOptions): UserPersistence;
+/**
+ * Initialize the global user persistence.
+ */
+export declare function initializeUserPersistence(options?: UserPersistenceOptions): UserPersistence;
+/**
+ * Get the global user persistence instance.
+ */
+export declare function getUserPersistence(): UserPersistence | null;
+/**
+ * Set a custom user persistence instance.
+ */
+export declare function setUserPersistence(persistence: UserPersistence | null): void;

package/dist/types/userPersistence/index.d.ts

@@ -0,0 +1,2 @@
+export { AsyncStorageUserPersistence, createUserPersistence, getUserPersistence, initializeUserPersistence, setUserPersistence, } from './UserPersistence';
+export type { UserPersistence, UserPersistenceOptions } from './types';

package/dist/types/userPersistence/types.d.ts

@@ -0,0 +1,36 @@
+import type { MetaUser } from '@grafana/faro-core';
+/**
+ * Interface for user data persistence.
+ *
+ * Handles saving and loading user data between app sessions.
+ */
+export interface UserPersistence {
+    /**
+     * Load the persisted user from storage.
+     * Returns null if no user has been persisted.
+     */
+    loadUser(): Promise<MetaUser | null>;
+    /**
+     * Save the user to storage.
+     * If user is null or cleared, any previously persisted user data is cleared.
+     */
+    saveUser(user: MetaUser | null): Promise<void>;
+    /**
+     * Clear any persisted user data.
+     */
+    clearUser(): Promise<void>;
+    /**
+     * Check if there is persisted user data.
+     */
+    hasPersistedUser(): Promise<boolean>;
+}
+/**
+ * Options for creating a UserPersistence instance.
+ */
+export interface UserPersistenceOptions {
+    /**
+     * Storage key for persisting user data.
+     * Default: 'faro_persisted_user'
+     */
+    storageKey?: string;
+}

package/dist/types/util/performanceObserverPolyfill.d.ts

@@ -0,0 +1,19 @@
+/**
+ * PerformanceObserver polyfill for React Native iOS
+ *
+ * React Native 0.84's native PerformanceObserver has a bug on iOS that throws
+ * `bad_variant_access` when the observer callback runs and calls getEntries().
+ * This happens in NativePerformance.createObserver when the native bridge
+ * returns data that causes a C++ variant access error.
+ *
+ * OpenTelemetry's FetchInstrumentation (and other libs) may use PerformanceObserver
+ * for resource timing. We provide a no-op polyfill on React Native iOS to prevent
+ * the crash while preserving refresh rate vitals and other functionality.
+ *
+ * @see https://github.com/facebook/react-native/issues (PerformanceObserver iOS)
+ */
+/**
+ * Apply polyfill on React Native iOS to prevent bad_variant_access crash.
+ * Must run before any code that might use PerformanceObserver.
+ */
+export declare function applyPerformanceObserverPolyfill(): void;

package/dist/types/utils/throttle.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Creates a throttled function that only invokes the provided function at most once per
+ * every `wait` milliseconds.
+ *
+ * @param func - The function to throttle
+ * @param wait - The number of milliseconds to throttle invocations to
+ * @returns A throttled version of the function
+ */
+export declare function throttle<T extends (...args: any[]) => any>(func: T, wait: number): T;

package/ios/CPUInfo.swift

@@ -0,0 +1,111 @@
+import Darwin
+import Foundation
+
+/// CPU usage monitoring for iOS
+///
+/// Uses task_info() to track per-process CPU usage via differential calculation.
+/// First call establishes baseline and returns 0.0. Subsequent calls return CPU usage percentage.
+///
+/// This implementation fixes the bug in the Flutter SDK which uses system-wide CPU time
+/// instead of per-process CPU time, causing incorrect percentages on multi-core devices.
+@objc(CPUInfo)
+public class CPUInfo: NSObject {
+
+    /// Serializes reads/writes of differential baseline state when `getCpuInfo()` is invoked concurrently.
+    private static let stateLock = NSLock()
+
+    // Static state for differential calculation
+    private static var lastCpuTime: Double = 0.0
+    private static var lastWallTime: Double = 0.0
+
+    /// Gets current CPU usage percentage using differential calculation
+    ///
+    /// Returns CPU usage as a percentage (0-100). First call returns 0.0 to establish baseline.
+    ///
+    /// - Returns: CPU usage percentage, or -1.0 on error
+    @objc public static func getCpuInfo() -> Double {
+        stateLock.lock()
+        defer { stateLock.unlock() }
+
+        guard let cpuTime = getProcessCpuTime(),
+              let wallTime = getWallTime() else {
+            return -1.0
+        }
+
+        // First call - establish baseline
+        if lastCpuTime == 0.0 {
+            lastCpuTime = cpuTime
+            lastWallTime = wallTime
+            return 0.0
+        }
+
+        // Calculate differential CPU usage
+        let cpuTimeDiff = cpuTime - lastCpuTime
+        let wallTimeDiff = wallTime - lastWallTime
+
+        // Avoid division by zero
+        guard wallTimeDiff > 0 else {
+            return -1.0
+        }
+
+        // CPU usage percentage (0-100)
+        let cpuUsagePercent = 100.0 * (cpuTimeDiff / wallTimeDiff)
+
+        // Store current values for next call
+        lastCpuTime = cpuTime
+        lastWallTime = wallTime
+
+        return cpuUsagePercent
+    }
+
+    /// Gets per-process CPU time using task_info()
+    ///
+    /// - Returns: Total process CPU time in seconds (user + system), or nil on error
+    private static func getProcessCpuTime() -> Double? {
+        var threadsList: thread_act_array_t?
+        var threadsCount = mach_msg_type_number_t(0)
+
+        let result = task_threads(mach_task_self_, &threadsList, &threadsCount)
+        guard result == KERN_SUCCESS, let threads = threadsList else {
+            return nil
+        }
+
+        defer {
+            vm_deallocate(mach_task_self_, vm_address_t(bitPattern: threads), vm_size_t(Int(threadsCount) * MemoryLayout<thread_t>.stride))
+        }
+
+        var totalCpuTime: Double = 0.0
+
+        for i in 0..<Int(threadsCount) {
+            var threadInfo = thread_basic_info()
+            var threadInfoCount = mach_msg_type_number_t(THREAD_INFO_MAX)
+
+            let infoResult = withUnsafeMutablePointer(to: &threadInfo) {
+                $0.withMemoryRebound(to: integer_t.self, capacity: 1) {
+                    thread_info(threads[i], thread_flavor_t(THREAD_BASIC_INFO), $0, &threadInfoCount)
+                }
+            }
+
+            guard infoResult == KERN_SUCCESS else {
+                continue
+            }
+
+            // Convert thread CPU time to seconds
+            let userTime = Double(threadInfo.user_time.seconds) + Double(threadInfo.user_time.microseconds) / 1_000_000.0
+            let systemTime = Double(threadInfo.system_time.seconds) + Double(threadInfo.system_time.microseconds) / 1_000_000.0
+
+            totalCpuTime += userTime + systemTime
+        }
+
+        return totalCpuTime
+    }
+
+    /// Gets current wall clock time
+    ///
+    /// - Returns: Current time in seconds since epoch, or nil on error
+    private static func getWallTime() -> Double? {
+        var currentTime = timeval(tv_sec: 0, tv_usec: 0)
+        gettimeofday(&currentTime, nil)
+        return Double(currentTime.tv_sec) + Double(currentTime.tv_usec) / 1_000_000.0
+    }
+}

package/ios/FaroCrashReport.swift

@@ -0,0 +1,319 @@
+import CrashReporter
+import Foundation
+
+/// Intermediate representation of a crash report from PLCrashReporter.
+///
+/// This struct provides a simplified, serializable model of crash data that can be
+/// converted to JSON and sent to the Faro collector. The design follows the Flutter
+/// SDK's pattern for consistency across mobile platforms.
+///
+/// ## Data Flow
+/// ```
+/// PLCrashReport (PLCrashReporter) → FaroCrashReport (this struct) → JSON → Faro Collector
+/// ```
+internal struct FaroCrashReport {
+    /// A client-generated 16-byte UUID of the incident.
+    var incidentIdentifier: String?
+    /// System information from the moment of crash.
+    var systemInfo: FaroSystemInfo?
+    /// Information about the process that crashed.
+    var processInfo: FaroCrashedProcessInfo?
+    /// Information about the fatal signal.
+    var signalInfo: FaroSignalInfo?
+    /// Uncaught exception information. Only available if a crash was caused by an uncaught exception.
+    var exceptionInfo: FaroExceptionInfo?
+    /// Information about all threads running at the moment of crash.
+    var threads: [FaroThreadInfo]
+    /// Information about binary images loaded by the process.
+    var binaryImages: [FaroBinaryImageInfo]
+    /// Custom user data injected before the crash occurred.
+    var contextData: Data?
+    /// Flag indicating if any stack traces were truncated due to size limits.
+    var wasTruncated: Bool
+}
+
+/// System information at the time of crash.
+internal struct FaroSystemInfo {
+    /// Date and time when the crash report was generated.
+    var timestamp: Date?
+}
+
+/// Information about the crashed process.
+internal struct FaroCrashedProcessInfo {
+    /// The name of the process.
+    var processName: String?
+    /// The process ID.
+    var processID: UInt
+    /// The path to the process executable.
+    var processPath: String?
+    /// The parent process ID.
+    var parentProcessID: UInt
+    /// The parent process name.
+    var parentProcessName: String?
+}
+
+/// Information about the fatal signal that caused the crash.
+internal struct FaroSignalInfo {
+    /// The name of the BSD termination signal, e.g., `SIGTRAP`, `SIGSEGV`.
+    var name: String?
+    /// Termination signal code, e.g., `#0`.
+    var code: String?
+    /// The faulting instruction address.
+    var address: UInt64
+}
+
+/// Information about an uncaught exception (if the crash was caused by one).
+internal struct FaroExceptionInfo {
+    /// The exception name, e.g., `NSInternalInconsistencyException`.
+    var name: String?
+    /// The exception reason, e.g., `unable to dequeue a cell with identifier foo`.
+    var reason: String?
+    /// The stack trace of this exception.
+    var stackFrames: [FaroStackFrame]
+}
+
+/// Information about a thread at the time of crash.
+internal struct FaroThreadInfo {
+    /// Application thread number.
+    var threadNumber: Int
+    /// Whether this thread crashed.
+    var crashed: Bool
+    /// The stack trace of this thread.
+    var stackFrames: [FaroStackFrame]
+}
+
+/// Information about a binary image loaded by the process.
+internal struct FaroBinaryImageInfo {
+    internal struct CodeType {
+        /// The name of CPU architecture, e.g., `arm64`, `x86_64`.
+        var architectureName: String?
+    }
+
+    /// The UUID of this image.
+    var uuid: String?
+    /// The name of this image.
+    var imageName: String
+    /// Whether this is a system library image.
+    var isSystemImage: Bool
+    /// Image code type (architecture information).
+    var codeType: CodeType?
+    /// The load address of this image.
+    var imageBaseAddress: UInt64
+    /// The size of this image segment.
+    var imageSize: UInt64
+}
+
+/// A single frame in a stack trace.
+internal struct FaroStackFrame: Codable {
+    /// The number of this frame in the stack trace.
+    var number: Int
+    /// The name of the library that produced this frame.
+    var libraryName: String?
+    /// The load address of the library that produced this frame.
+    var libraryBaseAddress: UInt64?
+    /// The instruction pointer of this frame.
+    var instructionPointer: UInt64
+
+    /// Converts to a dictionary suitable for JSON serialization.
+    var jsonRepresentation: [String: Any] {
+        return [
+            "lineno": number,
+            "colno": 0,
+            "filename": libraryName ?? "",
+            "function": "\(libraryBaseAddress ?? 0) \(instructionPointer)"
+        ]
+    }
+}
+
+// MARK: - FaroCrashReport Exception
+
+internal struct FaroCrashReportException: Error {
+    let description: String
+}
+
+// MARK: - PLCrashReporter Extensions
+
+extension FaroCrashReport {
+    /// Creates a FaroCrashReport from a PLCrashReport.
+    init(from plcr: PLCrashReport) throws {
+        guard let threads = plcr.threads,
+              let images = plcr.images else {
+            throw FaroCrashReportException(
+                description: "Received inconsistent PLCrashReport: threads=\(plcr.threads != nil), images=\(plcr.images != nil)"
+            )
+        }
+
+        if let uuid = plcr.uuidRef, let uuidString = CFUUIDCreateString(nil, uuid) {
+            self.incidentIdentifier = uuidString as String
+        } else {
+            self.incidentIdentifier = nil
+        }
+
+        self.systemInfo = FaroSystemInfo(from: plcr)
+        self.processInfo = FaroCrashedProcessInfo(from: plcr)
+        self.signalInfo = FaroSignalInfo(from: plcr)
+        self.exceptionInfo = FaroExceptionInfo(from: plcr)
+
+        self.threads = threads
+            .compactMap { $0 as? PLCrashReportThreadInfo }
+            .map { FaroThreadInfo(from: $0, in: plcr) }
+
+        self.binaryImages = images
+            .compactMap { $0 as? PLCrashReportBinaryImageInfo }
+            .compactMap { FaroBinaryImageInfo(from: $0) }
+
+        self.contextData = plcr.customData
+        self.wasTruncated = false
+    }
+}
+
+extension FaroSystemInfo {
+    init?(from plcr: PLCrashReport) {
+        guard let systemInfo = plcr.systemInfo else {
+            return nil
+        }
+        self.timestamp = systemInfo.timestamp
+    }
+}
+
+extension FaroCrashedProcessInfo {
+    init?(from plcr: PLCrashReport) {
+        guard plcr.hasProcessInfo, let processInfo = plcr.processInfo else {
+            return nil
+        }
+        self.processName = processInfo.processName
+        self.processID = processInfo.processID
+        self.processPath = processInfo.processPath
+        self.parentProcessID = processInfo.parentProcessID
+        self.parentProcessName = processInfo.parentProcessName
+    }
+}
+
+extension FaroSignalInfo {
+    init?(from plcr: PLCrashReport) {
+        guard let signalInfo = plcr.signalInfo else {
+            return nil
+        }
+        self.name = signalInfo.name
+        self.code = signalInfo.code
+        self.address = signalInfo.address
+    }
+}
+
+extension FaroExceptionInfo {
+    init?(from plcr: PLCrashReport) {
+        guard plcr.hasExceptionInfo, let exceptionInfo = plcr.exceptionInfo else {
+            return nil
+        }
+        self.name = exceptionInfo.exceptionName
+        self.reason = exceptionInfo.exceptionReason
+
+        if let stackFrames = exceptionInfo.stackFrames {
+            self.stackFrames = stackFrames
+                .compactMap { $0 as? PLCrashReportStackFrameInfo }
+                .enumerated()
+                .map { number, frame in FaroStackFrame(from: frame, number: number, in: plcr) }
+        } else {
+            self.stackFrames = []
+        }
+    }
+}
+
+extension FaroThreadInfo {
+    init(from threadInfo: PLCrashReportThreadInfo, in crashReport: PLCrashReport) {
+        self.threadNumber = threadInfo.threadNumber
+        self.crashed = threadInfo.crashed
+
+        if let stackFrames = threadInfo.stackFrames {
+            self.stackFrames = stackFrames
+                .compactMap { $0 as? PLCrashReportStackFrameInfo }
+                .enumerated()
+                .map { number, frame in FaroStackFrame(from: frame, number: number, in: crashReport) }
+        } else {
+            self.stackFrames = []
+        }
+    }
+}
+
+extension FaroBinaryImageInfo {
+    init?(from imageInfo: PLCrashReportBinaryImageInfo) {
+        guard let imagePath = imageInfo.imageName else {
+            return nil
+        }
+
+        self.uuid = imageInfo.imageUUID
+        self.imageName = URL(fileURLWithPath: imagePath).lastPathComponent
+
+        #if targetEnvironment(simulator)
+        self.isSystemImage = Self.isPathSystemImageInSimulator(imagePath)
+        #else
+        self.isSystemImage = Self.isPathSystemImageInDevice(imagePath)
+        #endif
+
+        if let codeType = imageInfo.codeType {
+            self.codeType = CodeType(from: codeType)
+        } else {
+            self.codeType = nil
+        }
+
+        self.imageBaseAddress = imageInfo.imageBaseAddress
+        self.imageSize = imageInfo.imageSize
+    }
+
+    static func isPathSystemImageInSimulator(_ path: String) -> Bool {
+        return path.contains("/Contents/Developer/Platforms/")
+    }
+
+    static func isPathSystemImageInDevice(_ path: String) -> Bool {
+        let isUserImage = path.contains("/Bundle/Application/")
+        return !isUserImage
+    }
+}
+
+extension FaroBinaryImageInfo.CodeType {
+    init?(from processorInfo: PLCrashReportProcessorInfo) {
+        guard processorInfo.typeEncoding == PLCrashReportProcessorTypeEncodingMach else {
+            return nil
+        }
+
+        let type = processorInfo.type
+        let subtype = processorInfo.subtype
+        let subtypeMask = UInt64(CPU_SUBTYPE_MASK)
+
+        switch type {
+        case UInt64(CPU_TYPE_X86):
+            self.architectureName = "i386"
+        case UInt64(CPU_TYPE_X86_64):
+            self.architectureName = "x86_64"
+        case UInt64(CPU_TYPE_ARM):
+            self.architectureName = "arm"
+        case UInt64(CPU_TYPE_ARM64):
+            switch subtype & ~subtypeMask {
+            case UInt64(CPU_SUBTYPE_ARM64_ALL):
+                self.architectureName = "arm64"
+            case UInt64(CPU_SUBTYPE_ARM64_V8):
+                self.architectureName = "armv8"
+            case UInt64(CPU_SUBTYPE_ARM64E):
+                self.architectureName = "arm64e"
+            default:
+                self.architectureName = "arm64-unknown"
+            }
+        default:
+            self.architectureName = nil
+        }
+    }
+}
+
+extension FaroStackFrame {
+    init(from stackFrame: PLCrashReportStackFrameInfo, number: Int, in crashReport: PLCrashReport) {
+        self.number = number
+        self.instructionPointer = stackFrame.instructionPointer
+
+        let image = crashReport.image(forAddress: stackFrame.instructionPointer)
+        self.libraryBaseAddress = image?.imageBaseAddress
+
+        if let imagePath = image?.imageName {
+            self.libraryName = URL(fileURLWithPath: imagePath).lastPathComponent
+        }
+    }
+}