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

package/dist/esm/instrumentations/errors/stackTraceParser.js

@@ -0,0 +1,153 @@
+import { Platform } from 'react-native';
+/**
+ * Parse React Native stack traces into structured stack frames
+ *
+ * React Native stack traces have different formats depending on platform and environment:
+ *
+ * iOS/Android (Dev):
+ *   at functionName (file.js:123:45)
+ *   at anonymous (native)
+ *
+ * iOS/Android (Release):
+ *   functionName@123:456
+ *   @[native code]
+ *
+ * Metro bundler:
+ *   at Object.functionName (/path/to/file.js:123:456)
+ */
+const REACT_NATIVE_STACK_REGEX = /^\s*at\s+(.+?)\s+\((.+?):(\d+):(\d+)\)$/;
+const REACT_NATIVE_NATIVE_REGEX = /^\s*at\s+(.+?)\s+\(native\)$/;
+const REACT_NATIVE_RELEASE_REGEX = /^(.+?)@(\d+):(\d+)$/;
+const REACT_NATIVE_ANONYMOUS_REGEX = /^\s*at\s+anonymous\s+\((.+?):(\d+):(\d+)\)$/;
+const METRO_BUNDLER_REGEX = /^\s*at\s+(?:Object\.)?(.+?)\s+\((.+?):(\d+):(\d+)\)$/;
+/**
+ * Parse a single stack trace line into a structured frame
+ */
+export function parseStackTraceLine(line) {
+    if (!line || typeof line !== 'string') {
+        return null;
+    }
+    const trimmedLine = line.trim();
+    if (!trimmedLine) {
+        return null;
+    }
+    // Try standard React Native format: at functionName (file.js:123:45)
+    let match = trimmedLine.match(REACT_NATIVE_STACK_REGEX);
+    if (match && match[2] && match[3] && match[4]) {
+        return {
+            function: match[1] || '<anonymous>',
+            filename: match[2],
+            lineno: parseInt(match[3], 10),
+            colno: parseInt(match[4], 10),
+        };
+    }
+    // Try Metro bundler format: at Object.functionName (/path/to/file.js:123:456)
+    match = trimmedLine.match(METRO_BUNDLER_REGEX);
+    if (match && match[2] && match[3] && match[4]) {
+        return {
+            function: match[1] || '<anonymous>',
+            filename: match[2],
+            lineno: parseInt(match[3], 10),
+            colno: parseInt(match[4], 10),
+        };
+    }
+    // Try anonymous format: at anonymous (file.js:123:45)
+    match = trimmedLine.match(REACT_NATIVE_ANONYMOUS_REGEX);
+    if (match && match[1] && match[2] && match[3]) {
+        return {
+            function: '<anonymous>',
+            filename: match[1],
+            lineno: parseInt(match[2], 10),
+            colno: parseInt(match[3], 10),
+        };
+    }
+    // Try native format: at functionName (native)
+    match = trimmedLine.match(REACT_NATIVE_NATIVE_REGEX);
+    if (match) {
+        return {
+            function: match[1] || '<native>',
+            filename: '<native>',
+            isNative: true,
+        };
+    }
+    // Try release/minified format: functionName@123:456
+    match = trimmedLine.match(REACT_NATIVE_RELEASE_REGEX);
+    if (match && match[2] && match[3]) {
+        return {
+            function: match[1] || '<anonymous>',
+            filename: '<unknown>',
+            lineno: parseInt(match[2], 10),
+            colno: parseInt(match[3], 10),
+        };
+    }
+    // Couldn't parse this line
+    return null;
+}
+/**
+ * Parse a full stack trace string into an array of structured frames
+ */
+export function parseStackTrace(stackTrace) {
+    if (!stackTrace || typeof stackTrace !== 'string') {
+        return [];
+    }
+    const lines = stackTrace.split('\n');
+    const frames = [];
+    for (const line of lines) {
+        const frame = parseStackTraceLine(line);
+        if (frame) {
+            frames.push(frame);
+        }
+    }
+    return frames;
+}
+/**
+ * Convert parsed stack frames to Faro's StackFrame format
+ */
+export function toFaroStackFrames(parsedFrames) {
+    return parsedFrames.map((frame, _index) => ({
+        filename: frame.filename || '<unknown>',
+        function: frame.function || '<anonymous>',
+        lineno: frame.lineno,
+        colno: frame.colno,
+    }));
+}
+/**
+ * Extract and parse stack frames from an Error object
+ */
+export function getStackFramesFromError(error) {
+    if (!error || !error.stack) {
+        return [];
+    }
+    try {
+        const parsedFrames = parseStackTrace(error.stack);
+        return toFaroStackFrames(parsedFrames);
+    }
+    catch (_e) {
+        // If parsing fails, return empty array
+        return [];
+    }
+}
+/**
+ * Get platform-specific error context
+ */
+export function getPlatformErrorContext() {
+    var _a;
+    return {
+        platform: Platform.OS,
+        platformVersion: ((_a = Platform.Version) === null || _a === void 0 ? void 0 : _a.toString()) || 'unknown',
+        isHermes: typeof HermesInternal !== 'undefined' ? 'true' : 'false',
+    };
+}
+/**
+ * Enhance error with React Native specific information
+ */
+export function enhanceErrorWithContext(error, additionalContext) {
+    const stackFrames = getStackFramesFromError(error);
+    const platformContext = getPlatformErrorContext();
+    return {
+        error,
+        stackFrames,
+        context: Object.assign(Object.assign({}, platformContext), additionalContext),
+    };
+}
+//# sourceMappingURL=stackTraceParser.js.map

package/dist/esm/instrumentations/errors/stackTraceParser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stackTraceParser.js","sourceRoot":"","sources":["../../../../src/instrumentations/errors/stackTraceParser.ts"],"names":[],"mappings":"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","sourcesContent":["import { Platform } from 'react-native';\n\nimport type { ExceptionStackFrame as StackFrame } from '@grafana/faro-core';\n\n// Declare global Hermes runtime\ndeclare const HermesInternal: object | undefined;\n\n/**\n * Parse React Native stack traces into structured stack frames\n *\n * React Native stack traces have different formats depending on platform and environment:\n *\n * iOS/Android (Dev):\n *   at functionName (file.js:123:45)\n *   at anonymous (native)\n *\n * iOS/Android (Release):\n *   functionName@123:456\n *   @[native code]\n *\n * Metro bundler:\n *   at Object.functionName (/path/to/file.js:123:456)\n */\n\nconst REACT_NATIVE_STACK_REGEX = /^\\s*at\\s+(.+?)\\s+\\((.+?):(\\d+):(\\d+)\\)$/;\nconst REACT_NATIVE_NATIVE_REGEX = /^\\s*at\\s+(.+?)\\s+\\(native\\)$/;\nconst REACT_NATIVE_RELEASE_REGEX = /^(.+?)@(\\d+):(\\d+)$/;\nconst REACT_NATIVE_ANONYMOUS_REGEX = /^\\s*at\\s+anonymous\\s+\\((.+?):(\\d+):(\\d+)\\)$/;\nconst METRO_BUNDLER_REGEX = /^\\s*at\\s+(?:Object\\.)?(.+?)\\s+\\((.+?):(\\d+):(\\d+)\\)$/;\n\nexport interface ParsedStackFrame {\n  function?: string;\n  filename?: string;\n  lineno?: number;\n  colno?: number;\n  isNative?: boolean;\n}\n\n/**\n * Parse a single stack trace line into a structured frame\n */\nexport function parseStackTraceLine(line: string): ParsedStackFrame | null {\n  if (!line || typeof line !== 'string') {\n    return null;\n  }\n\n  const trimmedLine = line.trim();\n  if (!trimmedLine) {\n    return null;\n  }\n\n  // Try standard React Native format: at functionName (file.js:123:45)\n  let match = trimmedLine.match(REACT_NATIVE_STACK_REGEX);\n  if (match && match[2] && match[3] && match[4]) {\n    return {\n      function: match[1] || '<anonymous>',\n      filename: match[2],\n      lineno: parseInt(match[3], 10),\n      colno: parseInt(match[4], 10),\n    };\n  }\n\n  // Try Metro bundler format: at Object.functionName (/path/to/file.js:123:456)\n  match = trimmedLine.match(METRO_BUNDLER_REGEX);\n  if (match && match[2] && match[3] && match[4]) {\n    return {\n      function: match[1] || '<anonymous>',\n      filename: match[2],\n      lineno: parseInt(match[3], 10),\n      colno: parseInt(match[4], 10),\n    };\n  }\n\n  // Try anonymous format: at anonymous (file.js:123:45)\n  match = trimmedLine.match(REACT_NATIVE_ANONYMOUS_REGEX);\n  if (match && match[1] && match[2] && match[3]) {\n    return {\n      function: '<anonymous>',\n      filename: match[1],\n      lineno: parseInt(match[2], 10),\n      colno: parseInt(match[3], 10),\n    };\n  }\n\n  // Try native format: at functionName (native)\n  match = trimmedLine.match(REACT_NATIVE_NATIVE_REGEX);\n  if (match) {\n    return {\n      function: match[1] || '<native>',\n      filename: '<native>',\n      isNative: true,\n    };\n  }\n\n  // Try release/minified format: functionName@123:456\n  match = trimmedLine.match(REACT_NATIVE_RELEASE_REGEX);\n  if (match && match[2] && match[3]) {\n    return {\n      function: match[1] || '<anonymous>',\n      filename: '<unknown>',\n      lineno: parseInt(match[2], 10),\n      colno: parseInt(match[3], 10),\n    };\n  }\n\n  // Couldn't parse this line\n  return null;\n}\n\n/**\n * Parse a full stack trace string into an array of structured frames\n */\nexport function parseStackTrace(stackTrace: string): ParsedStackFrame[] {\n  if (!stackTrace || typeof stackTrace !== 'string') {\n    return [];\n  }\n\n  const lines = stackTrace.split('\\n');\n  const frames: ParsedStackFrame[] = [];\n\n  for (const line of lines) {\n    const frame = parseStackTraceLine(line);\n    if (frame) {\n      frames.push(frame);\n    }\n  }\n\n  return frames;\n}\n\n/**\n * Convert parsed stack frames to Faro's StackFrame format\n */\nexport function toFaroStackFrames(parsedFrames: ParsedStackFrame[]): StackFrame[] {\n  return parsedFrames.map((frame, _index) => ({\n    filename: frame.filename || '<unknown>',\n    function: frame.function || '<anonymous>',\n    lineno: frame.lineno,\n    colno: frame.colno,\n  }));\n}\n\n/**\n * Extract and parse stack frames from an Error object\n */\nexport function getStackFramesFromError(error: Error): StackFrame[] {\n  if (!error || !error.stack) {\n    return [];\n  }\n\n  try {\n    const parsedFrames = parseStackTrace(error.stack);\n    return toFaroStackFrames(parsedFrames);\n  } catch (_e) {\n    // If parsing fails, return empty array\n    return [];\n  }\n}\n\n/**\n * Get platform-specific error context\n */\nexport function getPlatformErrorContext(): Record<string, string> {\n  return {\n    platform: Platform.OS,\n    platformVersion: Platform.Version?.toString() || 'unknown',\n    isHermes: typeof HermesInternal !== 'undefined' ? 'true' : 'false',\n  };\n}\n\n/**\n * Enhance error with React Native specific information\n */\nexport function enhanceErrorWithContext(\n  error: Error,\n  additionalContext?: Record<string, string>\n): {\n  error: Error;\n  stackFrames: StackFrame[];\n  context: Record<string, string>;\n} {\n  const stackFrames = getStackFramesFromError(error);\n  const platformContext = getPlatformErrorContext();\n\n  return {\n    error,\n    stackFrames,\n    context: {\n      ...platformContext,\n      ...additionalContext,\n    },\n  };\n}\n"]}

package/dist/esm/instrumentations/frameMonitoring/index.js

@@ -0,0 +1,2 @@
+export { FrameMonitoringInstrumentation } from './instrumentation';
+//# sourceMappingURL=index.js.map

package/dist/esm/instrumentations/frameMonitoring/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/instrumentations/frameMonitoring/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,8BAA8B,EAAE,MAAM,mBAAmB,CAAC","sourcesContent":["export { FrameMonitoringInstrumentation } from './instrumentation';\nexport type { FrameMetrics, FrameMonitoringOptions } from './types';\n"]}

package/dist/esm/instrumentations/frameMonitoring/instrumentation.js

@@ -0,0 +1,252 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { NativeEventEmitter, NativeModules, Platform } from 'react-native';
+import { BaseInstrumentation, VERSION } from '@grafana/faro-core';
+/**
+ * Default configuration values matching Flutter SDK's hardcoded values.
+ * These are React Native-specific advanced options for customization.
+ */
+const DEFAULT_TARGET_FPS = 60;
+const DEFAULT_FROZEN_FRAME_THRESHOLD_MS = 100;
+const DEFAULT_REFRESH_RATE_POLLING_INTERVAL = 30000;
+const DEFAULT_NORMALIZED_REFRESH_RATE = 60;
+/**
+ * Frame Monitoring Instrumentation for React Native.
+ *
+ * Monitors frame rendering performance and detects slow/frozen frames.
+ * Uses native CADisplayLink (iOS) and Choreographer (Android) for accurate metrics.
+ *
+ * ## Slow Frame Detection
+ * Slow frames are detected using **event-based grouping** to report user-perceptible jank:
+ * - Tracks consecutive frames below `targetFps` as a single "slow frame event"
+ * - Only counts events lasting ≥50ms (~3 frames at 60fps) to filter noise
+ * - This prevents reporting normal microsecond variations as slow frames
+ * - Reports meaningful performance degradation that affects user experience
+ *
+ * ## Frozen Frame Detection
+ * Frozen frames are individual frames exceeding `frozenFrameThresholdMs` (default 100ms).
+ * These represent severe jank where the app appears unresponsive.
+ *
+ * Sends measurements via Faro API:
+ * - `app_refresh_rate`: Current refresh rate in FPS
+ * - `app_frames_rate`: Number of slow frame events (not individual frames)
+ * - `app_frozen_frame`: Number of frozen frames (exceeding frozenFrameThresholdMs)
+ *
+ * @example
+ * ```typescript
+ * import { initializeFaro, FrameMonitoringInstrumentation } from '@grafana/faro-react-native';
+ *
+ * initializeFaro({
+ *   url: 'https://collector.example.com',
+ *   instrumentations: [
+ *     new FrameMonitoringInstrumentation({
+ *       targetFps: 60,
+ *       frozenFrameThresholdMs: 100,
+ *       refreshRatePollingInterval: 30000,
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+export class FrameMonitoringInstrumentation extends BaseInstrumentation {
+    constructor(options = {}) {
+        var _a, _b, _c, _d;
+        super();
+        this.name = '@grafana/faro-react-native:instrumentation-frame-monitoring';
+        this.version = VERSION;
+        this.pollingIntervalId = null;
+        this.eventEmitter = null;
+        this.eventSubscriptions = [];
+        this.options = {
+            targetFps: (_a = options.targetFps) !== null && _a !== void 0 ? _a : DEFAULT_TARGET_FPS,
+            frozenFrameThresholdMs: (_b = options.frozenFrameThresholdMs) !== null && _b !== void 0 ? _b : DEFAULT_FROZEN_FRAME_THRESHOLD_MS,
+            refreshRatePollingInterval: (_c = options.refreshRatePollingInterval) !== null && _c !== void 0 ? _c : DEFAULT_REFRESH_RATE_POLLING_INTERVAL,
+            normalizedRefreshRate: (_d = options.normalizedRefreshRate) !== null && _d !== void 0 ? _d : DEFAULT_NORMALIZED_REFRESH_RATE,
+        };
+    }
+    /**
+     * Check if refresh rate vitals are enabled in Faro config.
+     * Reads from faro.config.refreshRateVitals (single source of truth).
+     */
+    get refreshRateVitalsEnabled() {
+        var _a;
+        // Access config via this.config which is set by BaseInstrumentation after initialization
+        const config = this.config;
+        return (_a = config === null || config === void 0 ? void 0 : config.refreshRateVitals) !== null && _a !== void 0 ? _a : false;
+    }
+    initialize() {
+        this.logDebug('Initializing frame monitoring instrumentation');
+        const nativeModule = this.getNativeModule();
+        if (!nativeModule) {
+            this.logWarn('Native module not available for frame monitoring');
+            return;
+        }
+        // Start native frame monitoring with configuration
+        this.startNativeMonitoring(nativeModule);
+        // Set up event listeners for real-time frame events (Android pattern)
+        this.setupEventListeners(nativeModule);
+        // Set up polling for periodic metrics collection (iOS pattern)
+        this.startPolling();
+    }
+    getNativeModule() {
+        const { FaroReactNativeModule } = NativeModules;
+        if (!FaroReactNativeModule) {
+            return null;
+        }
+        return FaroReactNativeModule;
+    }
+    startNativeMonitoring(nativeModule) {
+        try {
+            if (typeof nativeModule.startFrameMonitoring === 'function') {
+                nativeModule.startFrameMonitoring({
+                    targetFps: this.options.targetFps,
+                    frozenFrameThresholdMs: this.options.frozenFrameThresholdMs,
+                    normalizedRefreshRate: this.options.normalizedRefreshRate,
+                });
+                this.logDebug('Started native frame monitoring');
+            }
+        }
+        catch (error) {
+            this.logError('Failed to start native frame monitoring', error);
+        }
+    }
+    setupEventListeners(nativeModule) {
+        // Android uses event-based approach for frozen frames only
+        // Slow frames are retrieved via polling (like iOS) to avoid flooding
+        if (Platform.OS === 'android') {
+            try {
+                this.eventEmitter = new NativeEventEmitter(nativeModule);
+                // Listen for frozen frame events
+                const frozenFrameSubscription = this.eventEmitter.addListener('onFrozenFrame', (data) => {
+                    // 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);
+                    }
+                });
+                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) => {
+                        this.handleRefreshRate(refreshRate);
+                    });
+                    this.eventSubscriptions.push(refreshRateSubscription);
+                }
+                this.logDebug('Set up Android frame event listeners');
+            }
+            catch (error) {
+                this.logError('Failed to set up frame event listeners', error);
+            }
+        }
+    }
+    startPolling() {
+        // Both iOS and Android use polling approach for slow frames
+        // This provides consistent behavior and avoids flooding with events
+        this.pollingIntervalId = setInterval(() => {
+            this.pollFrameMetrics();
+        }, this.options.refreshRatePollingInterval);
+    }
+    pollFrameMetrics() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const nativeModule = this.getNativeModule();
+            if (!nativeModule) {
+                return;
+            }
+            try {
+                // Get refresh rate (only send when refreshRateVitals is enabled in config)
+                if (this.refreshRateVitalsEnabled) {
+                    if (typeof nativeModule.getRefreshRate === 'function') {
+                        const refreshRate = yield nativeModule.getRefreshRate();
+                        if (refreshRate !== null && refreshRate > 0) {
+                            this.handleRefreshRate(refreshRate);
+                        }
+                    }
+                }
+                // Get full frame metrics if available
+                if (typeof nativeModule.getFrameMetrics === 'function') {
+                    const metrics = (yield nativeModule.getFrameMetrics());
+                    if (metrics) {
+                        if (this.refreshRateVitalsEnabled && metrics.refreshRate > 0) {
+                            this.handleRefreshRate(metrics.refreshRate);
+                        }
+                        if (metrics.slowFrames > 0) {
+                            this.handleSlowFrames(metrics.slowFrames);
+                        }
+                        if (metrics.frozenFrames > 0) {
+                            this.handleFrozenFrame(metrics.frozenFrames, metrics.frozenDurationMs);
+                        }
+                    }
+                }
+            }
+            catch (error) {
+                this.logError('Failed to poll frame metrics', error);
+            }
+        });
+    }
+    handleRefreshRate(refreshRate) {
+        this.api.pushMeasurement({
+            type: 'app_refresh_rate',
+            values: { refresh_rate: refreshRate },
+        }, { skipDedupe: true });
+    }
+    handleSlowFrames(count) {
+        // Note: Despite the name "slow_frames", this count represents slow frame EVENTS, not individual frames.
+        // Each event is a period of consecutive slow frames lasting ≥50ms (~3 frames at 60fps).
+        this.api.pushMeasurement({
+            type: 'app_frames_rate',
+            values: { slow_frames: count },
+        }, { skipDedupe: true });
+    }
+    handleFrozenFrame(count, durationMs) {
+        // 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',
+                values: {
+                    frozen_frames: count,
+                    frozen_duration: durationMs,
+                },
+            }, { skipDedupe: true });
+        }
+    }
+    /**
+     * Clean up resources when instrumentation is disabled.
+     */
+    unpatch() {
+        // Stop polling
+        if (this.pollingIntervalId !== null) {
+            clearInterval(this.pollingIntervalId);
+            this.pollingIntervalId = null;
+        }
+        // Remove event subscriptions
+        for (const subscription of this.eventSubscriptions) {
+            subscription.remove();
+        }
+        this.eventSubscriptions = [];
+        this.eventEmitter = null;
+        // Stop native monitoring
+        const nativeModule = this.getNativeModule();
+        if (nativeModule && typeof nativeModule.stopFrameMonitoring === 'function') {
+            try {
+                nativeModule.stopFrameMonitoring();
+            }
+            catch (error) {
+                this.logError('Failed to stop native frame monitoring', error);
+            }
+        }
+        this.logDebug('Frame monitoring instrumentation stopped');
+    }
+}
+//# sourceMappingURL=instrumentation.js.map

package/dist/esm/instrumentations/frameMonitoring/instrumentation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instrumentation.js","sourceRoot":"","sources":["../../../../src/instrumentations/frameMonitoring/instrumentation.ts"],"names":[],"mappings":"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","sourcesContent":["import { NativeEventEmitter, NativeModules, Platform } from 'react-native';\n\nimport { BaseInstrumentation, VERSION } from '@grafana/faro-core';\n\nimport type { ReactNativeConfig } from '../../config/types';\n\nimport type { FrameMetrics, FrameMonitoringOptions } from './types';\n\n/**\n * Default configuration values matching Flutter SDK's hardcoded values.\n * These are React Native-specific advanced options for customization.\n */\nconst DEFAULT_TARGET_FPS = 60;\nconst DEFAULT_FROZEN_FRAME_THRESHOLD_MS = 100;\nconst DEFAULT_REFRESH_RATE_POLLING_INTERVAL = 30000;\nconst DEFAULT_NORMALIZED_REFRESH_RATE = 60;\n\n/**\n * Frame Monitoring Instrumentation for React Native.\n *\n * Monitors frame rendering performance and detects slow/frozen frames.\n * Uses native CADisplayLink (iOS) and Choreographer (Android) for accurate metrics.\n *\n * ## Slow Frame Detection\n * Slow frames are detected using **event-based grouping** to report user-perceptible jank:\n * - Tracks consecutive frames below `targetFps` as a single \"slow frame event\"\n * - Only counts events lasting ≥50ms (~3 frames at 60fps) to filter noise\n * - This prevents reporting normal microsecond variations as slow frames\n * - Reports meaningful performance degradation that affects user experience\n *\n * ## Frozen Frame Detection\n * Frozen frames are individual frames exceeding `frozenFrameThresholdMs` (default 100ms).\n * These represent severe jank where the app appears unresponsive.\n *\n * Sends measurements via Faro API:\n * - `app_refresh_rate`: Current refresh rate in FPS\n * - `app_frames_rate`: Number of slow frame events (not individual frames)\n * - `app_frozen_frame`: Number of frozen frames (exceeding frozenFrameThresholdMs)\n *\n * @example\n * ```typescript\n * import { initializeFaro, FrameMonitoringInstrumentation } from '@grafana/faro-react-native';\n *\n * initializeFaro({\n *   url: 'https://collector.example.com',\n *   instrumentations: [\n *     new FrameMonitoringInstrumentation({\n *       targetFps: 60,\n *       frozenFrameThresholdMs: 100,\n *       refreshRatePollingInterval: 30000,\n *     }),\n *   ],\n * });\n * ```\n */\nexport class FrameMonitoringInstrumentation extends BaseInstrumentation {\n  readonly name = '@grafana/faro-react-native:instrumentation-frame-monitoring';\n  readonly version = VERSION;\n\n  private readonly options: Required<FrameMonitoringOptions>;\n  private pollingIntervalId: ReturnType<typeof setInterval> | null = null;\n  private eventEmitter: NativeEventEmitter | null = null;\n  private eventSubscriptions: Array<{ remove: () => void }> = [];\n\n  constructor(options: FrameMonitoringOptions = {}) {\n    super();\n    this.options = {\n      targetFps: options.targetFps ?? DEFAULT_TARGET_FPS,\n      frozenFrameThresholdMs: options.frozenFrameThresholdMs ?? DEFAULT_FROZEN_FRAME_THRESHOLD_MS,\n      refreshRatePollingInterval: options.refreshRatePollingInterval ?? DEFAULT_REFRESH_RATE_POLLING_INTERVAL,\n      normalizedRefreshRate: options.normalizedRefreshRate ?? DEFAULT_NORMALIZED_REFRESH_RATE,\n    };\n  }\n\n  /**\n   * Check if refresh rate vitals are enabled in Faro config.\n   * Reads from faro.config.refreshRateVitals (single source of truth).\n   */\n  private get refreshRateVitalsEnabled(): boolean {\n    // Access config via this.config which is set by BaseInstrumentation after initialization\n    const config = this.config as ReactNativeConfig | undefined;\n    return config?.refreshRateVitals ?? false;\n  }\n\n  initialize(): void {\n    this.logDebug('Initializing frame monitoring instrumentation');\n\n    const nativeModule = this.getNativeModule();\n    if (!nativeModule) {\n      this.logWarn('Native module not available for frame monitoring');\n      return;\n    }\n\n    // Start native frame monitoring with configuration\n    this.startNativeMonitoring(nativeModule);\n\n    // Set up event listeners for real-time frame events (Android pattern)\n    this.setupEventListeners(nativeModule);\n\n    // Set up polling for periodic metrics collection (iOS pattern)\n    this.startPolling();\n  }\n\n  private getNativeModule(): typeof NativeModules.FaroReactNativeModule | null {\n    const { FaroReactNativeModule } = NativeModules;\n\n    if (!FaroReactNativeModule) {\n      return null;\n    }\n\n    return FaroReactNativeModule;\n  }\n\n  private startNativeMonitoring(nativeModule: typeof NativeModules.FaroReactNativeModule): void {\n    try {\n      if (typeof nativeModule.startFrameMonitoring === 'function') {\n        nativeModule.startFrameMonitoring({\n          targetFps: this.options.targetFps,\n          frozenFrameThresholdMs: this.options.frozenFrameThresholdMs,\n          normalizedRefreshRate: this.options.normalizedRefreshRate,\n        });\n        this.logDebug('Started native frame monitoring');\n      }\n    } catch (error) {\n      this.logError('Failed to start native frame monitoring', error);\n    }\n  }\n\n  private setupEventListeners(nativeModule: typeof NativeModules.FaroReactNativeModule): void {\n    // Android uses event-based approach for frozen frames only\n    // Slow frames are retrieved via polling (like iOS) to avoid flooding\n    if (Platform.OS === 'android') {\n      try {\n        this.eventEmitter = new NativeEventEmitter(nativeModule);\n\n        // Listen for frozen frame events\n        const frozenFrameSubscription = this.eventEmitter.addListener(\n          'onFrozenFrame',\n          (data: number | { count: number; durationMs: number }) => {\n            // Support both formats: number (legacy) or object (with duration)\n            if (typeof data === 'number') {\n              this.handleFrozenFrame(data, 0);\n            } else {\n              this.handleFrozenFrame(data.count, data.durationMs || 0);\n            }\n          }\n        );\n        this.eventSubscriptions.push(frozenFrameSubscription);\n\n        // Listen for refresh rate events (only when refreshRateVitals is enabled in config)\n        if (this.refreshRateVitalsEnabled) {\n          const refreshRateSubscription = this.eventEmitter.addListener('onRefreshRate', (refreshRate: number) => {\n            this.handleRefreshRate(refreshRate);\n          });\n          this.eventSubscriptions.push(refreshRateSubscription);\n        }\n\n        this.logDebug('Set up Android frame event listeners');\n      } catch (error) {\n        this.logError('Failed to set up frame event listeners', error);\n      }\n    }\n  }\n\n  private startPolling(): void {\n    // Both iOS and Android use polling approach for slow frames\n    // This provides consistent behavior and avoids flooding with events\n    this.pollingIntervalId = setInterval(() => {\n      this.pollFrameMetrics();\n    }, this.options.refreshRatePollingInterval);\n  }\n\n  private async pollFrameMetrics(): Promise<void> {\n    const nativeModule = this.getNativeModule();\n    if (!nativeModule) {\n      return;\n    }\n\n    try {\n      // Get refresh rate (only send when refreshRateVitals is enabled in config)\n      if (this.refreshRateVitalsEnabled) {\n        if (typeof nativeModule.getRefreshRate === 'function') {\n          const refreshRate = await nativeModule.getRefreshRate();\n          if (refreshRate !== null && refreshRate > 0) {\n            this.handleRefreshRate(refreshRate);\n          }\n        }\n      }\n\n      // Get full frame metrics if available\n      if (typeof nativeModule.getFrameMetrics === 'function') {\n        const metrics = (await nativeModule.getFrameMetrics()) as FrameMetrics | null;\n        if (metrics) {\n          if (this.refreshRateVitalsEnabled && metrics.refreshRate > 0) {\n            this.handleRefreshRate(metrics.refreshRate);\n          }\n          if (metrics.slowFrames > 0) {\n            this.handleSlowFrames(metrics.slowFrames);\n          }\n          if (metrics.frozenFrames > 0) {\n            this.handleFrozenFrame(metrics.frozenFrames, metrics.frozenDurationMs);\n          }\n        }\n      }\n    } catch (error) {\n      this.logError('Failed to poll frame metrics', error);\n    }\n  }\n\n  private handleRefreshRate(refreshRate: number): void {\n    this.api.pushMeasurement(\n      {\n        type: 'app_refresh_rate',\n        values: { refresh_rate: refreshRate },\n      },\n      { skipDedupe: true }\n    );\n  }\n\n  private handleSlowFrames(count: number): void {\n    // Note: Despite the name \"slow_frames\", this count represents slow frame EVENTS, not individual frames.\n    // Each event is a period of consecutive slow frames lasting ≥50ms (~3 frames at 60fps).\n    this.api.pushMeasurement(\n      {\n        type: 'app_frames_rate',\n        values: { slow_frames: count },\n      },\n      { skipDedupe: true }\n    );\n  }\n\n  private handleFrozenFrame(count: number, durationMs: number): void {\n    // Only send frozen frame events if duration is greater than 0\n    // This filters out any erroneous 0ms frozen frames\n    if (durationMs > 0) {\n      // 🔍 TEMP DEBUG LOG - Remove after analysis\n      console.log(\n        `[Faro DEBUG ${Platform.OS.toUpperCase()}] 🧊 SENDING frozen frame: count=${count}, duration=${durationMs}ms`\n      );\n\n      this.api.pushMeasurement(\n        {\n          type: 'app_frozen_frame',\n          values: {\n            frozen_frames: count,\n            frozen_duration: durationMs,\n          },\n        },\n        { skipDedupe: true }\n      );\n    }\n  }\n\n  /**\n   * Clean up resources when instrumentation is disabled.\n   */\n  unpatch(): void {\n    // Stop polling\n    if (this.pollingIntervalId !== null) {\n      clearInterval(this.pollingIntervalId);\n      this.pollingIntervalId = null;\n    }\n\n    // Remove event subscriptions\n    for (const subscription of this.eventSubscriptions) {\n      subscription.remove();\n    }\n    this.eventSubscriptions = [];\n    this.eventEmitter = null;\n\n    // Stop native monitoring\n    const nativeModule = this.getNativeModule();\n    if (nativeModule && typeof nativeModule.stopFrameMonitoring === 'function') {\n      try {\n        nativeModule.stopFrameMonitoring();\n      } catch (error) {\n        this.logError('Failed to stop native frame monitoring', error);\n      }\n    }\n\n    this.logDebug('Frame monitoring instrumentation stopped');\n  }\n}\n"]}

package/dist/esm/instrumentations/frameMonitoring/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/esm/instrumentations/frameMonitoring/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/instrumentations/frameMonitoring/types.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * Configuration options for Frame Monitoring instrumentation.\n *\n * These are React Native-specific advanced options. The Flutter SDK uses fixed values\n * for these parameters (not configurable). Defaults here match Flutter's hardcoded values\n * for cross-platform consistency.\n *\n * Note: To enable frame monitoring, set `refreshRateVitals: true` in ReactNativeConfig.\n */\nexport interface FrameMonitoringOptions {\n  /**\n   * Target frames per second for slow frame detection.\n   * Frames rendering below this threshold are considered \"slow\".\n   * Default: 60 (Flutter SDK hardcoded value)\n   */\n  targetFps?: number;\n\n  /**\n   * Threshold in milliseconds for detecting frozen frames.\n   * Frames taking longer than this are considered \"frozen\".\n   * Default: 100ms (Flutter SDK uses 100_000_000 nanoseconds)\n   */\n  frozenFrameThresholdMs?: number;\n\n  /**\n   * Interval in milliseconds for collecting and sending frame metrics.\n   * Default: 30000 (30 seconds, aligned with fetchVitalsInterval)\n   */\n  refreshRatePollingInterval?: number;\n\n  /**\n   * Normalized refresh rate for ProMotion displays (120Hz, etc.).\n   * Used to normalize frame rates for high-refresh-rate displays to a standard baseline.\n   * Default: 60 (Flutter SDK's backendSupportedFrameRate)\n   */\n  normalizedRefreshRate?: number;\n}\n\n/**\n * Frame metrics collected by the instrumentation.\n */\nexport interface FrameMetrics {\n  /**\n   * Current refresh rate in FPS.\n   */\n  refreshRate: number;\n\n  /**\n   * Number of slow frames since last measurement.\n   */\n  slowFrames: number;\n\n  /**\n   * Number of frozen frames since last measurement.\n   */\n  frozenFrames: number;\n\n  /**\n   * Total duration of frozen frames in milliseconds.\n   */\n  frozenDurationMs: number;\n}\n\n/**\n * Native module methods for frame monitoring.\n */\nexport interface FrameMonitoringNativeModule {\n  /**\n   * Start frame monitoring.\n   */\n  startFrameMonitoring(config: {\n    targetFps: number;\n    frozenFrameThresholdMs: number;\n    normalizedRefreshRate: number;\n  }): void;\n\n  /**\n   * Stop frame monitoring.\n   */\n  stopFrameMonitoring(): void;\n\n  /**\n   * Get current frame metrics.\n   */\n  getFrameMetrics(): Promise<FrameMetrics | null>;\n\n  /**\n   * Get current refresh rate.\n   */\n  getRefreshRate(): Promise<number | null>;\n}\n"]}

package/dist/esm/instrumentations/http/index.js

@@ -0,0 +1,168 @@
+import { BaseInstrumentation, genShortID, VERSION } from '@grafana/faro-core';
+import { notifyHttpRequestEnd, notifyHttpRequestStart } from '../userActions/httpRequestMonitor';
+import { getPushEventOptionsWithActionContext } from '../utils/actionContext';
+import { buildFetchEventAttributes } from './utils';
+const FARO_TRACING_FETCH_EVENT = 'faro.tracing.fetch';
+/**
+ * Compute request body size in bytes (best-effort).
+ * FormData and ReadableStream do not expose length without consuming.
+ */
+function getRequestSize(body) {
+    if (body == null)
+        return undefined;
+    if (typeof body === 'string')
+        return new Blob([body]).size;
+    if (body instanceof ArrayBuffer)
+        return body.byteLength;
+    if (ArrayBuffer.isView(body))
+        return body.byteLength;
+    if (typeof Blob !== 'undefined' && body instanceof Blob)
+        return body.size;
+    if (body instanceof URLSearchParams)
+        return new Blob([body.toString()]).size;
+    return undefined;
+}
+/**
+ * HTTP instrumentation for React Native
+ *
+ * Tracks fetch API calls and emits faro.tracing.fetch events (Web SDK format).
+ * Compatible with Grafana Frontend Observability HTTP insights.
+ * Automatically captures:
+ * - Request URL, method, and timing
+ * - Response status codes (0 for network errors)
+ * - Request duration
+ * - Request/response size (bytes; best-effort)
+ * - Network errors
+ *
+ * @example
+ * ```tsx
+ * import { initializeFaro } from '@grafana/faro-react-native';
+ * import { HttpInstrumentation } from '@grafana/faro-react-native';
+ *
+ * initializeFaro({
+ *   // ...config
+ *   instrumentations: [
+ *     new HttpInstrumentation({
+ *       ignoredUrls: [/localhost/, /127\.0\.0\.1/],
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+export class HttpInstrumentation extends BaseInstrumentation {
+    constructor(options = {}) {
+        super();
+        this.name = '@grafana/faro-react-native:instrumentation-http';
+        this.version = VERSION;
+        this.requests = new Map();
+        this.ignoredUrls = options.ignoredUrls || [];
+    }
+    initialize() {
+        this.logInfo('HTTP instrumentation initialized');
+        this.patchFetch();
+    }
+    unpatch() {
+        if (this.originalFetch) {
+            global.fetch = this.originalFetch;
+            this.originalFetch = undefined;
+        }
+        this.requests.clear();
+    }
+    isUrlIgnored(url) {
+        var _a;
+        // Ignore the Faro collector URL to avoid tracking our own telemetry
+        if (url.includes('grafana.net/collect')) {
+            return true;
+        }
+        // Check user-provided ignored URLs
+        if (this.ignoredUrls.some((pattern) => pattern.test(url))) {
+            return true;
+        }
+        // Check config ignore URLs (includes transport URLs)
+        const configIgnoreUrls = ((_a = this.config) === null || _a === void 0 ? void 0 : _a.ignoreUrls) || [];
+        if (configIgnoreUrls.some((pattern) => {
+            if (typeof pattern === 'string') {
+                return url.includes(pattern);
+            }
+            return pattern.test(url);
+        })) {
+            return true;
+        }
+        return false;
+    }
+    patchFetch() {
+        if (this.originalFetch) {
+            return; // Already patched
+        }
+        this.originalFetch = global.fetch;
+        const self = this;
+        global.fetch = function (input, init) {
+            const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url || '';
+            // Extract method from Request object or init options
+            const requestMethod = typeof input !== 'string' && !(input instanceof URL) ? input.method : undefined;
+            const method = ((init === null || init === void 0 ? void 0 : init.method) || requestMethod || 'GET').toUpperCase();
+            if (self.isUrlIgnored(url)) {
+                return self.originalFetch.call(this, input, init);
+            }
+            const requestId = genShortID();
+            const startTime = Date.now();
+            const body = init === null || init === void 0 ? void 0 : init.body;
+            const requestSize = getRequestSize(body);
+            const payload = {
+                url,
+                method,
+                requestId,
+                startTime,
+                requestSize,
+            };
+            self.requests.set(requestId, payload);
+            // Notify user action monitor
+            notifyHttpRequestStart(payload);
+            return self
+                .originalFetch.call(this, input, init)
+                .then((response) => {
+                var _a;
+                const endTime = Date.now();
+                const duration = endTime - startTime;
+                const contentLength = response.headers.get('content-length');
+                const responseSize = contentLength ? parseInt(contentLength, 10) : undefined;
+                payload.responseSize =
+                    responseSize != null && !Number.isNaN(responseSize) && responseSize >= 0 ? responseSize : undefined;
+                payload.endTime = endTime;
+                payload.duration = duration;
+                payload.status = response.status;
+                // Notify user action monitor
+                notifyHttpRequestEnd(payload);
+                // Emit faro.tracing.fetch event (Web SDK format for Grafana HTTP insights)
+                // Include action context when active so HTTP errors show in user action table
+                const attributes = buildFetchEventAttributes(payload);
+                const pushOptions = getPushEventOptionsWithActionContext();
+                (_a = self.api) === null || _a === void 0 ? void 0 : _a.pushEvent(FARO_TRACING_FETCH_EVENT, attributes, undefined, pushOptions);
+                self.logDebug(`HTTP request → ${method} ${url} | status=${response.status} duration=${duration}ms` +
+                    (requestSize != null ? ` request_size=${requestSize}` : '') +
+                    (payload.responseSize != null ? ` response_size=${payload.responseSize}` : ''));
+                self.requests.delete(requestId);
+                return response;
+            })
+                .catch((error) => {
+                var _a;
+                const endTime = Date.now();
+                const duration = endTime - startTime;
+                payload.endTime = endTime;
+                payload.duration = duration;
+                payload.error = (error === null || error === void 0 ? void 0 : error.message) || 'Unknown error';
+                // Notify user action monitor
+                notifyHttpRequestEnd(payload);
+                // Emit faro.tracing.fetch event for failed request (status 0 = network error)
+                const attributes = buildFetchEventAttributes(payload);
+                const pushOptions = getPushEventOptionsWithActionContext();
+                (_a = self.api) === null || _a === void 0 ? void 0 : _a.pushEvent(FARO_TRACING_FETCH_EVENT, attributes, undefined, pushOptions);
+                self.logDebug(`HTTP request error → ${method} ${url} | error=${payload.error} duration=${duration}ms` +
+                    (requestSize != null ? ` request_size=${requestSize}` : ''));
+                self.requests.delete(requestId);
+                throw error;
+            });
+        };
+    }
+}
+//# sourceMappingURL=index.js.map