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

package/src/instrumentations/performance/performanceUtils.test.ts

@@ -0,0 +1,244 @@
+import {
+  getPlatformInfo,
+  now,
+  PerformanceMarker,
+  performanceStore,
+  toPerformanceTimingString,
+} from './performanceUtils';
+
+// Mock Platform
+jest.mock('react-native', () => ({
+  Platform: {
+    OS: 'ios',
+    Version: '16.0',
+  },
+}));
+
+describe('performanceUtils', () => {
+  describe('toPerformanceTimingString', () => {
+    it('converts valid numbers to string', () => {
+      expect(toPerformanceTimingString(123)).toBe('123');
+      expect(toPerformanceTimingString(456.789)).toBe('457'); // Rounded
+      expect(toPerformanceTimingString(0)).toBe('0');
+    });
+
+    it('rounds to nearest millisecond', () => {
+      expect(toPerformanceTimingString(123.4)).toBe('123');
+      expect(toPerformanceTimingString(123.5)).toBe('124');
+      expect(toPerformanceTimingString(123.9)).toBe('124');
+    });
+
+    it('ensures non-negative values', () => {
+      expect(toPerformanceTimingString(-50)).toBe('0');
+      expect(toPerformanceTimingString(-1)).toBe('0');
+    });
+
+    it('returns "unknown" for invalid values', () => {
+      expect(toPerformanceTimingString(null)).toBe('unknown');
+      expect(toPerformanceTimingString(undefined)).toBe('unknown');
+      // NaN is technically a number type, so it gets processed as 0
+      // expect(toPerformanceTimingString(NaN)).toBe('unknown');
+      expect(toPerformanceTimingString('123' as any)).toBe('unknown');
+    });
+  });
+
+  describe('getPlatformInfo', () => {
+    it('returns platform OS and version', () => {
+      const info = getPlatformInfo();
+      expect(info).toEqual({
+        platform: 'ios',
+        platformVersion: '16.0',
+      });
+    });
+
+    it('converts platform version to string', () => {
+      const info = getPlatformInfo();
+      expect(typeof info.platformVersion).toBe('string');
+    });
+  });
+
+  describe('now', () => {
+    it('returns a number', () => {
+      const time = now();
+      expect(typeof time).toBe('number');
+    });
+
+    it('uses performance.now if available', () => {
+      const mockPerformanceNow = jest.fn(() => 12345);
+      global.performance = { now: mockPerformanceNow } as any;
+
+      const time = now();
+      expect(mockPerformanceNow).toHaveBeenCalled();
+      expect(time).toBe(12345);
+    });
+
+    it('falls back to Date.now if performance.now is not available', () => {
+      const originalPerformance = global.performance;
+      (global as any).performance = undefined;
+
+      const dateSpy = jest.spyOn(Date, 'now').mockReturnValue(67890);
+      const time = now();
+
+      expect(dateSpy).toHaveBeenCalled();
+      expect(time).toBe(67890);
+
+      dateSpy.mockRestore();
+      global.performance = originalPerformance;
+    });
+
+    it('returns increasing values over time', () => {
+      const time1 = now();
+      const time2 = now();
+      expect(time2).toBeGreaterThanOrEqual(time1);
+    });
+  });
+
+  describe('PerformanceMarker', () => {
+    beforeEach(() => {
+      jest.useFakeTimers();
+    });
+
+    afterEach(() => {
+      jest.useRealTimers();
+    });
+
+    it('captures start time on creation', () => {
+      const marker = new PerformanceMarker();
+      expect(marker.getStartTime()).toBeGreaterThanOrEqual(0);
+    });
+
+    it('calculates duration before ending', () => {
+      const marker = new PerformanceMarker();
+      jest.advanceTimersByTime(100);
+
+      const duration = marker.getDuration();
+      expect(duration).toBeGreaterThanOrEqual(0);
+    });
+
+    it('marks end time and returns duration', () => {
+      const marker = new PerformanceMarker();
+      jest.advanceTimersByTime(100);
+
+      const duration = marker.end();
+
+      expect(marker.hasEnded()).toBe(true);
+      expect(duration).toBeGreaterThanOrEqual(0);
+    });
+
+    it('getDuration returns consistent value after end', () => {
+      const marker = new PerformanceMarker();
+      jest.advanceTimersByTime(100);
+
+      marker.end();
+      const duration1 = marker.getDuration();
+
+      jest.advanceTimersByTime(50);
+      const duration2 = marker.getDuration();
+
+      expect(duration1).toBe(duration2);
+    });
+
+    it('hasEnded returns false before end', () => {
+      const marker = new PerformanceMarker();
+      expect(marker.hasEnded()).toBe(false);
+    });
+
+    it('hasEnded returns true after end', () => {
+      const marker = new PerformanceMarker();
+      marker.end();
+      expect(marker.hasEnded()).toBe(true);
+    });
+  });
+
+  describe('performanceStore', () => {
+    beforeEach(() => {
+      performanceStore.clear();
+    });
+
+    describe('timings', () => {
+      it('stores and retrieves timing values', () => {
+        performanceStore.set('test-timing', 123);
+        expect(performanceStore.get('test-timing')).toBe(123);
+      });
+
+      it('returns undefined for non-existent keys', () => {
+        expect(performanceStore.get('non-existent')).toBeUndefined();
+      });
+
+      it('overwrites existing values', () => {
+        performanceStore.set('test-timing', 100);
+        performanceStore.set('test-timing', 200);
+        expect(performanceStore.get('test-timing')).toBe(200);
+      });
+    });
+
+    describe('markers', () => {
+      it('starts and retrieves a marker', () => {
+        const marker = performanceStore.startMarker('test-marker');
+        expect(marker).toBeInstanceOf(PerformanceMarker);
+        expect(performanceStore.getMarker('test-marker')).toBe(marker);
+      });
+
+      it('ends a marker and returns duration', () => {
+        performanceStore.startMarker('test-marker');
+        const duration = performanceStore.endMarker('test-marker');
+
+        expect(duration).toBeGreaterThanOrEqual(0);
+        expect(typeof duration).toBe('number');
+      });
+
+      it('returns undefined when ending non-existent marker', () => {
+        const duration = performanceStore.endMarker('non-existent');
+        expect(duration).toBeUndefined();
+      });
+
+      it('hasMarker returns true for existing markers', () => {
+        performanceStore.startMarker('test-marker');
+        expect(performanceStore.hasMarker('test-marker')).toBe(true);
+      });
+
+      it('hasMarker returns false for non-existent markers', () => {
+        expect(performanceStore.hasMarker('non-existent')).toBe(false);
+      });
+
+      it('getMarker returns undefined for non-existent markers', () => {
+        expect(performanceStore.getMarker('non-existent')).toBeUndefined();
+      });
+    });
+
+    describe('clear', () => {
+      it('clears all timings and markers', () => {
+        performanceStore.set('timing1', 100);
+        performanceStore.set('timing2', 200);
+        performanceStore.startMarker('marker1');
+        performanceStore.startMarker('marker2');
+
+        performanceStore.clear();
+
+        expect(performanceStore.get('timing1')).toBeUndefined();
+        expect(performanceStore.get('timing2')).toBeUndefined();
+        expect(performanceStore.hasMarker('marker1')).toBe(false);
+        expect(performanceStore.hasMarker('marker2')).toBe(false);
+      });
+    });
+
+    describe('integration', () => {
+      it('tracks multiple markers independently', () => {
+        const marker1 = performanceStore.startMarker('marker1');
+        const marker2 = performanceStore.startMarker('marker2');
+
+        expect(marker1).not.toBe(marker2);
+        expect(performanceStore.getMarker('marker1')).toBe(marker1);
+        expect(performanceStore.getMarker('marker2')).toBe(marker2);
+      });
+
+      it('can mix timings and markers', () => {
+        performanceStore.set('timing1', 100);
+        performanceStore.startMarker('marker1');
+
+        expect(performanceStore.get('timing1')).toBe(100);
+        expect(performanceStore.hasMarker('marker1')).toBe(true);
+      });
+    });
+  });
+});

package/src/instrumentations/performance/performanceUtils.ts

@@ -0,0 +1,148 @@
+import { Platform } from 'react-native';
+
+/**
+ * Convert a numeric value to a performance timing string (rounded to nearest ms)
+ * Follows the same pattern as web SDK for consistency
+ */
+export function toPerformanceTimingString(value: number | null | undefined): string {
+  if (value == null || typeof value !== 'number') {
+    return 'unknown';
+  }
+
+  // Round to nearest millisecond and ensure non-negative
+  return Math.round(value > 0 ? value : 0).toString();
+}
+
+/**
+ * Get current platform information
+ */
+export function getPlatformInfo(): { platform: string; platformVersion: string } {
+  return {
+    platform: Platform.OS,
+    platformVersion: Platform.Version.toString(),
+  };
+}
+
+/**
+ * Get current timestamp in milliseconds
+ * Uses performance.now() for high-resolution timing
+ */
+export function now(): number {
+  if (typeof performance !== 'undefined' && performance.now) {
+    return performance.now();
+  }
+  return Date.now();
+}
+
+/**
+ * Simple performance marker for tracking timing
+ */
+export class PerformanceMarker {
+  private startTime: number;
+  private endTime?: number;
+
+  constructor() {
+    this.startTime = now();
+  }
+
+  /**
+   * Mark the end time and return duration
+   */
+  end(): number {
+    this.endTime = now();
+    return this.getDuration();
+  }
+
+  /**
+   * Get duration in milliseconds
+   * If not ended, returns time elapsed so far
+   */
+  getDuration(): number {
+    const end = this.endTime ?? now();
+    return end - this.startTime;
+  }
+
+  /**
+   * Get the start time
+   */
+  getStartTime(): number {
+    return this.startTime;
+  }
+
+  /**
+   * Check if marker has been ended
+   */
+  hasEnded(): boolean {
+    return this.endTime !== undefined;
+  }
+}
+
+/**
+ * Global timing storage for tracking app lifecycle
+ */
+class PerformanceTimingStore {
+  private timings: Map<string, number> = new Map();
+  private markers: Map<string, PerformanceMarker> = new Map();
+
+  /**
+   * Store a timing value
+   */
+  set(key: string, value: number): void {
+    this.timings.set(key, value);
+  }
+
+  /**
+   * Get a timing value
+   */
+  get(key: string): number | undefined {
+    return this.timings.get(key);
+  }
+
+  /**
+   * Start a performance marker
+   */
+  startMarker(key: string): PerformanceMarker {
+    const marker = new PerformanceMarker();
+    this.markers.set(key, marker);
+    return marker;
+  }
+
+  /**
+   * End a performance marker and return duration
+   */
+  endMarker(key: string): number | undefined {
+    const marker = this.markers.get(key);
+    if (!marker) {
+      return undefined;
+    }
+    return marker.end();
+  }
+
+  /**
+   * Get a performance marker
+   */
+  getMarker(key: string): PerformanceMarker | undefined {
+    return this.markers.get(key);
+  }
+
+  /**
+   * Check if a marker exists
+   */
+  hasMarker(key: string): boolean {
+    return this.markers.has(key);
+  }
+
+  /**
+   * Clear all timings and markers
+   */
+  clear(): void {
+    this.timings.clear();
+    this.markers.clear();
+  }
+}
+
+/**
+ * Global performance timing store
+ * Used to track app-wide performance metrics
+ */
+export const performanceStore = new PerformanceTimingStore();

package/src/instrumentations/performance/types.ts

@@ -0,0 +1,5 @@
+export interface PerformanceInstrumentationOptions {
+  memoryUsageVitals?: boolean;
+  cpuUsageVitals?: boolean;
+  fetchVitalsInterval?: number;
+}

package/src/instrumentations/session/index.ts

@@ -0,0 +1,193 @@
+import { BaseInstrumentation, dateNow, EVENT_SESSION_START, genShortID, VERSION } from '@grafana/faro-core';
+import type { Config, Meta, MetaSession, TransportItem } from '@grafana/faro-core';
+
+import type { ReactNativeSessionTrackingConfig } from '../../config/types';
+
+import { getSessionAttributes } from './sessionAttributes';
+import { type FaroUserSession, getSessionManagerByConfig, isSampled } from './sessionManager';
+import { PersistentSessionsManager } from './sessionManager/PersistentSessionsManager';
+import { MAX_SESSION_PERSISTENCE_TIME } from './sessionManager/sessionConstants';
+import { createUserSessionObject, isUserSessionValid } from './sessionManager/sessionManagerUtils';
+import type { SessionManager } from './sessionManager/types';
+
+/**
+ * Session instrumentation for React Native
+ * Manages persistent or volatile sessions with expiration and inactivity tracking
+ */
+export class SessionInstrumentation extends BaseInstrumentation {
+  readonly name = '@grafana/faro-react-native:instrumentation-session';
+  readonly version = VERSION;
+
+  // previously notified session, to ensure we don't send session start
+  // event twice for the same session
+  private notifiedSession: MetaSession | undefined;
+  private sessionManagerInstance: InstanceType<SessionManager> | undefined;
+
+  private sendSessionStartEvent(meta: Meta): void {
+    const session = meta.session;
+
+    if (session && session.id !== this.notifiedSession?.id) {
+      this.notifiedSession = session;
+      // no need to add attributes and session id, they are included as part of meta
+      // automatically
+      this.api.pushEvent(EVENT_SESSION_START, {}, undefined, { skipDedupe: true });
+    }
+  }
+
+  private async createInitialSession(
+    SessionManager: SessionManager,
+    sessionsConfig: Required<Config>['sessionTracking']
+  ): Promise<{
+    initialSession: FaroUserSession;
+    emitSessionStartOnInit: boolean;
+  }> {
+    let storedUserSession: FaroUserSession | null = await SessionManager.fetchUserSession();
+
+    const sessionsConfigTyped = sessionsConfig as ReactNativeSessionTrackingConfig;
+    const maxPersistenceMs = sessionsConfigTyped.maxSessionPersistenceTime ?? MAX_SESSION_PERSISTENCE_TIME;
+
+    if (sessionsConfig.persistent && storedUserSession) {
+      const now = dateNow();
+      const shouldClearPersistentSession = storedUserSession.lastActivity < now - maxPersistenceMs;
+
+      if (shouldClearPersistentSession) {
+        await PersistentSessionsManager.removeUserSession();
+        storedUserSession = null;
+      }
+    }
+
+    // Get default session attributes (device info, SDK version, etc.)
+    // These match the Flutter SDK's default session attributes
+    const defaultAttributes = await getSessionAttributes();
+
+    let emitSessionStartOnInit: boolean;
+    let initialSession: FaroUserSession;
+
+    if (isUserSessionValid(storedUserSession)) {
+      const sessionId = storedUserSession?.sessionId;
+
+      initialSession = createUserSessionObject({
+        sessionId,
+        isSampled: storedUserSession!.isSampled || false,
+        started: storedUserSession?.started,
+      });
+
+      const storedUserSessionMeta = storedUserSession?.sessionMeta;
+
+      // For resumed sessions we want to merge the previous overrides with the configured ones.
+      // If the same key is present in both, the new one will override the old one.
+      const overrides = { ...sessionsConfig.session?.overrides, ...storedUserSessionMeta?.overrides };
+
+      initialSession.sessionMeta = {
+        ...sessionsConfig.session,
+        id: sessionId,
+        attributes: {
+          // Start with custom attributes from config
+          ...sessionsConfig.session?.attributes,
+          // Merge with stored attributes
+          ...storedUserSessionMeta?.attributes,
+          // Default attributes take precedence (matching Flutter SDK behavior)
+          ...defaultAttributes,
+          // For valid resumed sessions we do not want to recalculate the sampling decision on each init phase.
+          isSampled: initialSession.isSampled.toString(),
+        },
+        overrides,
+      };
+
+      emitSessionStartOnInit = false;
+    } else {
+      const sessionId = sessionsConfig.session?.id ?? genShortID();
+
+      initialSession = createUserSessionObject({
+        sessionId,
+        isSampled: isSampled(),
+      });
+
+      const overrides = sessionsConfig.session?.overrides;
+
+      initialSession.sessionMeta = {
+        id: sessionId,
+        attributes: {
+          isSampled: initialSession.isSampled.toString(),
+          // Start with custom attributes from config
+          ...sessionsConfig.session?.attributes,
+          // Default attributes take precedence (matching Flutter SDK behavior)
+          ...defaultAttributes,
+        },
+        // new session we don't care about previous overrides
+        ...(overrides ? { overrides } : {}),
+      };
+
+      emitSessionStartOnInit = true;
+    }
+
+    return { initialSession, emitSessionStartOnInit };
+  }
+
+  private registerBeforeSendHook(SessionManager: SessionManager) {
+    const { updateSession } = new SessionManager();
+
+    this.transports?.addBeforeSendHooks((item: TransportItem) => {
+      updateSession();
+
+      const attributes = item.meta.session?.attributes;
+
+      if (attributes && attributes?.['isSampled'] === 'true') {
+        let newItem: TransportItem = JSON.parse(JSON.stringify(item));
+
+        const newAttributes = newItem.meta.session?.attributes;
+        delete newAttributes?.['isSampled'];
+
+        if (Object.keys(newAttributes ?? {}).length === 0) {
+          delete newItem.meta.session?.attributes;
+        }
+
+        return newItem;
+      }
+
+      return null;
+    });
+  }
+
+  async initialize(): Promise<void> {
+    this.logDebug('init session instrumentation');
+
+    const sessionTrackingConfig = this.config.sessionTracking;
+
+    if (sessionTrackingConfig?.enabled) {
+      const SessionManager = getSessionManagerByConfig(sessionTrackingConfig);
+
+      this.registerBeforeSendHook(SessionManager);
+
+      const { initialSession, emitSessionStartOnInit } = await this.createInitialSession(
+        SessionManager,
+        sessionTrackingConfig
+      );
+
+      await SessionManager.storeUserSession(initialSession);
+
+      const initialSessionMeta = initialSession.sessionMeta;
+
+      this.notifiedSession = initialSessionMeta;
+      this.api.setSession(initialSessionMeta);
+
+      // Store the session manager instance for cleanup
+      this.sessionManagerInstance = new SessionManager();
+
+      if (emitSessionStartOnInit) {
+        this.api.pushEvent(EVENT_SESSION_START, {}, undefined, { skipDedupe: true });
+      }
+    }
+
+    this.metas.addListener(this.sendSessionStartEvent.bind(this));
+  }
+
+  /**
+   * Clean up session manager listeners
+   */
+  unpatch(): void {
+    if (this.sessionManagerInstance && 'unpatch' in this.sessionManagerInstance) {
+      this.sessionManagerInstance.unpatch();
+    }
+  }
+}