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

package/ios/FaroCrashReporter.swift

@@ -0,0 +1,243 @@
+import CrashReporter
+import Foundation
+
+/// iOS Crash Reporter using PLCrashReporter.
+///
+/// This class handles:
+/// 1. Enabling PLCrashReporter to capture crashes
+/// 2. Loading and parsing crash reports from previous sessions
+/// 3. Converting crash data to JSON format compatible with Faro
+///
+/// ## Architecture
+/// PLCrashReporter captures crashes using signal handlers (BSD signals like SIGSEGV, SIGABRT)
+/// and Mach exception handlers. When a crash occurs, it writes a crash report to disk.
+/// On the next app launch, we load this report, convert it to JSON, and return it to
+/// JavaScript for sending to the Faro collector.
+///
+/// ## Usage
+/// This is called automatically by the CrashReportingInstrumentation in TypeScript.
+@objc(FaroCrashReporter)
+public class FaroCrashReporter: NSObject {
+
+    private static var crashReporter: PLCrashReporter?
+    private static var isEnabled = false
+
+    /// Signal descriptions for human-readable crash messages.
+    private static let signalDescriptions: [String: String] = [
+        "SIGHUP": "Hangup",
+        "SIGINT": "Interrupt",
+        "SIGQUIT": "Quit",
+        "SIGILL": "Illegal instruction",
+        "SIGTRAP": "Trace/BPT trap",
+        "SIGABRT": "Abort trap",
+        "SIGEMT": "EMT trap",
+        "SIGFPE": "Floating point exception",
+        "SIGKILL": "Killed",
+        "SIGBUS": "Bus error",
+        "SIGSEGV": "Segmentation fault",
+        "SIGSYS": "Bad system call",
+        "SIGPIPE": "Broken pipe",
+        "SIGALRM": "Alarm clock",
+        "SIGTERM": "Terminated"
+    ]
+
+    // MARK: - Public API
+
+    /// Enables crash reporting using PLCrashReporter.
+    ///
+    /// This should be called early in the app lifecycle. It sets up signal handlers
+    /// to capture crashes. Safe to call multiple times - will only enable once.
+    ///
+    /// - Returns: true if successfully enabled, false otherwise
+    @objc public static func enable() -> Bool {
+        guard !isEnabled else {
+            return true
+        }
+
+        guard let cacheDir = FileManager.default.urls(for: .cachesDirectory, in: .userDomainMask).first else {
+            print("[FaroCrashReporter] Cannot access cache directory")
+            return false
+        }
+
+        let crashDir = cacheDir.appendingPathComponent("com.grafana.faro.crash-reporting", isDirectory: true)
+
+        // Create crash directory if needed
+        try? FileManager.default.createDirectory(at: crashDir, withIntermediateDirectories: true)
+
+        // Configure PLCrashReporter
+        // Using BSD signal handler for broader compatibility
+        // Empty symbolication strategy - we'll handle that server-side
+        let config = PLCrashReporterConfig(
+            signalHandlerType: .BSD,
+            symbolicationStrategy: [],
+            basePath: crashDir.path
+        )
+
+        guard let reporter = PLCrashReporter(configuration: config) else {
+            print("[FaroCrashReporter] Could not create PLCrashReporter instance")
+            return false
+        }
+
+        do {
+            try reporter.enableAndReturnError()
+            crashReporter = reporter
+            isEnabled = true
+            print("[FaroCrashReporter] Successfully enabled crash reporting")
+            return true
+        } catch {
+            print("[FaroCrashReporter] Failed to enable: \(error)")
+            return false
+        }
+    }
+
+    /// Gets crash reports from previous sessions as JSON strings.
+    ///
+    /// Returns an array of JSON strings, each representing a crash report.
+    /// The JSON format matches the Android implementation for consistency.
+    /// After calling this method, pending crash reports are purged.
+    ///
+    /// - Returns: Array of crash report JSON strings, or nil if no crashes
+    @objc public static func getCrashReports() -> [String]? {
+        // Ensure crash reporter is enabled
+        guard enable() else {
+            return nil
+        }
+
+        guard let reporter = crashReporter else {
+            return nil
+        }
+
+        guard reporter.hasPendingCrashReport() else {
+            return nil
+        }
+
+        var crashReports: [String] = []
+
+        do {
+            let data = try reporter.loadPendingCrashReportDataAndReturnError()
+            let plcrReport = try PLCrashReport(data: data)
+            let crashReport = try FaroCrashReport(from: plcrReport)
+
+            // Convert to JSON matching Android format
+            if let jsonString = exportCrashReportAsJSON(crashReport) {
+                crashReports.append(jsonString)
+            }
+        } catch {
+            print("[FaroCrashReporter] Failed to load crash report: \(error)")
+        }
+
+        // Purge the crash report after loading
+        reporter.purgePendingCrashReport()
+
+        return crashReports.isEmpty ? nil : crashReports
+    }
+
+    // MARK: - Private Helpers
+
+    /// Converts a FaroCrashReport to JSON string matching the Android format.
+    private static func exportCrashReportAsJSON(_ crashReport: FaroCrashReport) -> String? {
+        var json: [String: Any] = [:]
+
+        // Reason - matches Android's "reason" field
+        // For iOS, we use the signal name as the reason
+        let signalName = crashReport.signalInfo?.name ?? "UNKNOWN"
+        json["reason"] = signalName
+
+        // Timestamp - Unix timestamp in milliseconds
+        if let timestamp = crashReport.systemInfo?.timestamp {
+            json["timestamp"] = Int64(timestamp.timeIntervalSince1970 * 1000)
+        }
+
+        // Status - iOS doesn't have exit status like Android, use signal code
+        json["status"] = 0
+
+        // Description - human-readable crash description
+        json["description"] = formattedDescription(for: crashReport)
+
+        // Process info
+        if let processInfo = crashReport.processInfo {
+            json["processName"] = processInfo.processName ?? ""
+            json["pid"] = processInfo.processID
+        }
+
+        // Signal info (iOS-specific)
+        if let signalInfo = crashReport.signalInfo {
+            json["signal"] = "\(signalInfo.name ?? "UNKNOWN") (\(signalInfo.code ?? ""))"
+        }
+
+        // Stack trace as a string (similar to Android's trace field)
+        let trace = formattedStackTrace(for: crashReport)
+        if !trace.isEmpty {
+            json["trace"] = trace
+        }
+
+        // Incident identifier
+        if let incidentId = crashReport.incidentIdentifier {
+            json["incidentId"] = incidentId
+        }
+
+        // Convert to JSON string
+        do {
+            let jsonData = try JSONSerialization.data(withJSONObject: json, options: [])
+            return String(data: jsonData, encoding: .utf8)
+        } catch {
+            print("[FaroCrashReporter] Failed to serialize crash report: \(error)")
+            return nil
+        }
+    }
+
+    /// Creates a human-readable description of the crash.
+    ///
+    /// This returns just the descriptive portion. The TypeScript layer formats the
+    /// final error message as "{reason}: {description}, status: {status}" to match
+    /// the Flutter SDK pattern.
+    private static func formattedDescription(for crashReport: FaroCrashReport) -> String {
+        // If there's an uncaught exception, include the exception details
+        if let exception = crashReport.exceptionInfo {
+            let name = exception.name ?? "Unknown"
+            let reason = exception.reason ?? "Unknown reason"
+            return "Uncaught exception '\(name)': \(reason)"
+        }
+
+        // Otherwise, provide a signal-based description
+        // The 'reason' field contains the signal name (e.g., SIGSEGV),
+        // so the description provides additional context
+        if let signalName = crashReport.signalInfo?.name,
+           let signalDescription = signalDescriptions[signalName] {
+            return signalDescription
+        }
+
+        return "Application crash"
+    }
+
+    /// Formats the stack trace as a string for the trace field.
+    private static func formattedStackTrace(for crashReport: FaroCrashReport) -> String {
+        // Get the most meaningful stack trace:
+        // 1. Exception stack trace (if available)
+        // 2. Crashed thread stack trace
+        // 3. First thread stack trace (fallback)
+        let stackFrames: [FaroStackFrame]?
+
+        if let exceptionFrames = crashReport.exceptionInfo?.stackFrames, !exceptionFrames.isEmpty {
+            stackFrames = exceptionFrames
+        } else if let crashedThread = crashReport.threads.first(where: { $0.crashed }) {
+            stackFrames = crashedThread.stackFrames
+        } else {
+            stackFrames = crashReport.threads.first?.stackFrames
+        }
+
+        guard let frames = stackFrames, !frames.isEmpty else {
+            return ""
+        }
+
+        // Format similar to iOS crash logs
+        var lines: [String] = []
+        for frame in frames.prefix(50) { // Limit to 50 frames
+            let library = frame.libraryName ?? "???"
+            let address = String(format: "0x%016llx", frame.instructionPointer)
+            lines.append("\(frame.number)  \(library)  \(address)")
+        }
+
+        return lines.joined(separator: "\n")
+    }
+}

package/ios/FaroReactNative.swift

@@ -0,0 +1,175 @@
+import Foundation
+
+/// Faro React Native iOS Native Module
+///
+/// Provides native iOS implementations for Real User Monitoring (RUM) metrics.
+/// This class is called from Objective-C bridge (`FaroReactNativeModule.mm`)
+/// which exports methods to JavaScript via React Native's native module system.
+///
+/// ## Metrics Provided
+/// - **App Startup Time**: Cold start duration using kernel process info
+/// - **Memory Usage**: Physical memory footprint via Mach task API
+/// - **CPU Usage**: Per-process CPU percentage via thread aggregation
+///
+/// ## Implementation Notes
+/// All methods use low-level iOS/Darwin APIs for accurate measurements:
+/// - `sysctl()` for process information
+/// - `task_info()` for memory and thread data
+///
+/// These implementations are aligned with Grafana Faro Flutter SDK patterns
+/// but include improvements where applicable (e.g., better memory metric).
+@objc(FaroReactNative)
+public class FaroReactNative: NSObject {
+
+    // MARK: - App Startup Time
+
+    /// Returns the app's cold start duration in milliseconds.
+    ///
+    /// Uses `sysctl()` to query the kernel for the actual process start time.
+    /// This approach requires no manual initialization in AppDelegate - the OS
+    /// tracks process creation time automatically.
+    ///
+    /// ## How It Works
+    /// 1. Queries kernel via `sysctl()` for `kinfo_proc.kp_proc.p_starttime`
+    /// 2. Gets current wall clock time via `gettimeofday()`
+    /// 3. Returns the difference in milliseconds
+    ///
+    /// ## RUM Best Practices
+    /// - ✅ Uses OS-level timing (most accurate)
+    /// - ✅ No manual instrumentation required
+    /// - ✅ Works for cold starts
+    /// - ⚠️ For warm starts, additional app lifecycle tracking is needed
+    ///
+    /// ## When to Call
+    /// Call this after the app's UI is interactive (e.g., after first render)
+    /// to measure Time-To-Interactive (TTI).
+    ///
+    /// - Returns: Duration from process start to now in milliseconds
+    @objc public static func getAppStartDuration() -> Double {
+        var kinfo = kinfo_proc()
+        var size = MemoryLayout<kinfo_proc>.stride
+        var mib: [Int32] = [CTL_KERN, KERN_PROC, KERN_PROC_PID, getpid()]
+
+        let result = sysctl(&mib, u_int(mib.count), &kinfo, &size, nil, 0)
+        guard result == 0 else {
+            return 0.0
+        }
+
+        let startTime = kinfo.kp_proc.p_starttime
+        var currentTime = timeval(tv_sec: 0, tv_usec: 0)
+        gettimeofday(&currentTime, nil)
+
+        let currentTimeMs = Double(Int64(currentTime.tv_sec) * 1000) + Double(currentTime.tv_usec) / 1000.0
+        let processStartMs = Double(Int64(startTime.tv_sec) * 1000) + Double(startTime.tv_usec) / 1000.0
+
+        return currentTimeMs - processStartMs
+    }
+
+    // MARK: - Memory Usage
+
+    /// Returns current memory usage in kilobytes.
+    ///
+    /// Uses `task_info()` with `TASK_VM_INFO` to get the process's physical
+    /// memory footprint. This is the recommended metric for iOS memory monitoring.
+    ///
+    /// ## Memory Metrics Explained
+    /// - **`phys_footprint`** (used here): Physical memory attributed to this app.
+    ///   This is what Apple recommends and what Xcode's Memory Gauge shows.
+    /// - **`resident_size`**: Physical pages currently in RAM (less accurate,
+    ///   can include shared memory counted multiple times).
+    ///
+    /// ## RUM Best Practices
+    /// - ✅ Uses `phys_footprint` (Apple-recommended metric)
+    /// - ✅ Matches Xcode Memory Gauge for easy correlation
+    /// - ✅ Suitable for periodic sampling (low overhead)
+    ///
+    /// ## Typical Values
+    /// - Small apps: 50-100 MB
+    /// - Medium apps: 100-300 MB
+    /// - Memory warnings start around 1GB+ on modern devices
+    ///
+    /// - Returns: Memory usage in KB, or 0.0 on error
+    @objc public static func getMemoryUsage() -> Double {
+        var vmInfo = task_vm_info_data_t()
+        var count = mach_msg_type_number_t(MemoryLayout<task_vm_info>.size / MemoryLayout<integer_t>.size)
+
+        let result = withUnsafeMutablePointer(to: &vmInfo) { vmInfoPtr in
+            vmInfoPtr.withMemoryRebound(to: integer_t.self, capacity: Int(count)) { ptr in
+                task_info(mach_task_self_, task_flavor_t(TASK_VM_INFO), ptr, &count)
+            }
+        }
+
+        guard result == KERN_SUCCESS else {
+            return 0.0
+        }
+
+        // phys_footprint is in bytes, convert to KB
+        // This is the recommended iOS memory metric (matches Xcode Memory Gauge)
+        let memoryBytes = Double(vmInfo.phys_footprint)
+        return memoryBytes / 1024.0
+    }
+
+    // MARK: - CPU Usage
+
+    /// Returns current CPU usage as a percentage (0-100+).
+    ///
+    /// Uses differential calculation - first call establishes a baseline and
+    /// returns 0.0, subsequent calls return the actual CPU usage percentage.
+    ///
+    /// ## How It Works
+    /// Delegates to `CPUInfo.getCpuInfo()` which:
+    /// 1. Enumerates all threads via `task_threads()`
+    /// 2. Sums CPU time (user + system) across all threads
+    /// 3. Calculates percentage: `(cpuTimeDelta / wallTimeDelta) * 100`
+    ///
+    /// ## RUM Best Practices
+    /// - ✅ Per-process CPU (not system-wide)
+    /// - ✅ Per-thread aggregation (accurate on multi-core)
+    /// - ✅ Differential calculation (measures actual usage between calls)
+    /// - ✅ Low overhead (suitable for periodic sampling)
+    ///
+    /// ## Return Values
+    /// - `0.0`: First call (baseline) or very low CPU usage
+    /// - `0-100`: Normal CPU usage percentage
+    /// - `>100`: Possible on multi-core (e.g., 200% = 2 cores fully utilized)
+    /// - `-1.0`: Error occurred
+    ///
+    /// ## Sampling Recommendations
+    /// - Sample every 1-5 seconds for general monitoring
+    /// - Sample more frequently during performance investigations
+    /// - First call after app start returns 0 (baseline), ignore this value
+    ///
+    /// - Returns: CPU usage percentage, or -1.0 on error
+    @objc public static func getCpuUsage() -> Double {
+        return CPUInfo.getCpuInfo()
+    }
+
+    // MARK: - Crash Reporting
+
+    /// Enables crash reporting using PLCrashReporter.
+    ///
+    /// This sets up signal handlers to capture crashes (SIGSEGV, SIGABRT, etc.)
+    /// and Mach exceptions. Should be called early in the app lifecycle.
+    ///
+    /// - Returns: true if successfully enabled, false otherwise
+    @objc public static func enableCrashReporting() -> Bool {
+        return FaroCrashReporter.enable()
+    }
+
+    /// Gets crash reports from previous sessions as JSON strings.
+    ///
+    /// Returns an array of JSON strings, each representing a crash report.
+    /// The JSON format matches the Android implementation for consistency:
+    /// - `reason`: Signal name (e.g., "SIGSEGV", "SIGABRT")
+    /// - `timestamp`: Unix timestamp in milliseconds
+    /// - `description`: Human-readable crash description
+    /// - `trace`: Stack trace as string
+    /// - `signal`: Signal info (iOS-specific)
+    ///
+    /// After calling this method, pending crash reports are purged.
+    ///
+    /// - Returns: Array of crash report JSON strings, or nil if no crashes
+    @objc public static func getCrashReports() -> [String]? {
+        return FaroCrashReporter.getCrashReports()
+    }
+}

package/ios/FaroReactNativeModule.h

@@ -0,0 +1,4 @@
+#import <React/RCTBridgeModule.h>
+
+@interface FaroReactNativeModule : NSObject <RCTBridgeModule>
+@end

package/ios/FaroReactNativeModule.mm

@@ -0,0 +1,124 @@
+#import "FaroReactNativeModule.h"
+#import <React/RCTBridgeModule.h>
+#import "FaroReactNative-Swift.h"
+
+@implementation FaroReactNativeModule
+
+RCT_EXPORT_MODULE(FaroReactNativeModule)
+
+/// Synchronous method for immediate access from JavaScript
+/// Returns app startup duration in milliseconds from process start to current time
+RCT_EXPORT_BLOCKING_SYNCHRONOUS_METHOD(getAppStartDuration)
+{
+  return @([FaroReactNative getAppStartDuration]);
+}
+
+/// Synchronous method for immediate access from JavaScript
+/// Returns current memory usage in kilobytes (RSS)
+RCT_EXPORT_BLOCKING_SYNCHRONOUS_METHOD(getMemoryUsage)
+{
+  return @([FaroReactNative getMemoryUsage]);
+}
+
+/// Synchronous method for immediate access from JavaScript
+/// Returns current CPU usage percentage (0-100+), or -1 on error
+/// First call returns 0 (baseline), subsequent calls return actual usage
+RCT_EXPORT_BLOCKING_SYNCHRONOUS_METHOD(getCpuUsage)
+{
+  double cpuUsage = [FaroReactNative getCpuUsage];
+  // Return null for error case (-1.0) to match JavaScript expectations
+  return cpuUsage < 0 ? [NSNull null] : @(cpuUsage);
+}
+
+/// Start frame monitoring with configuration
+/// @param config Dictionary with targetFps, frozenFrameThresholdMs, normalizedRefreshRate
+RCT_EXPORT_METHOD(startFrameMonitoring:(NSDictionary *)config)
+{
+  double targetFps = [[config objectForKey:@"targetFps"] doubleValue] ?: 60.0;
+  double frozenFrameThresholdMs = [[config objectForKey:@"frozenFrameThresholdMs"] doubleValue] ?: 100.0;
+  double normalizedRefreshRate = [[config objectForKey:@"normalizedRefreshRate"] doubleValue] ?: 60.0;
+  
+  dispatch_async(dispatch_get_main_queue(), ^{
+    [[RefreshRateVitals shared] configureWithTargetFps:targetFps
+                               frozenFrameThresholdMs:frozenFrameThresholdMs
+                               normalizedRefreshRate:normalizedRefreshRate];
+    [[RefreshRateVitals shared] start];
+  });
+}
+
+/// Stop frame monitoring
+RCT_EXPORT_METHOD(stopFrameMonitoring)
+{
+  dispatch_async(dispatch_get_main_queue(), ^{
+    [[RefreshRateVitals shared] stop];
+  });
+}
+
+/// Get current refresh rate
+/// @param resolve Promise resolve callback
+/// @param reject Promise reject callback
+RCT_EXPORT_METHOD(getRefreshRate:(RCTPromiseResolveBlock)resolve
+                  reject:(RCTPromiseRejectBlock)reject)
+{
+  dispatch_async(dispatch_get_main_queue(), ^{
+    double refreshRate = [[RefreshRateVitals shared] getRefreshRate];
+    if (refreshRate > 0) {
+      resolve(@(refreshRate));
+    } else {
+      resolve([NSNull null]);
+    }
+  });
+}
+
+/// Get frame metrics (refresh rate, slow frame events, frozen frames, frozen duration)
+/// Note: slowFrames contains the count of slow frame EVENTS (not individual frames)
+/// @param resolve Promise resolve callback
+/// @param reject Promise reject callback
+RCT_EXPORT_METHOD(getFrameMetrics:(RCTPromiseResolveBlock)resolve
+                  reject:(RCTPromiseRejectBlock)reject)
+{
+  dispatch_async(dispatch_get_main_queue(), ^{
+    RefreshRateVitals *vitals = [RefreshRateVitals shared];
+    
+    NSDictionary *metrics = @{
+      @"refreshRate": @([vitals getRefreshRate]),
+      @"slowFrames": @([vitals getAndResetSlowFrames]),
+      @"frozenFrames": @([vitals getAndResetFrozenFrames]),
+      @"frozenDurationMs": @([vitals getAndResetFrozenDuration])
+    };
+    
+    resolve(metrics);
+  });
+}
+
+// MARK: - Crash Reporting
+
+/// Enable crash reporting using PLCrashReporter.
+/// Sets up signal handlers to capture crashes (SIGSEGV, SIGABRT, etc.).
+/// Should be called early in the app lifecycle.
+/// @param resolve Promise resolve callback
+/// @param reject Promise reject callback
+RCT_EXPORT_METHOD(enableCrashReporting:(RCTPromiseResolveBlock)resolve
+                  reject:(RCTPromiseRejectBlock)reject)
+{
+  BOOL success = [FaroReactNative enableCrashReporting];
+  resolve(@(success));
+}
+
+/// Get crash reports from previous app sessions.
+/// Uses PLCrashReporter to capture signal crashes and Mach exceptions.
+/// Returns an array of JSON strings matching the Android format.
+/// @param resolve Promise resolve callback
+/// @param reject Promise reject callback
+RCT_EXPORT_METHOD(getCrashReport:(RCTPromiseResolveBlock)resolve
+                  reject:(RCTPromiseRejectBlock)reject)
+{
+  NSArray<NSString *> *crashReports = [FaroReactNative getCrashReports];
+  if (crashReports != nil && crashReports.count > 0) {
+    resolve(crashReports);
+  } else {
+    resolve([NSNull null]);
+  }
+}
+
+@end