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

package/src/index.ts

@@ -19,6 +19,12 @@ export { ErrorMechanism, ErrorsInstrumentation } from './instrumentations/errors
 export type { ErrorMechanismType, ErrorsInstrumentationOptions } from './instrumentations/errors';
 export { ConsoleInstrumentation } from './instrumentations/console';
 export { SessionInstrumentation } from './instrumentations/session';
+export {
+  getSessionAttributes,
+  loadSessionDeviceAttributesForInit,
+  minimalSessionDeviceAttributes,
+} from './instrumentations/session/sessionAttributes';
+export type { SessionAttributes } from './instrumentations/session/sessionAttributes';
 export { ViewInstrumentation } from './instrumentations/view';
 export { AppStateInstrumentation } from './instrumentations/appState';
 export { UserActionInstrumentation } from './instrumentations/userActions';
@@ -110,5 +116,5 @@ export type {
   PushMeasurementOptions,
 } from '@grafana/faro-core';
 
-// Export LogLevel enum (not just the type)
-export { LogLevel } from '@grafana/faro-core';
+// Export LogLevel and InternalLoggerLevel from our local copy (avoid bundling faro-core's web code)
+export { LogLevel, InternalLoggerLevel, allLogLevels, defaultLogLevel } from './internalLogger';

package/src/initialize.test.ts

@@ -0,0 +1,126 @@
+import { VERSION } from '@grafana/faro-core';
+import { mockConfig, MockTransport } from '@grafana/faro-test-utils';
+
+import packageJson from '../package.json';
+
+import { initializeFaro } from './initialize';
+import { SessionInstrumentation } from './instrumentations/session';
+import * as sessionAttributes from './instrumentations/session/sessionAttributes';
+
+describe('initializeFaro', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    jest.clearAllTimers();
+    delete (global as any).faro;
+  });
+
+  it('should initialize Faro', async () => {
+    const transport = new MockTransport();
+    const faro = await initializeFaro(
+      mockConfig({
+        url: 'http://localhost:12345/collect',
+        transports: [transport],
+        instrumentations: [new SessionInstrumentation()],
+        sessionTracking: {
+          enabled: true,
+          persistent: false,
+        },
+      })
+    );
+
+    expect(faro).toBeDefined();
+    expect(faro.api).toBeDefined();
+    expect(faro.metas).toBeDefined();
+  });
+
+  it('should set session on init for volatile session tracking', async () => {
+    const transport = new MockTransport();
+    const faro = await initializeFaro(
+      mockConfig({
+        url: 'http://localhost:12345/collect',
+        transports: [transport],
+        instrumentations: [new SessionInstrumentation()],
+        sessionTracking: {
+          enabled: true,
+          persistent: false,
+        },
+      })
+    );
+
+    expect(faro).toBeDefined();
+    expect(faro.metas.value.session?.id).toBeDefined();
+  });
+
+  it('should attach session to telemetry events after init', async () => {
+    const transport = new MockTransport();
+    const faro = await initializeFaro(
+      mockConfig({
+        url: 'http://localhost:12345/collect',
+        transports: [transport],
+        instrumentations: [new SessionInstrumentation()],
+        sessionTracking: {
+          enabled: true,
+          persistent: false,
+        },
+      })
+    );
+
+    transport.items = [];
+    faro.api.pushEvent('test_event', { data: 'test' });
+
+    expect(transport.items).toHaveLength(1);
+    expect(transport.items[0].meta.session).toBeDefined();
+    expect(transport.items[0].meta.session?.id).toBeDefined();
+  });
+
+  it('should reject when url is missing', async () => {
+    await expect(
+      initializeFaro(
+        mockConfig({
+          // @ts-expect-error - testing missing url
+          url: undefined,
+          transports: [],
+        })
+      )
+    ).rejects.toThrow('url is required');
+  });
+
+  it('should await device attributes then merge preloaded session attributes', async () => {
+    const spy = jest.spyOn(sessionAttributes, 'loadSessionDeviceAttributesForInit').mockResolvedValue({
+      react_native_version: '0.0.1',
+      device_os: 'iOS',
+      device_os_version: '17.0',
+      device_os_detail: 'iOS 17.0',
+      device_manufacturer: 'apple',
+      device_model: 'test-model',
+      device_model_name: 'Test Phone',
+      device_brand: 'Apple',
+      device_is_physical: 'true',
+      device_id: 'preloaded-device-id',
+      device_type: 'mobile',
+      device_memory_total: '100',
+      device_memory_used: '50',
+    });
+
+    const faro = await initializeFaro(
+      mockConfig({
+        url: 'http://localhost:12345/collect',
+        transports: [new MockTransport()],
+        instrumentations: [new SessionInstrumentation()],
+        sessionTracking: {
+          enabled: true,
+          persistent: false,
+        },
+      })
+    );
+
+    expect(spy).toHaveBeenCalled();
+    expect(faro.metas.value.sdk?.name).toBe('faro-react-native');
+    expect(faro.metas.value.sdk?.version).toBe(VERSION);
+    expect(faro.metas.value.sdk?.integrations).toEqual([{ name: packageJson.name, version: packageJson.version }]);
+    expect(faro.metas.value.session?.attributes?.['react_native_version']).toBe('0.0.1');
+    expect(faro.metas.value.session?.attributes?.['device_id']).toBe('preloaded-device-id');
+
+    spy.mockRestore();
+  });
+});

package/src/initialize.ts

@@ -2,8 +2,14 @@ import { type Faro, initializeFaro as initializeFaroCore } from '@grafana/faro-c
 
 import { makeRNConfig } from './config/makeRNConfig';
 import type { ReactNativeConfig } from './config/types';
+import { loadSessionDeviceAttributesForInit } from './instrumentations/session/sessionAttributes';
 
-export function initializeFaro(config: ReactNativeConfig): Faro {
-  const fullConfig = makeRNConfig(config);
+/**
+ * Awaits async device/session attribute collection, then initializes Faro with core `initializeFaro`.
+ * On failure during collection, uses `minimalSessionDeviceAttributes` before init.
+ */
+export async function initializeFaro(config: ReactNativeConfig): Promise<Faro> {
+  const preloadedSessionDeviceAttributes = await loadSessionDeviceAttributesForInit();
+  const fullConfig = makeRNConfig(config, preloadedSessionDeviceAttributes);
   return initializeFaroCore(fullConfig);
 }

package/src/instrumentations/console/index.ts

@@ -25,6 +25,7 @@ export class ConsoleInstrumentation extends BaseInstrumentation {
   private originalConsole: Partial<Console> = {};
   private errorSerializer: LogArgsSerializer = reactNativeLogArgsSerializer;
   private patchedLevels: LogLevel[] = [];
+  private isProcessing = false;
 
   initialize(): void {
     const instrumentationOptions = this.config.consoleInstrumentation;
@@ -35,9 +36,11 @@ export class ConsoleInstrumentation extends BaseInstrumentation {
       ? (instrumentationOptions?.errorSerializer ?? defaultErrorArgsSerializer)
       : reactNativeLogArgsSerializer;
 
-    // Store original console methods
+    // Store original console methods - use unpatchedConsole from config if available
+    // to avoid capturing React Native's patched console (LogBox, DevTools)
+    const sourceConsole = this.config.unpatchedConsole ?? console;
     allLogLevels.forEach((level) => {
-      this.originalConsole[level] = console[level];
+      this.originalConsole[level] = sourceConsole[level];
     });
 
     // Determine which levels to patch
@@ -49,6 +52,13 @@ export class ConsoleInstrumentation extends BaseInstrumentation {
     // Patch console methods
     this.patchedLevels.forEach((level) => {
       console[level] = (...args: unknown[]) => {
+        // Prevent re-entry to avoid infinite loops
+        if (this.isProcessing) {
+          this.originalConsole[level]?.(...args);
+          return;
+        }
+
+        this.isProcessing = true;
         try {
           if (level === LogLevel.ERROR && !instrumentationOptions?.consoleErrorAsLog) {
             // Handle console.error as an error with advanced serialization
@@ -83,22 +93,15 @@ export class ConsoleInstrumentation extends BaseInstrumentation {
             // Handle other log levels normally
             this.api.pushLog(args, { level });
           }
-        } catch (err) {
-          // Use unpatchedConsole to avoid infinite loop
-          this.unpatchedConsole.error('[Faro Console] Error capturing log:', err);
-          this.logError(err);
+        } catch (_err) {
+          // Silently ignore errors to prevent infinite loops during bootstrap
         } finally {
-          // Always call original console method
+          // Always call original console method (still protected by isProcessing flag)
           this.originalConsole[level]?.(...args);
+          this.isProcessing = false;
         }
       };
     });
-
-    this.logInfo('Console instrumentation initialized', {
-      patchedLevels: this.patchedLevels,
-      serializeErrors,
-      consoleErrorAsLog: instrumentationOptions?.consoleErrorAsLog ?? false,
-    });
   }
 
   /**
@@ -113,6 +116,5 @@ export class ConsoleInstrumentation extends BaseInstrumentation {
     });
 
     this.patchedLevels = [];
-    this.logInfo('Console instrumentation unpatched');
   }
 }

package/src/instrumentations/errors/index.ts

@@ -60,10 +60,9 @@ interface ErrorFingerprint {
  *
  * @example
  * ```tsx
- * import { initializeFaro } from '@grafana/faro-react-native';
- * import { ErrorsInstrumentation } from '@grafana/faro-react-native';
+ * import { ErrorsInstrumentation, initializeFaro } from '@grafana/faro-react-native';
  *
- * initializeFaro({
+ * await initializeFaro({
  *   // ...config
  *   instrumentations: [
  *     new ErrorsInstrumentation({
@@ -95,8 +94,6 @@ export class ErrorsInstrumentation extends BaseInstrumentation {
   }
 
   initialize(): void {
-    this.logInfo('Initializing errors instrumentation');
-
     // Capture unhandled JavaScript errors
     this.setupGlobalErrorHandler();
 
@@ -113,13 +110,11 @@ export class ErrorsInstrumentation extends BaseInstrumentation {
       try {
         // Check if error should be ignored
         if (this.shouldIgnoreError(error)) {
-          this.logDebug('Ignoring error based on ignoreErrors patterns', { message: error.message });
           return;
         }
 
         // Check for duplicate errors
         if (this.options.enableDeduplication && this.isDuplicateError(error)) {
-          this.logDebug('Ignoring duplicate error', { message: error.message });
           return;
         }
 
@@ -144,9 +139,8 @@ export class ErrorsInstrumentation extends BaseInstrumentation {
         if (this.options.enableDeduplication) {
           this.addErrorFingerprint(error);
         }
-      } catch (e) {
+      } catch (_e) {
         // Don't let error reporting cause more errors
-        this.logError('Failed to report error to Faro', e);
       } finally {
         // Always call the original handler to maintain normal error behavior
         if (this.originalErrorHandler) {
@@ -175,13 +169,11 @@ export class ErrorsInstrumentation extends BaseInstrumentation {
 
         // Check if error should be ignored
         if (this.shouldIgnoreError(error)) {
-          this.logDebug('Ignoring unhandled rejection based on ignoreErrors patterns', { message: error.message });
           return;
         }
 
         // Check for duplicate errors
         if (this.options.enableDeduplication && this.isDuplicateError(error)) {
-          this.logDebug('Ignoring duplicate unhandled rejection', { message: error.message });
           return;
         }
 
@@ -207,8 +199,8 @@ export class ErrorsInstrumentation extends BaseInstrumentation {
         if (this.options.enableDeduplication) {
           this.addErrorFingerprint(error);
         }
-      } catch (e) {
-        this.logError('Failed to report unhandled rejection to Faro', e);
+      } catch (_e) {
+        // Don't let error reporting cause more errors
       }
     };
 

package/src/instrumentations/session/beforeSendHook.test.ts

@@ -0,0 +1,129 @@
+import { mockConfig, MockTransport } from '@grafana/faro-test-utils';
+
+import { initializeFaro } from '../../initialize';
+
+import { SessionInstrumentation } from './index';
+
+function testEventItems(transport: MockTransport) {
+  return transport.items.filter((i) => i.type === 'event' && i.payload.name === 'test_event');
+}
+
+describe('SessionInstrumentation beforeSend hook', () => {
+  let transport: MockTransport;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it('should pass through items when session is sampled (isSampled="true")', async () => {
+    transport = new MockTransport();
+
+    const faro = await initializeFaro(
+      mockConfig({
+        url: 'http://localhost:12345/collect',
+        transports: [transport],
+        instrumentations: [new SessionInstrumentation()],
+        sessionTracking: {
+          enabled: true,
+          persistent: false,
+        },
+      })
+    );
+
+    // Manually set session with isSampled='true'
+    faro.api.setSession({
+      id: 'test-session-id',
+      attributes: { isSampled: 'true' },
+    });
+
+    // Push an event
+    faro.api.pushEvent('test_event', { data: 'test' });
+
+    // Should send the item (after removing isSampled attribute); ignore session_start from init / setSession
+    const testEvents = testEventItems(transport);
+    expect(testEvents).toHaveLength(1);
+    expect(testEvents[0].meta.session?.id).toBe('test-session-id');
+    expect(testEvents[0].meta.session?.attributes?.['isSampled']).toBeUndefined();
+  });
+
+  it('should drop items when session is not sampled (isSampled="false")', async () => {
+    transport = new MockTransport();
+
+    const faro = await initializeFaro(
+      mockConfig({
+        url: 'http://localhost:12345/collect',
+        transports: [transport],
+        instrumentations: [new SessionInstrumentation()],
+        sessionTracking: {
+          enabled: true,
+          persistent: false,
+        },
+      })
+    );
+
+    // Manually set session with isSampled='false'
+    faro.api.setSession({
+      id: 'test-session-id',
+      attributes: { isSampled: 'false' },
+    });
+
+    // Push an event
+    faro.api.pushEvent('test_event', { data: 'test' });
+
+    // Should NOT send the test event (session_start may still be emitted before setSession)
+    expect(testEventItems(transport)).toHaveLength(0);
+  });
+
+  it('should pass through items when no isSampled attribute exists', async () => {
+    transport = new MockTransport();
+
+    const faro = await initializeFaro(
+      mockConfig({
+        url: 'http://localhost:12345/collect',
+        transports: [transport],
+        instrumentations: [new SessionInstrumentation()],
+        sessionTracking: {
+          enabled: true,
+          persistent: false,
+        },
+      })
+    );
+
+    // Manually set session WITHOUT isSampled attribute
+    faro.api.setSession({
+      id: 'test-session-id',
+      attributes: { customAttr: 'value' },
+    });
+
+    // Push an event
+    faro.api.pushEvent('test_event', { data: 'test' });
+
+    // Should send the item unchanged
+    const testEvents = testEventItems(transport);
+    expect(testEvents).toHaveLength(1);
+    expect(testEvents[0].meta.session?.id).toBe('test-session-id');
+    expect(testEvents[0].meta.session?.attributes?.['customAttr']).toBe('value');
+  });
+
+  it('should pass through items when no session exists', async () => {
+    transport = new MockTransport();
+
+    const faro = await initializeFaro(
+      mockConfig({
+        url: 'http://localhost:12345/collect',
+        transports: [transport],
+        instrumentations: [new SessionInstrumentation()],
+        sessionTracking: {
+          enabled: true,
+          persistent: false,
+        },
+      })
+    );
+
+    // Push an event without setting any session
+    faro.api.pushEvent('test_event', { data: 'test' });
+
+    // Should send the test event (session is set at init)
+    expect(testEventItems(transport)).toHaveLength(1);
+  });
+});

package/src/instrumentations/session/index.ts

@@ -1,11 +1,10 @@
 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 type { ReactNativeFullConfig, ReactNativeSessionTrackingConfig } from '../../config/types';
 
-import { getSessionAttributes } from './sessionAttributes';
+import { minimalSessionDeviceAttributes, type SessionAttributes } 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';
@@ -23,6 +22,14 @@ export class SessionInstrumentation extends BaseInstrumentation {
   private notifiedSession: MetaSession | undefined;
   private sessionManagerInstance: InstanceType<SessionManager> | undefined;
 
+  private getDefaultSessionDeviceAttributes(): SessionAttributes {
+    const cfg = this.config as ReactNativeFullConfig;
+    if (cfg.preloadedSessionDeviceAttributes != null) {
+      return cfg.preloadedSessionDeviceAttributes;
+    }
+    return minimalSessionDeviceAttributes();
+  }
+
   private sendSessionStartEvent(meta: Meta): void {
     const session = meta.session;
 
@@ -34,14 +41,14 @@ export class SessionInstrumentation extends BaseInstrumentation {
     }
   }
 
-  private async createInitialSession(
-    SessionManager: SessionManager,
+  private createInitialSession(
+    SessionManagerClass: SessionManager,
     sessionsConfig: Required<Config>['sessionTracking']
-  ): Promise<{
+  ): {
     initialSession: FaroUserSession;
     emitSessionStartOnInit: boolean;
-  }> {
-    let storedUserSession: FaroUserSession | null = await SessionManager.fetchUserSession();
+  } {
+    let storedUserSession = SessionManagerClass.fetchUserSession();
 
     const sessionsConfigTyped = sessionsConfig as ReactNativeSessionTrackingConfig;
     const maxPersistenceMs = sessionsConfigTyped.maxSessionPersistenceTime ?? MAX_SESSION_PERSISTENCE_TIME;
@@ -51,14 +58,12 @@ export class SessionInstrumentation extends BaseInstrumentation {
       const shouldClearPersistentSession = storedUserSession.lastActivity < now - maxPersistenceMs;
 
       if (shouldClearPersistentSession) {
-        await PersistentSessionsManager.removeUserSession();
+        SessionManagerClass.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();
+    const defaultAttributes = this.getDefaultSessionDeviceAttributes();
 
     let emitSessionStartOnInit: boolean;
     let initialSession: FaroUserSession;
@@ -68,7 +73,7 @@ export class SessionInstrumentation extends BaseInstrumentation {
 
       initialSession = createUserSessionObject({
         sessionId,
-        isSampled: storedUserSession!.isSampled || false,
+        isSampled: storedUserSession?.isSampled || false,
         started: storedUserSession?.started,
       });
 
@@ -124,15 +129,24 @@ export class SessionInstrumentation extends BaseInstrumentation {
     return { initialSession, emitSessionStartOnInit };
   }
 
-  private registerBeforeSendHook(SessionManager: SessionManager) {
-    const { updateSession } = new SessionManager();
+  private registerBeforeSendHook(SessionManagerClass: SessionManager) {
+    const { updateSession } = new SessionManagerClass();
 
     this.transports?.addBeforeSendHooks((item: TransportItem) => {
       updateSession();
 
       const attributes = item.meta.session?.attributes;
 
-      if (attributes && attributes?.['isSampled'] === 'true') {
+      // Only filter out items when session is explicitly NOT sampled (isSampled='false')
+      // If isSampled='true', remove the attribute before sending (it's internal)
+      // If no isSampled attribute, pass through the item unchanged
+      if (attributes?.['isSampled'] === 'false') {
+        // Session is not sampled - drop this item
+        return null;
+      }
+
+      if (attributes?.['isSampled'] === 'true') {
+        // Session is sampled - remove internal isSampled attribute before sending
         let newItem: TransportItem = JSON.parse(JSON.stringify(item));
 
         const newAttributes = newItem.meta.session?.attributes;
@@ -145,38 +159,37 @@ export class SessionInstrumentation extends BaseInstrumentation {
         return newItem;
       }
 
-      return null;
+      // No isSampled attribute or other value - pass through unchanged
+      return item;
     });
   }
 
-  async initialize(): Promise<void> {
-    this.logDebug('init session instrumentation');
-
+  initialize(): void {
     const sessionTrackingConfig = this.config.sessionTracking;
 
-    if (sessionTrackingConfig?.enabled) {
-      const SessionManager = getSessionManagerByConfig(sessionTrackingConfig);
-
-      this.registerBeforeSendHook(SessionManager);
+    if (!sessionTrackingConfig?.enabled) {
+      this.metas.addListener(this.sendSessionStartEvent.bind(this));
+      return;
+    }
 
-      const { initialSession, emitSessionStartOnInit } = await this.createInitialSession(
-        SessionManager,
-        sessionTrackingConfig
-      );
+    const SessionManagerClass = getSessionManagerByConfig(sessionTrackingConfig);
 
-      await SessionManager.storeUserSession(initialSession);
+    this.registerBeforeSendHook(SessionManagerClass);
 
-      const initialSessionMeta = initialSession.sessionMeta;
+    const { initialSession, emitSessionStartOnInit } = this.createInitialSession(
+      SessionManagerClass,
+      sessionTrackingConfig
+    );
+    SessionManagerClass.storeUserSession(initialSession);
 
-      this.notifiedSession = initialSessionMeta;
-      this.api.setSession(initialSessionMeta);
+    const initialSessionMeta = initialSession.sessionMeta;
+    this.notifiedSession = initialSessionMeta;
+    this.api.setSession(initialSessionMeta);
 
-      // Store the session manager instance for cleanup
-      this.sessionManagerInstance = new SessionManager();
+    this.sessionManagerInstance = new SessionManagerClass();
 
-      if (emitSessionStartOnInit) {
-        this.api.pushEvent(EVENT_SESSION_START, {}, undefined, { skipDedupe: true });
-      }
+    if (emitSessionStartOnInit) {
+      this.api.pushEvent(EVENT_SESSION_START, {}, undefined, { skipDedupe: true });
     }
 
     this.metas.addListener(this.sendSessionStartEvent.bind(this));