@luciq/react-native 19.4.0 → 19.6.0

package/ios/RNLuciq/LuciqScreenLoadingFrameTracker.m

@@ -0,0 +1,121 @@
+#import "LuciqScreenLoadingFrameTracker.h"
+#import <QuartzCore/CADisplayLink.h>
+
+@interface LuciqScreenLoadingFrameTracker ()
+@property (nonatomic, strong) NSMutableDictionary<NSString *, NSNumber *> *spanIdToTimestamp;
+@property (nonatomic, strong) NSMutableSet<NSString *> *activeSpanIds;
+@property (nonatomic, strong) NSMutableDictionary<NSString *, NSNumber *> *spanIdToTrackingStart;
+@property (nonatomic, assign) NSInteger maxStorageCapacity;
+@property (nonatomic, assign) BOOL isTracking;
+@property (nonatomic, strong) CADisplayLink *displayLink;
+@end
+
+@implementation LuciqScreenLoadingFrameTracker
+
++ (instancetype)sharedInstance {
+    static LuciqScreenLoadingFrameTracker *instance = nil;
+    static dispatch_once_t onceToken;
+    dispatch_once(&onceToken, ^{
+        instance = [[self alloc] init];
+    });
+    return instance;
+}
+
+- (instancetype)init {
+    if (self = [super init]) {
+        self.spanIdToTimestamp = [NSMutableDictionary dictionary];
+        self.activeSpanIds = [NSMutableSet set];
+        self.spanIdToTrackingStart = [NSMutableDictionary dictionary];
+        self.maxStorageCapacity = 50;
+        self.isTracking = NO;
+    }
+    return self;
+}
+
+- (void)initializeFrameTracking {
+    if (self.isTracking) {
+        return;
+    }
+
+    self.displayLink = [CADisplayLink displayLinkWithTarget:self selector:@selector(handleDisplayLink:)];
+    [self.displayLink addToRunLoop:[NSRunLoop mainRunLoop] forMode:NSRunLoopCommonModes];
+    self.isTracking = YES;
+}
+
+- (void)handleDisplayLink:(CADisplayLink *)displayLink {
+    [self frameRenderedWithTimestamp:displayLink.timestamp];
+}
+
+- (void)frameRenderedWithTimestamp:(NSTimeInterval)timestamp {
+    if (self.activeSpanIds.count > 0) {
+        // timestamp is monotonic (seconds since boot, from CADisplayLink / mach_absolute_time)
+        // Convert to epoch microseconds using the same approach as Android:
+        // figure out how long ago the frame was rendered, then subtract from current epoch
+        NSTimeInterval currentUptime = [[NSProcessInfo processInfo] systemUptime];
+        NSTimeInterval currentEpoch = [[NSDate date] timeIntervalSince1970];
+        NSTimeInterval timeSinceFrame = currentUptime - timestamp;
+        NSTimeInterval frameEpochSeconds = currentEpoch - timeSinceFrame;
+        NSTimeInterval epochTimestampMicroseconds = frameEpochSeconds * 1000000;
+        NSNumber *timestampNumber = @(epochTimestampMicroseconds);
+
+        NSMutableSet<NSString *> *resolvedSpanIds = [NSMutableSet set];
+        for (NSString *spanId in self.activeSpanIds) {
+            NSNumber *trackingStart = self.spanIdToTrackingStart[spanId];
+            if (trackingStart && timestamp < trackingStart.doubleValue) {
+                NSLog(@"[ScreenLoading] Skipping frame for span %@ (VSync %.6fs < tracking start %.6fs)", spanId, timestamp, trackingStart.doubleValue);
+                continue;
+            }
+            self.spanIdToTimestamp[spanId] = timestampNumber;
+            [resolvedSpanIds addObject:spanId];
+            [self.spanIdToTrackingStart removeObjectForKey:spanId];
+            NSLog(@"[ScreenLoading] Frame rendered for span %@ at %.0fμs", spanId, epochTimestampMicroseconds);
+        }
+        [self.activeSpanIds minusSet:resolvedSpanIds];
+
+        // Cleanup if exceeding capacity
+        if (self.spanIdToTimestamp.count > self.maxStorageCapacity) {
+            [self cleanupStorage];
+        }
+    }
+}
+
+- (void)startTrackingForSpanId:(NSString *)spanId {
+    [self.activeSpanIds addObject:spanId];
+    self.spanIdToTrackingStart[spanId] = @([[NSProcessInfo processInfo] systemUptime]);
+    NSLog(@"[ScreenLoading] Started tracking for span %@", spanId);
+}
+
+- (NSNumber *)getFrameTimestampForSpanId:(NSString *)spanId {
+    NSNumber *timestamp = self.spanIdToTimestamp[spanId];
+    if (timestamp) {
+        [self.spanIdToTimestamp removeObjectForKey:spanId];
+        NSLog(@"[ScreenLoading] Retrieved timestamp %@μs for span %@", timestamp, spanId);
+    }
+    return timestamp;
+}
+
+- (void)cleanup {
+    if (self.isTracking) {
+        [self.displayLink invalidate];
+        self.displayLink = nil;
+        self.isTracking = NO;
+    }
+    [self.spanIdToTimestamp removeAllObjects];
+    [self.activeSpanIds removeAllObjects];
+}
+
+- (void)cleanupStorage {
+    NSArray *sortedKeys = [self.spanIdToTimestamp keysSortedByValueUsingComparator:^NSComparisonResult(NSNumber *obj1, NSNumber *obj2) {
+        return [obj1 compare:obj2];
+    }];
+
+    NSInteger itemsToRemove = self.spanIdToTimestamp.count - 30;
+    if (itemsToRemove > 0) {
+        for (NSInteger i = 0; i < itemsToRemove; i++) {
+            [self.spanIdToTimestamp removeObjectForKey:sortedKeys[i]];
+        }
+    }
+}
+
+@end
+

package/ios/RNLuciq/Util/LCQAPM+PrivateAPIs.h

@@ -10,7 +10,21 @@
 @interface LCQAPM (PrivateAPIs)
 
 @property (class, atomic, assign) BOOL networkEnabled;
+@property (class, atomic, readonly) BOOL endScreenLoadingEnabled;
+
+typedef void (^LCQDisplayLinkObservationCallback)(NSTimeInterval currentTimestamp, NSTimeInterval targetTimestamp);
 
 + (BOOL)customSpansEnabled;
 
++ (void)endScreenLoadingCPWithEndTimestampMUS:(double)endTimestampMUS;
++ (void)reportScreenLoadingCPWithStartTimestampMUS:(double)startTimestampMUS
+                                       durationMUS:(double)durationMUS
+                                    stages:(nullable NSDictionary<NSString *, NSNumber *> *)stages;;
+
++ (void)startObservingDisplayLinkWithCallback:(LCQDisplayLinkObservationCallback _Nonnull)callback;
++ (void)stopObservingDisplayLink;
++ (void)reportScreenLoadingCPUITraceWithName:(NSString *_Nonnull)name
+                       screenLoadingStartMUS:(double)screenLoadingStartMUS
+                    screenLoadingDurationMUS:(double)screenLoadingDurationMUS
+                                      stages:(nullable NSDictionary<NSString *, NSNumber *> *)stages;
 @end

package/ios/native.rb

@@ -1,4 +1,4 @@
-$luciq= { :version => '19.5.1' }
+$luciq= { :version => '19.6.1' }
 
 def use_luciq! (spec = nil)
   version = $luciq[:version]

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@luciq/react-native",
   "description": "Luciq is the Agentic Observability Platform built for Mobile.",
-  "version": "19.4.0",
+  "version": "19.6.0",
   "author": "Luciq (https://luciq.ai)",
   "repository": "github:luciqai/luciq-reactnative-sdk",
   "homepage": "https://www.luciq.ai/platforms/react-native",
@@ -50,11 +50,13 @@
     "@rollup/plugin-json": "^6.0.0",
     "@rollup/plugin-node-resolve": "^15.0.1",
     "@rollup/plugin-typescript": "^11.0.0",
+    "@testing-library/react-native": "^13.3.3",
     "@trivago/prettier-plugin-sort-imports": "^4.2.0",
     "@types/jest": "^29.5.3",
     "@types/minimatch": "3.0.4",
     "@types/node": "^20.4.8",
     "@types/react-native": "^0.72.2",
+    "@types/react-test-renderer": "^19.1.0",
     "axios": "1.11.0",
     "babel-core": "7.0.0-bridge.0",
     "babel-jest": "^29.6.2",
@@ -75,6 +77,7 @@
     "react-native": "^0.72.3",
     "react-native-navigation": "7.36.0",
     "react-navigation": "^4.4.4",
+    "react-test-renderer": "18.3.1",
     "rollup": "^3.27.2",
     "rollup-plugin-cleanup": "^3.2.1",
     "rollup-plugin-copy": "^3.5.0",

package/scripts/get-github-app-token.sh

@@ -0,0 +1,70 @@
+#!/bin/bash
+
+# Generates a GitHub App installation token using openssl + curl.
+# No external dependencies required.
+#
+# Usage: bash get-github-app-token.sh <APP_ID_ENV> <PRIVATE_KEY_ENV> <INSTALLATION_ID_ENV>
+# Example: bash get-github-app-token.sh AND_LUCIQ_APP_ID AND_LUCIQ_PRIVATE_KEY AND_LUCIQ_INSTALLATION_ID
+# Example: bash get-github-app-token.sh AND_INSTABUG_APP_ID AND_INSTABUG_PRIVATE_KEY AND_INSTABUG_INSTALLATION_ID
+
+set -euo pipefail
+
+APP_ID_ENV="${1:?Usage: $0 <APP_ID_ENV> <PRIVATE_KEY_ENV> <INSTALLATION_ID_ENV>}"
+PRIVATE_KEY_ENV="${2:?Usage: $0 <APP_ID_ENV> <PRIVATE_KEY_ENV> <INSTALLATION_ID_ENV>}"
+INSTALL_ID_ENV="${3:?Usage: $0 <APP_ID_ENV> <PRIVATE_KEY_ENV> <INSTALLATION_ID_ENV>}"
+
+APP_ID="${!APP_ID_ENV:?Error: $APP_ID_ENV is not set}"
+PRIVATE_KEY="${!PRIVATE_KEY_ENV:?Error: $PRIVATE_KEY_ENV is not set}"
+INSTALL_ID="${!INSTALL_ID_ENV:?Error: $INSTALL_ID_ENV is not set}"
+
+# Reconstruct PEM file from flattened env var
+# CircleCI flattens multiline env vars into a single line,
+# so we extract header/footer and re-wrap the base64 body at 64 chars
+PEM_FILE=$(mktemp)
+chmod 600 "$PEM_FILE"
+trap 'rm -f "$PEM_FILE"' EXIT
+
+BODY=$(printf '%s' "$PRIVATE_KEY" | sed 's/-----BEGIN RSA PRIVATE KEY-----//;s/-----END RSA PRIVATE KEY-----//;s/ //g')
+{
+    echo "-----BEGIN RSA PRIVATE KEY-----"
+    echo "$BODY" | fold -w 64
+    echo "-----END RSA PRIVATE KEY-----"
+} > "$PEM_FILE"
+
+# Base64url encode (RFC 4648): replace +/ with -_, strip =
+b64url() {
+    openssl base64 -A | tr '+/' '-_' | tr -d '='
+}
+
+NOW=$(date +%s)
+IAT=$((NOW - 60))    # 60s clock skew allowance per GitHub docs
+EXP=$((NOW + 600))   # 10min max JWT lifetime per GitHub docs
+
+# Create JWT header and payload
+HEADER=$(printf '{"alg":"RS256","typ":"JWT"}' | b64url)
+PAYLOAD=$(printf '{"iat":%d,"exp":%d,"iss":"%s"}' "$IAT" "$EXP" "$APP_ID" | b64url)
+
+# Sign with RSA-SHA256
+SIGNATURE=$(printf '%s.%s' "$HEADER" "$PAYLOAD" | openssl dgst -sha256 -sign "$PEM_FILE" -binary | b64url)
+
+JWT_TOKEN="${HEADER}.${PAYLOAD}.${SIGNATURE}"
+
+# Exchange JWT for installation token
+RESPONSE=$(curl -sf -X POST \
+    -H "Authorization: Bearer $JWT_TOKEN" \
+    -H "Accept: application/vnd.github+json" \
+    -H "X-GitHub-Api-Version: 2022-11-28" \
+    "https://api.github.com/app/installations/${INSTALL_ID}/access_tokens") || {
+    echo "Error: GitHub API request failed (HTTP error)" >&2
+    exit 1
+}
+
+TOKEN=$(echo "$RESPONSE" | jq -r '.token // empty')
+
+if [ -z "$TOKEN" ]; then
+    ERROR_MSG=$(echo "$RESPONSE" | jq -r '.message // "unknown error"')
+    echo "Error: Failed to get installation token: $ERROR_MSG" >&2
+    exit 1
+fi
+
+echo "$TOKEN"

package/scripts/notify-github.sh

@@ -1,15 +1,24 @@
 #!/bin/bash
 
+set -euo pipefail
+
 pr_url="https://api.github.com/repos/$CIRCLE_PROJECT_USERNAME/$CIRCLE_PROJECT_REPONAME/pulls?head=$CIRCLE_PROJECT_USERNAME:$CIRCLE_BRANCH&state=open"
 pr_response=$(curl --location --request GET "$pr_url" --header "Authorization: Bearer $RELEASE_GITHUB_TOKEN")
 
-if [ $(echo "$pr_response" | jq length) -eq 0 ]; then
-  echo "No PR found to update"
-else
-  pr_comment_url=$(echo "$pr_response" | jq -r ".[]._links.comments.href")
+if ! echo "$pr_response" | jq -e 'type == "array"' >/dev/null; then
+  echo "Unexpected GitHub API response (not an array):"
+  echo "$pr_response"
+  exit 1
+fi
 
-  curl --location --request POST "$pr_comment_url" \
-    --header 'Content-Type: application/json' \
-    --header "Authorization: Bearer $RELEASE_GITHUB_TOKEN" \
-    --data-raw "$1"
+if [ "$(echo "$pr_response" | jq length)" -eq 0 ]; then
+  echo "No PR found to update"
+  exit 0
 fi
+
+pr_comment_url=$(echo "$pr_response" | jq -r ".[]._links.comments.href")
+
+curl --location --request POST "$pr_comment_url" \
+  --header 'Content-Type: application/json' \
+  --header "Authorization: Bearer $RELEASE_GITHUB_TOKEN" \
+  --data-raw "$1"

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);
+}