@luciq/react-native 19.4.0 → 19.6.0-51917-SNAPSHOT

package/src/components/LuciqCaptureScreenLoading.tsx

@@ -0,0 +1,210 @@
+import React, { useState, useRef, useEffect, useLayoutEffect, useContext } from 'react';
+import { View, ViewProps } from 'react-native';
+import { ScreenLoadingManager } from '../modules/apm/ScreenLoadingManager';
+import { Logger } from '../utils/logger';
+import { nowMicros, toEpochMicros } from '../utils/LuciqUtils';
+
+// Context to handle nested components
+const ScreenLoadingContext = React.createContext<boolean>(false);
+
+export interface LuciqScreenLoadingProps extends ViewProps {
+  screenName: string;
+  record?: boolean;
+  onMeasured?: (ttid: number) => void;
+}
+
+export function LuciqCaptureScreenLoading(props: LuciqScreenLoadingProps) {
+  const { screenName, record, onMeasured, onLayout, children, ...viewProps } = props;
+
+  const isNested = useContext(ScreenLoadingContext);
+
+  // Refs for timestamps (these don't need to trigger re-renders)
+  const constructorTimestampRef = useRef<number>(nowMicros()); // microseconds
+  const renderStartTimestampRef = useRef<number | undefined>(undefined);
+  const renderEndTimestampRef = useRef<number | undefined>(undefined);
+  const mountTimestampRef = useRef<number | undefined>(undefined);
+
+  // Guards to ensure single execution
+  const initializedRef = useRef(false);
+  const hasFirstRenderCompletedRef = useRef(false);
+  const attributesRecordedRef = useRef(false);
+  const initialSpanIdRef = useRef<string | null>(null);
+
+  // Capture render start timestamp ONLY on first render
+  if (!hasFirstRenderCompletedRef.current) {
+    renderStartTimestampRef.current = nowMicros();
+  }
+
+  // Initialize span - runs once like constructor (lazy initialization)
+  if (!initializedRef.current) {
+    initializedRef.current = true;
+    // Initialize span if conditions are met
+    try {
+      if (record !== false && ScreenLoadingManager.isFeatureEnabled()) {
+        const span = ScreenLoadingManager.createSpan(
+          screenName,
+          true,
+          constructorTimestampRef.current,
+        );
+        if (span) {
+          initialSpanIdRef.current = span.spanId;
+          Logger.log(`[LuciqScreenLoading] Span ${span.spanId} created in constructor`);
+        }
+      }
+    } catch (error) {
+      Logger.error('[LuciqScreenLoading] Failed to create span:', error);
+    }
+  }
+
+  const [spanId, setSpanId] = useState<string | null>(initialSpanIdRef.current);
+  const [isMeasured, setIsMeasured] = useState(false);
+
+  // Ref to avoid stale closure in useLayoutEffect
+  const onMeasuredRef = useRef(onMeasured);
+  useEffect(() => {
+    onMeasuredRef.current = onMeasured;
+  }, [onMeasured]);
+
+  // Refs to track latest values for cleanup (componentWillUnmount)
+  const spanIdRef = useRef<string | null>(spanId);
+  const isMeasuredRef = useRef(isMeasured);
+
+  // Keep refs in sync with state
+  useEffect(() => {
+    spanIdRef.current = spanId;
+  }, [spanId]);
+
+  useEffect(() => {
+    isMeasuredRef.current = isMeasured;
+  }, [isMeasured]);
+
+  // Handle nested component detection
+  useEffect(() => {
+    // Check if we're nested and should ignore this component
+    if (isNested && initialSpanIdRef.current) {
+      Logger.log(
+        `[LuciqScreenLoading] Nested component detected, ignoring span ${initialSpanIdRef.current}`,
+      );
+      // Cancel the span
+      setSpanId(null);
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []); // Empty deps = componentDidMount
+
+  // Record lifecycle timestamps after first render completes (synchronous)
+  // useLayoutEffect fires synchronously after DOM mutations but before browser paint
+  useLayoutEffect(() => {
+    // Skip if no span, already recorded, or nested
+    if (!spanId || attributesRecordedRef.current || isNested) {
+      return;
+    }
+
+    // endSpan is async (native frame timestamp fetch), fire-and-forget from useLayoutEffect
+    ScreenLoadingManager.endSpan(spanId)
+      .then(() => {
+        const completedSpan = ScreenLoadingManager.getActiveSpan(spanId);
+        if (completedSpan?.ttid && onMeasuredRef.current) {
+          onMeasuredRef.current(completedSpan.ttid / 1000);
+        }
+      })
+      .catch((error) => {
+        Logger.warn('[LuciqScreenLoading] Failed to end span:', error);
+      });
+
+    attributesRecordedRef.current = true;
+    mountTimestampRef.current = nowMicros();
+
+    try {
+      // Record all timestamps
+      ScreenLoadingManager.addSpanAttribute(
+        spanId,
+        'cnst_mus_st',
+        toEpochMicros(constructorTimestampRef.current),
+      );
+
+      if (renderStartTimestampRef.current) {
+        ScreenLoadingManager.addSpanAttribute(
+          spanId,
+          'rnd_mus_st',
+          toEpochMicros(renderStartTimestampRef.current),
+        );
+      }
+
+      ScreenLoadingManager.addSpanAttribute(
+        spanId,
+        'mnt_mus_st',
+        toEpochMicros(mountTimestampRef.current),
+      );
+
+      // Record all durations
+      if (renderStartTimestampRef.current) {
+        // Constructor duration: time from component init to first render start
+        const constructorDuration =
+          renderStartTimestampRef.current - constructorTimestampRef.current;
+        ScreenLoadingManager.addSpanAttribute(spanId, 'cnst_mus', constructorDuration);
+      }
+
+      if (renderEndTimestampRef.current && renderStartTimestampRef.current) {
+        // Render duration: time spent creating JSX
+        const renderDuration = renderEndTimestampRef.current - renderStartTimestampRef.current;
+        ScreenLoadingManager.addSpanAttribute(spanId, 'rnd_mus', renderDuration);
+      }
+
+      if (mountTimestampRef.current && renderEndTimestampRef.current) {
+        // Mount duration: time from render complete to effect execution
+        const mountDuration = mountTimestampRef.current - renderEndTimestampRef.current;
+        ScreenLoadingManager.addSpanAttribute(spanId, 'mnt_mus', mountDuration);
+      }
+
+      Logger.log(`[LuciqScreenLoading] Lifecycle measurements for span ${spanId}:`, {
+        constructor_us: renderStartTimestampRef.current
+          ? renderStartTimestampRef.current - constructorTimestampRef.current
+          : undefined,
+        render_us:
+          renderEndTimestampRef.current && renderStartTimestampRef.current
+            ? renderEndTimestampRef.current - renderStartTimestampRef.current
+            : undefined,
+        mount_us:
+          mountTimestampRef.current && renderEndTimestampRef.current
+            ? mountTimestampRef.current - renderEndTimestampRef.current
+            : undefined,
+      });
+    } catch (error) {
+      Logger.error(`[LuciqScreenLoading] Failed to record attributes for span ${spanId}:`, error);
+    }
+
+    // End the span — mark as measured synchronously to guard against unmount race
+    setIsMeasured(true);
+
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [spanId]); // Run when spanId is set
+
+  // componentWillUnmount equivalent
+  useEffect(() => {
+    return () => {
+      // Cleanup on unmount if not measured
+      if (spanIdRef.current && !isMeasuredRef.current) {
+        ScreenLoadingManager.endSpan(spanIdRef.current).catch((error) => {
+          Logger.warn('[LuciqScreenLoading] Failed to end span on unmount:', error);
+        });
+      }
+    };
+  }, []); // Empty deps = only runs cleanup on unmount
+
+  // Create the JSX result
+  const result = (
+    <ScreenLoadingContext.Provider value={spanId !== null}>
+      <View {...viewProps} onLayout={onLayout}>
+        {children}
+      </View>
+    </ScreenLoadingContext.Provider>
+  );
+
+  // Capture render end timestamp ONLY on first render (after JSX creation)
+  if (!hasFirstRenderCompletedRef.current) {
+    renderEndTimestampRef.current = nowMicros();
+    hasFirstRenderCompletedRef.current = true;
+  }
+
+  return result;
+}

package/src/index.ts

@@ -45,4 +45,8 @@ export type {
   ThemeConfig,
 };
 
+// Screen Loading Component
+export { LuciqCaptureScreenLoading } from './components/LuciqCaptureScreenLoading';
+export type { LuciqScreenLoadingProps } from './components/LuciqCaptureScreenLoading';
+
 export default Luciq;

package/src/modules/APM.ts

@@ -7,6 +7,13 @@ import {
   addCompletedCustomSpan as addCompletedCustomSpanInternal,
 } from '../utils/CustomSpansManager';
 import type { CustomSpan } from '../models/CustomSpan';
+import { ScreenLoadingManager } from './apm/ScreenLoadingManager';
+import { Logger } from '../utils/logger';
+
+// Initialize Screen Loading on module load
+ScreenLoadingManager.initialize().catch((error) => {
+  Logger.error('[APM] Failed to initialize Screen Loading:', error);
+});
 
 /**
  * Enables or disables APM
@@ -195,3 +202,38 @@ export const addCompletedCustomSpan = async (
 ): Promise<void> => {
   return addCompletedCustomSpanInternal(name, startDate, endDate);
 };
+
+/**
+ * Enables or disables Screen Loading feature
+ * @param isEnabled
+ */
+export const setScreenLoadingEnabled = (isEnabled: boolean) => {
+  try {
+    NativeAPM.setScreenLoadingEnabled(isEnabled);
+  } catch (error) {
+    Logger.error('[APM] Failed to set screen loading enabled:', error);
+  }
+};
+
+/**
+ * Extends the currently running screen loading trace with a new end timestamp.
+ */
+export const endScreenLoading = () => {
+  ScreenLoadingManager.endScreenLoading();
+};
+
+/**
+ * Exclude specific routes from automatic screen loading measurement
+ * @param routes Array of route names to exclude
+ */
+export function excludeScreenLoadingRoutes(routes: string[]): void {
+  ScreenLoadingManager.excludeRoutes(routes);
+}
+
+/**
+ * Include previously excluded routes back into screen loading measurement
+ * @param routes Array of route names to include (or empty to clear all exclusions)
+ */
+export function includeScreenLoadingRoutes(routes?: string[]): void {
+  ScreenLoadingManager.includeRoutes(routes);
+}

package/src/modules/Luciq.ts

@@ -10,7 +10,7 @@ import type { NavigationAction, NavigationState as NavigationStateV4 } from 'rea
 import type { LuciqConfig } from '../models/LuciqConfig';
 import Report from '../models/Report';
 import { emitter, NativeEvents, NativeLuciq } from '../native/NativeLuciq';
-import { registerFeatureFlagsListener } from '../utils/FeatureFlags';
+import { registerFeatureFlagsListener, initFeatureFlagsCache } from '../utils/FeatureFlags';
 import {
   AutoMaskingType,
   ColorTheme,
@@ -29,6 +29,7 @@ import LuciqUtils, {
 } from '../utils/LuciqUtils';
 import * as NetworkLogger from './NetworkLogger';
 import { captureUnhandledRejections } from '../utils/UnhandledRejectionTracking';
+import { ScreenLoadingManager } from './apm/ScreenLoadingManager';
 import type { ReproConfig } from '../models/ReproConfig';
 import type { FeatureFlag } from '../models/FeatureFlag';
 import { addAppStateListener } from '../utils/AppStatesHandler';
@@ -48,6 +49,13 @@ let isNativeInterceptionFeatureEnabled = false; // Checks the value of "cp_nativ
 let hasAPMNetworkPlugin = false; // Android only: checks if the APM plugin is installed.
 let shouldEnableNativeInterception = false; // For Android: used to disable APM logging inside reportNetworkLog() -> NativeAPM.networkLogAndroid(), For iOS: used to control native interception (true == enabled , false == disabled)
 
+// Screen Loading tracking variables
+let _navigationRef: NavigationContainerRefWithCurrent<ReactNavigation.RootParamList> | null = null;
+let _currentRoute: string | null = null;
+let _activeNavigationSpanId: string | null = null;
+let _stateChangeTimeout: ReturnType<typeof setTimeout> | undefined;
+const STATE_CHANGE_TIMEOUT_MS = 2000; // Safety timeout if state never changes
+
 /**
  * Enables or disables Luciq functionality.
  * @param isEnabled A boolean to enable/disable Luciq.
@@ -81,10 +89,22 @@ function reportCurrentViewForAndroid(screenName: string | null) {
  * @param config SDK configurations. See {@link LuciqConfig} for more info.
  */
 export const init = (config: LuciqConfig) => {
+  initFeatureFlagsCache();
+
   if (Platform.OS === 'android') {
     // Add android feature flags listener for android
     registerFeatureFlagsListener();
     addOnFeatureUpdatedListener(config);
+
+    // Enable the JS XHR interceptor synchronously so cold-start requests
+    // (fired before LCQ_ON_FEATURES_UPDATED_CALLBACK arrives) are captured.
+    handleNetworkInterceptionMode(config);
+
+    setApmNetworkFlagsIfChanged({
+      isNativeInterceptionFeatureEnabled: isNativeInterceptionFeatureEnabled,
+      hasAPMNetworkPlugin: hasAPMNetworkPlugin,
+      shouldEnableNativeInterception: shouldEnableNativeInterception,
+    });
   } else {
     isNativeInterceptionFeatureEnabled = NativeNetworkLogger.isNativeInterceptionEnabled();
 
@@ -116,7 +136,7 @@ export const init = (config: LuciqConfig) => {
   reportCurrentViewForAndroid(firstScreen);
   setTimeout(() => {
     if (_currentScreen === firstScreen) {
-      NativeLuciq.reportScreenChange(firstScreen);
+      NativeLuciq.reportScreenChange(firstScreen, null);
       _currentScreen = null;
     }
   }, 1000);
@@ -158,12 +178,14 @@ export const setWebViewUserInteractionsTrackingEnabled = (isEnabled: boolean) =>
  * Handles app state changes and updates APM network flags if necessary.
  */
 const handleAppStateChange = async (nextAppState: AppStateStatus, config: LuciqConfig) => {
-  // Checks if  the app has come to the foreground
+  // Checks if the app has come to the foreground
   if (['inactive', 'background'].includes(_currentAppState) && nextAppState === 'active') {
     const isUpdated = await fetchApmNetworkFlags();
     if (isUpdated) {
       refreshAPMNetworkConfigs(config);
     }
+    // Refresh screen loading flags from native
+    await ScreenLoadingManager.refreshFlags();
   }
 
   _currentAppState = nextAppState;
@@ -756,6 +778,139 @@ export const onReportSubmitHandler = (handler?: (report: Report) => void) => {
   NativeLuciq.setPreSendingHandler(handler);
 };
 
+/**
+ * Helper to clear the state change timeout
+ */
+const _clearStateChangeTimeout = (): void => {
+  if (_stateChangeTimeout) {
+    clearTimeout(_stateChangeTimeout);
+    _stateChangeTimeout = undefined;
+  }
+};
+
+/**
+ * Handles React Navigation's __unsafe_action__ event
+ * This fires WHEN a navigation action is dispatched (the start of navigation)
+ */
+const _onNavigationAction = (event?: any): void => {
+  // Check for noop actions that shouldn't create spans
+  if (event?.data?.noop) {
+    Logger.log('[ScreenLoading] Navigation action is a noop, not starting span');
+    return;
+  }
+
+  // Skip non-navigation actions (like SET_PARAMS, OPEN_DRAWER, etc.)
+  const actionType = event?.data?.action?.type;
+  if (
+    actionType &&
+    ['SET_PARAMS', 'OPEN_DRAWER', 'CLOSE_DRAWER', 'TOGGLE_DRAWER'].includes(actionType)
+  ) {
+    Logger.log(`[ScreenLoading] Skipping non-navigation action: ${actionType}`);
+    return;
+  }
+
+  // If there's an existing active span, it means navigation was interrupted
+  // Discard the previous span as it never completed
+  if (_activeNavigationSpanId) {
+    Logger.log('[ScreenLoading] Discarding incomplete previous navigation span');
+    // Mark the span as cancelled/error since state change never occurred
+    const span = ScreenLoadingManager.getActiveSpan(_activeNavigationSpanId);
+    if (span) {
+      ScreenLoadingManager.endSpan(_activeNavigationSpanId);
+    }
+    _activeNavigationSpanId = null;
+    _clearStateChangeTimeout();
+  }
+
+  // Create a new span for this navigation action
+  // We don't know the destination screen yet, so use a placeholder name
+  if (ScreenLoadingManager.isFeatureEnabled()) {
+    const span = ScreenLoadingManager.createSpan('NavigationPending', false);
+    if (span) {
+      _activeNavigationSpanId = span.spanId;
+      Logger.log(`[ScreenLoading] Started span ${span.spanId} on navigation dispatch`);
+
+      // Set a safety timeout to discard the span if state never changes
+      // This prevents memory leaks from incomplete navigations
+      _stateChangeTimeout = setTimeout(() => {
+        if (_activeNavigationSpanId === span.spanId) {
+          Logger.warn(
+            `[ScreenLoading] Navigation span ${span.spanId} timed out - state never changed`,
+          );
+          ScreenLoadingManager.endSpan(span.spanId);
+          _activeNavigationSpanId = null;
+        }
+      }, STATE_CHANGE_TIMEOUT_MS);
+    }
+  }
+};
+
+/**
+ * Handles React Navigation's state event
+ * This fires AFTER the navigation state has changed (the screen is mounted)
+ */
+const _onNavigationStateChange = (): void => {
+  if (!_navigationRef?.current) {
+    return;
+  }
+
+  const previousRouteName = _currentRoute;
+  const currentRoute = _navigationRef.current.getCurrentRoute();
+  const currentRouteName = currentRoute?.name || null;
+
+  // If no route or same route, ignore
+  if (!currentRouteName || previousRouteName === currentRouteName) {
+    // Still need to clean up the span if one was created
+    if (_activeNavigationSpanId) {
+      Logger.log('[ScreenLoading] Navigation resulted in same route, discarding span');
+      ScreenLoadingManager.endSpan(_activeNavigationSpanId);
+      _activeNavigationSpanId = null;
+      _clearStateChangeTimeout();
+    }
+    return;
+  }
+
+  // Capture the span ID BEFORE clearing it so we can pass it to reportScreenChange
+  let spanIdForReport: string | null = _activeNavigationSpanId;
+
+  // Complete the active navigation span if one exists
+  if (_activeNavigationSpanId) {
+    // Now that we know the actual route name, check if it's excluded
+    if (ScreenLoadingManager.isRouteExcluded(currentRouteName)) {
+      Logger.log(`[ScreenLoading] Route "${currentRouteName}" is excluded, discarding span`);
+      ScreenLoadingManager.discardSpan(_activeNavigationSpanId);
+      spanIdForReport = null;
+      _activeNavigationSpanId = null;
+      _clearStateChangeTimeout();
+    } else {
+      const span = ScreenLoadingManager.getActiveSpan(_activeNavigationSpanId);
+      if (span) {
+        // Update the span name from placeholder to actual screen name
+        span.screenName = currentRouteName;
+
+        // End the span - the native frame tracker will provide the actual render timestamp
+        ScreenLoadingManager.endSpan(_activeNavigationSpanId)
+          .then(() => {
+            Logger.log(`[ScreenLoading] Completed span for navigation to ${currentRouteName}`);
+          })
+          .catch((error) => {
+            Logger.warn('[ScreenLoading] Failed to end navigation span:', error);
+          });
+      }
+
+      // Clear the active span and timeout
+      _activeNavigationSpanId = null;
+      _clearStateChangeTimeout();
+    }
+  }
+
+  // Update the current route for the rest of Luciq's tracking
+  _currentRoute = currentRouteName;
+
+  // Report to native
+  NativeLuciq.reportScreenChange(currentRouteName, spanIdForReport);
+};
+
 export const onNavigationStateChange = (
   prevState: NavigationStateV4,
   currentState: NavigationStateV4,
@@ -765,17 +920,33 @@ export const onNavigationStateChange = (
   const prevScreen = LuciqUtils.getActiveRouteName(prevState);
 
   if (prevScreen !== currentScreen) {
+    // Start Screen Loading measurement for v4
+    let screenLoadingSpanId: string | null = null;
+    if (ScreenLoadingManager.isFeatureEnabled()) {
+      const span = ScreenLoadingManager.createSpan(currentScreen || 'Unknown', false);
+      if (span) {
+        screenLoadingSpanId = span.spanId;
+      }
+    }
+
     reportCurrentViewForAndroid(currentScreen);
     if (_currentScreen != null && _currentScreen !== firstScreen) {
-      NativeLuciq.reportScreenChange(_currentScreen);
+      NativeLuciq.reportScreenChange(_currentScreen, screenLoadingSpanId);
       _currentScreen = null;
     }
     _currentScreen = currentScreen;
     setTimeout(() => {
       if (currentScreen && _currentScreen === currentScreen) {
-        NativeLuciq.reportScreenChange(currentScreen);
+        NativeLuciq.reportScreenChange(currentScreen, screenLoadingSpanId);
         _currentScreen = null;
       }
+
+      // End Screen Loading measurement for v4
+      if (screenLoadingSpanId) {
+        ScreenLoadingManager.endSpan(screenLoadingSpanId).catch((error) => {
+          Logger.warn('[ScreenLoading] Failed to end span:', error);
+        });
+      }
     }, 1000);
   }
 };
@@ -785,17 +956,28 @@ export const onStateChange = (state?: NavigationStateV5) => {
     return;
   }
 
+  // Delegate to the new state change handler for Screen Loading
+  // This handles reportScreenChange when setNavigationListener was called
+  _onNavigationStateChange();
+
+  // When setNavigationListener is used, _onNavigationStateChange already handles
+  // reportScreenChange properly - skip legacy logic to avoid duplicate calls
+  if (_navigationRef?.current) {
+    return;
+  }
+
+  // Fallback: Legacy screen tracking for users who only use onStateChange without setNavigationListener
   const currentScreen = LuciqUtils.getFullRoute(state);
   reportCurrentViewForAndroid(currentScreen);
   if (_currentScreen !== null && _currentScreen !== firstScreen) {
-    NativeLuciq.reportScreenChange(_currentScreen);
+    NativeLuciq.reportScreenChange(_currentScreen, null);
     _currentScreen = null;
   }
 
   _currentScreen = currentScreen;
   setTimeout(() => {
     if (_currentScreen === currentScreen) {
-      NativeLuciq.reportScreenChange(currentScreen);
+      NativeLuciq.reportScreenChange(currentScreen, null);
       _currentScreen = null;
     }
   }, 1000);
@@ -809,13 +991,29 @@ export const onStateChange = (state?: NavigationStateV5) => {
 export const setNavigationListener = (
   navigationRef: NavigationContainerRefWithCurrent<ReactNavigation.RootParamList>,
 ) => {
-  return navigationRef.addListener('state', () => {
-    onStateChange(navigationRef.getRootState());
-  });
+  // Store the navigationRef for Screen Loading tracking
+  _navigationRef = navigationRef;
+
+  if (!navigationRef?.current) {
+    Logger.warn('[Luciq] Navigation ref not available, cannot set listeners');
+    return;
+  }
+
+  // Register the __unsafe_action__ listener for span creation
+  // This listener fires on navigation dispatch (start of navigation)
+  navigationRef.current.addListener('__unsafe_action__', _onNavigationAction);
+
+  // NOTE: We do NOT register a 'state' listener here because the user is expected
+  // to pass Luciq.onStateChange to NavigationContainer's onStateChange prop.
+  // Registering both would cause duplicate reportScreenChange calls.
+
+  Logger.log('[Luciq] Registered Screen Loading listener (__unsafe_action__)');
+
+  // return stateListener;
 };
 
 export const reportScreenChange = (screenName: string) => {
-  NativeLuciq.reportScreenChange(screenName);
+  NativeLuciq.reportScreenChange(screenName, null);
 };
 
 /**
@@ -879,7 +1077,7 @@ export const componentDidAppearListener = (event: ComponentDidAppearEvent) => {
     return;
   }
   if (_lastScreen !== event.componentName) {
-    NativeLuciq.reportScreenChange(event.componentName);
+    NativeLuciq.reportScreenChange(event.componentName, null);
     _lastScreen = event.componentName;
   }
 };

package/src/modules/NetworkLogger.ts

@@ -39,10 +39,17 @@ function getPortFromUrl(url: string) {
  * It is enabled by default.
  * @param isEnabled
  */
+const NET_TAG = 'LCQ-RN-NET:';
+
 export const setEnabled = (isEnabled: boolean) => {
   if (isEnabled) {
     xhr.enableInterception();
     xhr.setOnDoneCallback(async (network) => {
+      Logger.debug(
+        NET_TAG,
+        `[NetworkLogger] onDoneCallback received: ${network.method} ${network.url}, status=${network.responseCode}`,
+      );
+
       // eslint-disable-next-line no-new-func
       const predicate = Function('network', 'return ' + _requestFilterExpression);
 
@@ -50,12 +57,17 @@ export const setEnabled = (isEnabled: boolean) => {
         const MAX_NETWORK_BODY_SIZE_IN_BYTES = await NativeLuciq.getNetworkBodyMaxSize();
         try {
           if (_networkDataObfuscationHandler) {
+            Logger.debug(NET_TAG, `[NetworkLogger] Running obfuscation handler for ${network.url}`);
             network = await _networkDataObfuscationHandler(network);
           }
 
           if (__DEV__) {
             const urlPort = getPortFromUrl(network.url);
             if (urlPort === LuciqRNConfig.metroDevServerPort) {
+              Logger.debug(
+                NET_TAG,
+                `[NetworkLogger] Skipping Metro dev server request: ${network.url}`,
+              );
               return;
             }
           }
@@ -97,10 +109,23 @@ export const setEnabled = (isEnabled: boolean) => {
             );
           }
 
+          Logger.debug(
+            NET_TAG,
+            `[NetworkLogger] Reporting network log to native: ${network.method} ${network.url}`,
+          );
           reportNetworkLog(network);
         } catch (e) {
-          Logger.error(e);
+          Logger.error(
+            NET_TAG,
+            `[NetworkLogger] Error processing network log for ${network.url}:`,
+            e,
+          );
         }
+      } else {
+        Logger.debug(
+          NET_TAG,
+          `[NetworkLogger] Request filtered out by predicate: ${network.method} ${network.url}, expression="${_requestFilterExpression}"`,
+        );
       }
     });
   } else {