@grafana/faro-react-native 1.3.0 → 1.4.0

package/src/instrumentations/session/sessionActivity.ts

@@ -0,0 +1,58 @@
+import { EVENT_VIEW_CHANGED, TransportItemType } from '@grafana/faro-core';
+import type { EventAttributes, TransportItem } from '@grafana/faro-core';
+
+import { EVENT_NAVIGATION } from '../../navigation/utils';
+import { EVENT_APP_STATE_CHANGED } from '../appState';
+
+export enum SessionActivityKind {
+  Meaningful = 'meaningful',
+  Passive = 'passive',
+}
+
+type ActivityEventPayload = {
+  action?: unknown;
+  attributes?: EventAttributes;
+  name?: string;
+};
+
+/** Classifies how a transport item affects the session inactivity window. */
+export function classifySessionActivity(item: TransportItem): SessionActivityKind {
+  const payload = item.payload as ActivityEventPayload;
+
+  if (payload.action != null) {
+    return SessionActivityKind.Meaningful;
+  }
+
+  if (item.type !== TransportItemType.EVENT) {
+    return SessionActivityKind.Passive;
+  }
+
+  if (payload.name === EVENT_VIEW_CHANGED || payload.name === EVENT_NAVIGATION) {
+    return SessionActivityKind.Meaningful;
+  }
+
+  if (
+    payload.name === EVENT_APP_STATE_CHANGED &&
+    payload.attributes?.['fromState'] === 'background' &&
+    payload.attributes?.['toState'] === 'active'
+  ) {
+    return SessionActivityKind.Meaningful;
+  }
+
+  return SessionActivityKind.Passive;
+}
+
+type CrashPayload = {
+  fatal?: unknown;
+  type?: unknown;
+};
+
+/** Recovered crashes keep the session captured by the previous process. */
+export function isRecoveredCrashItem(item: TransportItem, currentSessionId: string | undefined): boolean {
+  if (item.type !== TransportItemType.EXCEPTION || item.meta.session?.id == null) {
+    return false;
+  }
+
+  const payload = item.payload as CrashPayload;
+  return payload.type === 'crash' && payload.fatal === true && item.meta.session.id !== currentSessionId;
+}

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

@@ -1,11 +1,19 @@
 import AsyncStorage from '@react-native-async-storage/async-storage';
-import { Platform } from 'react-native';
+import { NativeModules, Platform } from 'react-native';
 import DeviceInfo from 'react-native-device-info';
 
-import { getSessionAttributes, loadMobileMetaForInit } from './sessionAttributes';
+import { getSessionAttributes, loadMobileMetaForInit, minimalSessionDeviceAttributes } from './sessionAttributes';
+import { resetSessionProcessForTests } from './sessionProcess';
 
 const INSTALLATION_ID_STORAGE_KEY = '@grafana/faro-react-native/installation_id';
 const STORED_INSTALLATION_ID = 'stored-installation-id';
+const originalNativeModule = NativeModules.FaroReactNativeModule;
+const sessionNativeModule = {
+  claimSessionPersistence: () => true,
+  getSessionProcessIdentifier: () => 'com.example.myapp',
+  isMainSessionProcess: () => true,
+  releaseSessionPersistence: () => true,
+};
 
 function setStoredInstallationId(value = STORED_INSTALLATION_ID): void {
   (global as any).mockAsyncStorage = {
@@ -37,7 +45,14 @@ jest.mock('react-native-device-info', () => ({
 describe('sessionAttributes', () => {
   beforeEach(() => {
     (global as any).mockAsyncStorage = {};
+    NativeModules.FaroReactNativeModule = sessionNativeModule;
     jest.clearAllMocks();
+    resetSessionProcessForTests();
+  });
+
+  afterAll(() => {
+    NativeModules.FaroReactNativeModule = originalNativeModule;
+    resetSessionProcessForTests();
   });
 
   describe('getSessionAttributes', () => {
@@ -79,6 +94,7 @@ describe('sessionAttributes', () => {
 
         expect(attributes).toEqual({
           react_native_version: '0.75.1',
+          process_name: 'com.example.myapp',
           device_os: 'iOS',
           device_os_version: '17.0',
           device_os_detail: 'iOS 17.0',
@@ -177,6 +193,7 @@ describe('sessionAttributes', () => {
 
         expect(attributes).toEqual({
           react_native_version: '0.75.1',
+          process_name: 'com.example.myapp',
           device_os: 'Android',
           device_os_version: '15',
           device_os_detail: 'Android 15 (SDK 35)',
@@ -439,6 +456,7 @@ describe('sessionAttributes', () => {
         expect(mobileMeta).toEqual({
           sessionAttributes: {
             react_native_version: '0.75.1',
+            process_name: 'com.example.myapp',
           },
           meta: {
             app: {
@@ -531,6 +549,7 @@ describe('sessionAttributes', () => {
         // Device info is omitted when collection fails so nothing partial is sent to Faro
         expect(attributes).toEqual({
           react_native_version: expect.any(String),
+          process_name: 'com.example.myapp',
         });
         expect(attributes.device_id).toBeUndefined();
         expect(attributes.device_os).toBeUndefined();
@@ -555,6 +574,7 @@ describe('sessionAttributes', () => {
         // Any synchronous DeviceInfo failure skips all device fields (minimal payload only)
         expect(attributes).toEqual({
           react_native_version: expect.any(String),
+          process_name: 'com.example.myapp',
         });
         expect(attributes.device_id).toBeUndefined();
         expect(attributes.device_manufacturer).toBeUndefined();
@@ -601,5 +621,20 @@ describe('sessionAttributes', () => {
         expect(attributes.device_manufacturer).toBe('oneplus');
       });
     });
+
+    it('omits process identity when the native bridge is unavailable', () => {
+      const nativeModule = NativeModules.FaroReactNativeModule;
+      NativeModules.FaroReactNativeModule = undefined;
+      resetSessionProcessForTests();
+
+      try {
+        expect(minimalSessionDeviceAttributes()).toEqual({
+          react_native_version: expect.any(String),
+        });
+      } finally {
+        NativeModules.FaroReactNativeModule = nativeModule;
+        resetSessionProcessForTests();
+      }
+    });
   });
 });

package/src/instrumentations/session/sessionAttributes.ts

@@ -4,13 +4,14 @@ import DeviceInfo from 'react-native-device-info';
 import type { Meta } from '@grafana/faro-core';
 
 import { getInstallationId } from './installationId';
+import { getSessionProcessInfo } from './sessionProcess';
 
 /**
  * Session attributes for React Native
  * These attributes are automatically included with every telemetry event
  *
- * Core attributes match Flutter SDK format, with additional mobile-specific
- * monitoring fields (memory, device type, battery, etc.)
+ * Core mobile session attributes, with additional monitoring fields
+ * (memory, device type, battery, etc.)
  *
  * SDK name, core version, and npm adapter are on Faro meta `sdk` (`getSdkMeta` in `metas/sdk.ts`).
  *
@@ -20,6 +21,9 @@ export interface SessionAttributes {
   /** Host app's React Native framework version (e.g. "0.75.1") from `Platform.constants`. */
   react_native_version: string;
 
+  /** Stable Android process name or Apple bundle identifier for this runtime. */
+  process_name?: string;
+
   /** Operating system ("iOS" or "Android") */
   device_os?: string;
 
@@ -138,7 +142,7 @@ function getMobileDeviceType(isTablet: boolean): 'mobile' | 'tablet' | undefined
 }
 
 /**
- * Get OS detail string matching Flutter SDK format
+ * Get OS detail string for session attributes.
  * iOS: "iOS 17.0"
  * Android: "Android 15 (SDK 35)"
  */
@@ -174,8 +178,10 @@ async function getDeviceOsBuildId(): Promise<string | undefined> {
  * No synchronous DeviceInfo reads — use {@link getSessionAttributes} or the package async `initializeFaro`.
  */
 export function minimalSessionDeviceAttributes(): SessionAttributes {
+  const processInfo = getSessionProcessInfo();
   return {
     react_native_version: getReactNativeVersion(),
+    ...(processInfo == null ? {} : { process_name: processInfo.identifier }),
   };
 }
 
@@ -183,8 +189,9 @@ export function minimalSessionDeviceAttributes(): SessionAttributes {
  * Get all session attributes
  * These attributes are automatically included with every telemetry event
  *
- * Core attributes matching Flutter SDK:
+ * Core session attributes:
  * - react_native_version (RN framework in the host app)
+ * - process_name (Android process name or iOS bundle identifier)
  * - device_os, device_os_version, device_os_detail
  * - device_manufacturer, device_model, device_model_name
  * - device_brand, device_is_physical, device_id
@@ -222,7 +229,6 @@ async function collectMobileMeta(): Promise<PreloadedMobileMeta> {
     // Memory info
     const totalMemory = DeviceInfo.getTotalMemorySync();
     const usedMemory = DeviceInfo.getUsedMemorySync();
-    const reactNativeVersion = getReactNativeVersion();
 
     // Try to get async device info (battery, carrier)
     let batteryLevel: string | undefined;
@@ -265,7 +271,7 @@ async function collectMobileMeta(): Promise<PreloadedMobileMeta> {
     }
 
     const attributes: SessionAttributes = {
-      react_native_version: reactNativeVersion,
+      ...minimalSessionDeviceAttributes(),
       device_os: systemName,
       device_os_version: systemVersion,
       device_os_detail: deviceOsDetail,

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

@@ -0,0 +1,410 @@
+import { EVENT_SESSION_START, EVENT_VIEW_CHANGED, initializeFaro, TransportItemType } from '@grafana/faro-core';
+import type { TransportItem } from '@grafana/faro-core';
+import { mockConfig, MockTransport } from '@grafana/faro-test-utils';
+
+import { ViewInstrumentation } from '../view';
+
+import { SessionInstrumentation } from './index';
+import { MmkvPersistentSessionsManager } from './sessionManager/MmkvPersistentSessionsManager';
+import { VolatileSessionsManager } from './sessionManager/VolatileSessionManager';
+
+async function initializeWithoutInstrumentations() {
+  return initializeFaro(
+    mockConfig({
+      instrumentations: [],
+      transports: [new MockTransport()],
+      url: 'http://localhost:12345/collect',
+      sessionTracking: { enabled: true, persistent: false },
+    })
+  );
+}
+
+function sessionStartCount(transport: MockTransport): number {
+  return transport.items.filter(
+    (item) => item.type === TransportItemType.EVENT && item.payload.name === EVENT_SESSION_START
+  ).length;
+}
+
+function sessionItem(isSampled: boolean): TransportItem {
+  return {
+    type: TransportItemType.EVENT,
+    payload: { name: 'test' },
+    meta: {
+      session: {
+        id: 'active-session',
+        attributes: { isSampled: isSampled.toString() },
+      },
+    },
+  };
+}
+
+function expectSampledItem(result: TransportItem | null): TransportItem {
+  expect(result).not.toBeNull();
+  if (result == null) {
+    throw new Error('Expected a sampled item to be retained.');
+  }
+
+  expect(result.payload).toEqual({ name: 'test' });
+  expect(result.meta.session?.attributes?.['isSampled']).toBeUndefined();
+  return result;
+}
+
+describe('session cleanup', () => {
+  beforeEach(() => {
+    jest.restoreAllMocks();
+    jest.clearAllMocks();
+    VolatileSessionsManager.removeUserSession();
+  });
+
+  afterEach(() => {
+    VolatileSessionsManager.removeUserSession();
+  });
+
+  it('removes the volatile manager metas listener with the same handler', async () => {
+    const faro = await initializeWithoutInstrumentations();
+    const addListenerSpy = jest.spyOn(faro.metas, 'addListener');
+    const removeListenerSpy = jest.spyOn(faro.metas, 'removeListener');
+    const storeSessionSpy = jest.spyOn(VolatileSessionsManager, 'storeUserSession');
+    const manager = new VolatileSessionsManager();
+    const handler = addListenerSpy.mock.calls[0]?.[0];
+
+    expect(handler).toBeDefined();
+    faro.api.setSession({ id: 'before-cleanup' });
+    expect(storeSessionSpy).toHaveBeenCalled();
+    storeSessionSpy.mockClear();
+
+    manager.unpatch();
+    manager.unpatch();
+
+    expect(removeListenerSpy).toHaveBeenCalledTimes(1);
+    expect(removeListenerSpy).toHaveBeenCalledWith(handler);
+
+    faro.api.setSession({ id: 'after-cleanup' });
+    expect(storeSessionSpy).not.toHaveBeenCalled();
+  });
+
+  it('removes the persistent manager metas listener with the same handler', async () => {
+    const faro = await initializeWithoutInstrumentations();
+    const addListenerSpy = jest.spyOn(faro.metas, 'addListener');
+    const removeListenerSpy = jest.spyOn(faro.metas, 'removeListener');
+    jest.spyOn(MmkvPersistentSessionsManager, 'fetchUserSession').mockReturnValue(null);
+    const storeSessionSpy = jest.spyOn(MmkvPersistentSessionsManager, 'storeUserSession').mockImplementation();
+    const manager = new MmkvPersistentSessionsManager();
+    const handler = addListenerSpy.mock.calls[0]?.[0];
+
+    expect(handler).toBeDefined();
+    faro.api.setSession({ id: 'before-cleanup' });
+    expect(storeSessionSpy).toHaveBeenCalled();
+    storeSessionSpy.mockClear();
+
+    manager.unpatch();
+    manager.unpatch();
+
+    expect(removeListenerSpy).toHaveBeenCalledTimes(1);
+    expect(removeListenerSpy).toHaveBeenCalledWith(handler);
+
+    faro.api.setSession({ id: 'after-cleanup' });
+    expect(storeSessionSpy).not.toHaveBeenCalled();
+  });
+
+  it('cleans up through destroy while a retained hook still enforces sampling', async () => {
+    const transport = new MockTransport();
+    const faro = initializeFaro(
+      mockConfig({
+        instrumentations: [],
+        transports: [transport],
+        url: 'http://localhost:12345/collect',
+        sessionTracking: { enabled: true, persistent: false },
+      })
+    );
+    const addListenerSpy = jest.spyOn(faro.metas, 'addListener');
+    const removeListenerSpy = jest.spyOn(faro.metas, 'removeListener');
+    const removeBeforeSendHooksSpy = jest.spyOn(faro.transports, 'removeBeforeSendHooks');
+    const instrumentation = new SessionInstrumentation();
+
+    faro.instrumentations.add(instrumentation);
+
+    const registeredListeners = addListenerSpy.mock.calls.map(([listener]) => listener);
+    expect(registeredListeners).toHaveLength(2);
+
+    const beforeSendHooks = faro.transports.getBeforeSendHooks();
+    expect(beforeSendHooks).toHaveLength(2);
+    const [fallbackHook, beforeSendHook] = beforeSendHooks;
+    if (fallbackHook == null || beforeSendHook == null) {
+      throw new Error('Expected the sampling fallback and session before-send hooks to be registered.');
+    }
+    expectSampledItem(beforeSendHook(sessionItem(true)));
+
+    const storedSession = VolatileSessionsManager.fetchUserSession();
+    if (storedSession == null) {
+      throw new Error('Expected an active volatile session before cleanup.');
+    }
+    const unsampledSession = {
+      ...storedSession,
+      isSampled: false,
+      sessionMeta: {
+        ...storedSession.sessionMeta,
+        id: storedSession.sessionId,
+        attributes: {
+          ...storedSession.sessionMeta?.attributes,
+          isSampled: 'false',
+        },
+      },
+    };
+    VolatileSessionsManager.storeUserSession(unsampledSession);
+    faro.api.setSession(unsampledSession.sessionMeta);
+    expect(faro.api.getSession()?.attributes?.['isSampled']).toBe('false');
+    const sessionStartsBeforeDestroy = sessionStartCount(transport);
+    instrumentation.destroy();
+
+    expect(removeListenerSpy).toHaveBeenCalledTimes(2);
+    expect(new Set(removeListenerSpy.mock.calls.map(([listener]) => listener))).toStrictEqual(
+      new Set(registeredListeners)
+    );
+    expect(removeBeforeSendHooksSpy).toHaveBeenCalledWith(beforeSendHook);
+    // A detached session hook must not rotate sessions, but a captured queued
+    // item still carries the sampling decision that the hook must enforce.
+    expect(beforeSendHook(sessionItem(false))).toBeNull();
+    expectSampledItem(beforeSendHook(sessionItem(true)));
+    expect(fallbackHook(sessionItem(false))).toBeNull();
+    expectSampledItem(fallbackHook(sessionItem(true)));
+
+    expect(faro.api.getSession()?.attributes?.['isSampled']).toBeUndefined();
+    const itemsAfterDestroy = transport.items.length;
+    faro.transports.execute(sessionItem(false));
+    expect(transport.items).toHaveLength(itemsAfterDestroy);
+    faro.transports.execute(sessionItem(true));
+    expect(transport.items).toHaveLength(itemsAfterDestroy + 1);
+    expect(transport.items.at(-1)?.meta.session?.attributes?.['isSampled']).toBeUndefined();
+
+    faro.api.pushEvent('after-destroy');
+    expect(transport.items.at(-1)?.payload).toEqual(expect.objectContaining({ name: 'after-destroy' }));
+    expect(transport.items.at(-1)?.meta.session?.attributes?.['isSampled']).toBeUndefined();
+
+    faro.api.setSession({ id: 'after-cleanup' });
+    expect(sessionStartCount(transport)).toBe(sessionStartsBeforeDestroy);
+
+    instrumentation.destroy();
+    expect(removeListenerSpy).toHaveBeenCalledTimes(2);
+    expect(removeBeforeSendHooksSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it.each([
+    ['sampled', 1, 1],
+    ['unsampled', 0, 0],
+  ] as const)('keeps teardown listener telemetry attributed for a %s session', async (_name, rate, expectedCount) => {
+    const transport = new MockTransport();
+    const faro = initializeFaro(
+      mockConfig({
+        instrumentations: [],
+        transports: [transport],
+        url: 'http://localhost:12345/collect',
+        view: { name: 'configured-view' },
+        sessionTracking: {
+          enabled: true,
+          persistent: false,
+          sampling: { resolve: () => rate },
+        },
+      })
+    );
+    const instrumentation = new SessionInstrumentation();
+    const checkSessionSpy = jest.spyOn(VolatileSessionsManager.prototype, 'checkSession');
+    faro.instrumentations.add(instrumentation);
+    faro.instrumentations.add(new ViewInstrumentation());
+    const storedSession = VolatileSessionsManager.fetchUserSession();
+    if (storedSession == null) {
+      throw new Error('Expected an active volatile session before cleanup.');
+    }
+    expect(storedSession.isSampled).toBe(rate === 1);
+    checkSessionSpy.mockClear();
+    const itemsBeforeDestroy = transport.items.length;
+
+    instrumentation.destroy();
+
+    expect(checkSessionSpy).not.toHaveBeenCalled();
+    const teardownItems = transport.items.slice(itemsBeforeDestroy);
+    const viewChangedItems = teardownItems.filter(
+      (item) => item.type === TransportItemType.EVENT && item.payload.name === EVENT_VIEW_CHANGED
+    );
+    expect(viewChangedItems).toHaveLength(expectedCount);
+    if (expectedCount === 1) {
+      expect(viewChangedItems[0]?.meta.session?.id).toBe(storedSession.sessionId);
+      expect(viewChangedItems[0]?.meta.session?.attributes?.['isSampled']).toBeUndefined();
+    }
+  });
+
+  it('finishes cleanup when a metas listener throws during the sampling scrub', async () => {
+    const faro = await initializeWithoutInstrumentations();
+    const instrumentation = new SessionInstrumentation();
+    const removeBeforeSendHooksSpy = jest.spyOn(faro.transports, 'removeBeforeSendHooks');
+    const checkSessionSpy = jest.spyOn(VolatileSessionsManager.prototype, 'checkSession');
+    faro.instrumentations.add(instrumentation);
+    const beforeSendHook = faro.transports.getBeforeSendHooks().at(-1);
+    if (beforeSendHook == null) {
+      throw new Error('Expected a session before-send hook before cleanup.');
+    }
+    const throwingListener = jest.fn((meta) => {
+      if (meta.session == null) {
+        throw new Error('metas listener failed');
+      }
+    });
+    faro.metas.addListener(throwingListener);
+
+    expect(() => instrumentation.destroy()).toThrow('metas listener failed');
+    expect(removeBeforeSendHooksSpy).toHaveBeenCalledTimes(1);
+    expect(removeBeforeSendHooksSpy).toHaveBeenCalledWith(beforeSendHook);
+
+    faro.metas.removeListener(throwingListener);
+    checkSessionSpy.mockClear();
+    faro.api.pushEvent('after-failed-cleanup');
+    expect(checkSessionSpy).not.toHaveBeenCalled();
+
+    expect(() => instrumentation.destroy()).not.toThrow();
+    expect(removeBeforeSendHooksSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it('binds a manager listener to the supplied metas instance', async () => {
+    const registeredFaro = await initializeWithoutInstrumentations();
+    const addListenerSpy = jest.spyOn(registeredFaro.metas, 'addListener');
+    const removeRegisteredListenerSpy = jest.spyOn(registeredFaro.metas, 'removeListener');
+    const replacementFaro = await initializeWithoutInstrumentations();
+    const addReplacementListenerSpy = jest.spyOn(replacementFaro.metas, 'addListener');
+    const removeReplacementListenerSpy = jest.spyOn(replacementFaro.metas, 'removeListener');
+    const manager = new VolatileSessionsManager(registeredFaro.metas);
+    const handler = addListenerSpy.mock.calls[0]?.[0];
+
+    manager.unpatch();
+
+    expect(addListenerSpy).toHaveBeenCalledWith(handler);
+    expect(addReplacementListenerSpy).not.toHaveBeenCalled();
+    expect(removeRegisteredListenerSpy).toHaveBeenCalledWith(handler);
+    expect(removeReplacementListenerSpy).not.toHaveBeenCalled();
+  });
+
+  it('binds a persistent manager listener to the supplied metas instance', async () => {
+    const registeredFaro = await initializeWithoutInstrumentations();
+    const addListenerSpy = jest.spyOn(registeredFaro.metas, 'addListener');
+    const removeRegisteredListenerSpy = jest.spyOn(registeredFaro.metas, 'removeListener');
+    const replacementFaro = await initializeWithoutInstrumentations();
+    const addReplacementListenerSpy = jest.spyOn(replacementFaro.metas, 'addListener');
+    const removeReplacementListenerSpy = jest.spyOn(replacementFaro.metas, 'removeListener');
+    jest.spyOn(MmkvPersistentSessionsManager, 'fetchUserSession').mockReturnValue(null);
+    jest.spyOn(MmkvPersistentSessionsManager, 'storeUserSession').mockImplementation();
+    const manager = new MmkvPersistentSessionsManager(registeredFaro.metas);
+    const handler = addListenerSpy.mock.calls[0]?.[0];
+
+    manager.unpatch();
+
+    expect(addListenerSpy).toHaveBeenCalledWith(handler);
+    expect(addReplacementListenerSpy).not.toHaveBeenCalled();
+    expect(removeRegisteredListenerSpy).toHaveBeenCalledWith(handler);
+    expect(removeReplacementListenerSpy).not.toHaveBeenCalled();
+  });
+
+  it('moves every registration when an instrumentation instance is reused', async () => {
+    const instrumentation = new SessionInstrumentation();
+    const firstTransport = new MockTransport();
+    const firstFaro = initializeFaro(
+      mockConfig({
+        instrumentations: [],
+        transports: [firstTransport],
+        url: 'http://localhost:12345/collect',
+        sessionTracking: { enabled: true, persistent: false },
+      })
+    );
+    const firstRemoveListenerSpy = jest.spyOn(firstFaro.metas, 'removeListener');
+    const firstRemoveBeforeSendHooksSpy = jest.spyOn(firstFaro.transports, 'removeBeforeSendHooks');
+    const firstSetSessionSpy = jest.spyOn(firstFaro.api, 'setSession');
+    firstFaro.instrumentations.add(instrumentation);
+    const firstHook = firstFaro.transports.getBeforeSendHooks().at(-1);
+    if (firstHook == null) {
+      throw new Error('Expected the first Faro instance to retain its session hook.');
+    }
+
+    const secondTransport = new MockTransport();
+    const secondFaro = initializeFaro(
+      mockConfig({
+        instrumentations: [],
+        transports: [secondTransport],
+        url: 'http://localhost:12345/collect',
+        sessionTracking: { enabled: true, persistent: false },
+      })
+    );
+    const secondAddListenerSpy = jest.spyOn(secondFaro.metas, 'addListener');
+    const secondRemoveListenerSpy = jest.spyOn(secondFaro.metas, 'removeListener');
+    secondFaro.instrumentations.add(instrumentation);
+
+    expect(firstRemoveListenerSpy).toHaveBeenCalledTimes(2);
+    expect(firstRemoveBeforeSendHooksSpy).toHaveBeenCalledWith(firstHook);
+    expect(firstSetSessionSpy).toHaveBeenCalledWith(
+      expect.objectContaining({
+        attributes: expect.not.objectContaining({ isSampled: expect.anything() }),
+      })
+    );
+    expect(secondAddListenerSpy).toHaveBeenCalledTimes(2);
+    const firstHookResult = expectSampledItem(firstHook(sessionItem(true)));
+    expect(firstHookResult.meta.session?.id).toBe('active-session');
+
+    const secondSessionStarts = sessionStartCount(secondTransport);
+    firstFaro.api.setSession({ id: 'stale-faro-session' });
+    expect(sessionStartCount(secondTransport)).toBe(secondSessionStarts);
+
+    secondFaro.api.setSession({ id: 'active-faro-session' });
+    expect(sessionStartCount(secondTransport)).toBe(secondSessionStarts + 1);
+
+    instrumentation.destroy();
+    expect(secondRemoveListenerSpy).toHaveBeenCalledTimes(2);
+
+    secondFaro.api.setSession({ id: 'after-destroy' });
+    expect(sessionStartCount(secondTransport)).toBe(secondSessionStarts + 1);
+  });
+
+  it('lets a replacement hook reattribute items retained by an older Faro Core', async () => {
+    const faro = await initializeWithoutInstrumentations();
+    const firstInstrumentation = new SessionInstrumentation();
+    faro.instrumentations.add(firstInstrumentation);
+    const firstHook = faro.transports.getBeforeSendHooks().at(-1);
+    if (firstHook == null) {
+      throw new Error('Expected the first instrumentation to register a session hook.');
+    }
+
+    faro.instrumentations.remove(firstInstrumentation);
+    expect(faro.instrumentations.instrumentations).not.toContain(firstInstrumentation);
+    expect(faro.instrumentations.instrumentations).toHaveLength(0);
+
+    const replacementInstrumentation = new SessionInstrumentation();
+    faro.instrumentations.add(replacementInstrumentation);
+    expect(faro.instrumentations.instrumentations).toContain(replacementInstrumentation);
+
+    const activeSession = VolatileSessionsManager.fetchUserSession();
+    if (activeSession == null) {
+      throw new Error('Expected the replacement instrumentation to own a session.');
+    }
+
+    const installedHooks = faro.transports.getBeforeSendHooks();
+    const hooks = installedHooks.includes(firstHook) ? installedHooks : [firstHook, ...installedHooks];
+    const result = hooks.reduce<TransportItem | null>(
+      (item, hook) => (item == null ? null : hook(item)),
+      sessionItem(false)
+    );
+    const sampledResult = expectSampledItem(result);
+
+    expect(sampledResult.meta.session?.id).toBe(activeSession.sessionId);
+    replacementInstrumentation.destroy();
+  });
+
+  it('registers its manager listener on the instrumentation metas instance', async () => {
+    const ownerFaro = await initializeWithoutInstrumentations();
+    const ownerAddListenerSpy = jest.spyOn(ownerFaro.metas, 'addListener');
+    const otherFaro = await initializeWithoutInstrumentations();
+    const otherAddListenerSpy = jest.spyOn(otherFaro.metas, 'addListener');
+    const instrumentation = new SessionInstrumentation();
+
+    ownerFaro.instrumentations.add(instrumentation);
+
+    expect(ownerAddListenerSpy).toHaveBeenCalledTimes(2);
+    expect(otherAddListenerSpy).not.toHaveBeenCalled();
+
+    instrumentation.destroy();
+  });
+});