react-native-nitro-tracing 0.6.0

package/src/plugins/errors.ts

@@ -0,0 +1,69 @@
+import type { TracePlugin } from './TracePlugin'
+type Handler = (error: unknown, isFatal?: boolean) => void
+export interface ErrorUtilsLike {
+  getGlobalHandler(): Handler
+  setGlobalHandler(handler: Handler): void
+}
+export interface ErrorsPluginOptions {
+  /** Defaults to React Native's global ErrorUtils. */
+  errorUtils?: ErrorUtilsLike
+  /** Also record console.error calls. Default false; libraries log non-fatal noise there. */
+  console?: boolean
+}
+const messageOf = (value: unknown) =>
+  value instanceof Error ? `${value.name}: ${value.message}` : String(value)
+/** Records uncaught JS errors as `js.error` marks, then calls the previous handler unchanged. */
+export function createErrorsPlugin(
+  options: ErrorsPluginOptions = {}
+): TracePlugin {
+  return {
+    id: 'errors',
+    start({ recording, reportError }) {
+      const utils =
+        options.errorUtils ??
+        (globalThis as unknown as { ErrorUtils?: ErrorUtilsLike }).ErrorUtils
+      let active = true
+      let recordingError = false
+      const record = (kind: string, message: string, fatal: boolean) => {
+        if (!active || recordingError) return
+        recordingError = true
+        try {
+          recording.mark({
+            name: 'js.error',
+            correlationId: '',
+            attributes: [
+              { key: 'source', value: 'error' },
+              { key: 'kind', value: kind },
+              { key: 'fatal', value: String(fatal) },
+              { key: 'message', value: message.slice(0, 1024) },
+            ],
+          })
+        } catch (error) {
+          reportError(error)
+        } finally {
+          recordingError = false
+        }
+      }
+      const previous = utils?.getGlobalHandler()
+      const handler: Handler = (error, isFatal) => {
+        record('global', messageOf(error), Boolean(isFatal))
+        previous?.(error, isFatal)
+      }
+      utils?.setGlobalHandler(handler)
+      const consoleError = console.error
+      const patchedConsole = (...args: unknown[]) => {
+        record('console', args.map(messageOf).join(' '), false)
+        consoleError.apply(console, args)
+      }
+      if (options.console) console.error = patchedConsole
+      return {
+        stop() {
+          active = false
+          if (utils && previous && utils.getGlobalHandler() === handler)
+            utils.setGlobalHandler(previous)
+          if (console.error === patchedConsole) console.error = consoleError
+        },
+      }
+    },
+  }
+}

package/src/plugins/nativeMetrics.ts

@@ -0,0 +1,26 @@
+import type { TracePlugin } from './TracePlugin'
+export interface NativeMetricsOptions {
+  /** Metric window; 250–60000 ms. Default 1000. */
+  intervalMs?: number
+  /** Main-thread frame metrics (ui.fps, ui.frame_gap.max, ui.frames.slow/frozen). Default true. */
+  frames?: boolean
+}
+/**
+ * Native measurement layer: a sampler thread writes process.cpu, process.memory and
+ * main-thread frame windows straight into the recording, with no per-frame JS work.
+ * Alternative or complement to Sentry's measurements; each metric carries source=native.
+ */
+export function createNativeMetricsPlugin(
+  options: NativeMetricsOptions = {}
+): TracePlugin {
+  return {
+    id: 'native-metrics',
+    start({ recording }) {
+      recording.startNativeSampling({
+        intervalMs: options.intervalMs ?? 1000,
+        frames: options.frames ?? true,
+      })
+      return { stop: () => recording.stopNativeSampling() }
+    },
+  }
+}

package/src/plugins/navigation.ts

@@ -0,0 +1,111 @@
+import type { TraceSpan } from '../specs/TraceSpan.nitro'
+import type { TracePlugin } from './TracePlugin'
+/** Structural subset of a React Navigation container ref (expo-router: useNavigationContainerRef()). */
+export interface NavigationRefLike {
+  addListener(event: 'state' | 'ready', listener: () => void): () => void
+  getCurrentRoute(): { name: string; key?: string } | undefined
+  /** React Navigation logs an error when getCurrentRoute() runs before mount. */
+  isReady?(): boolean
+}
+export interface NavigationPluginOptions {
+  /** Defaults to requestAnimationFrame. */
+  requestFrame?: (callback: () => void) => unknown
+}
+/**
+ * Per focused route: a `navigation.enter` mark, a `screen <name>` visit span (dwell time)
+ * and a `navigation.transition` metric from state change to the second frame callback.
+ * The transition is a render-opportunity estimate, not content readiness.
+ */
+export function createNavigationPlugin(
+  ref: NavigationRefLike,
+  options: NavigationPluginOptions = {}
+): TracePlugin {
+  return {
+    id: 'navigation',
+    start({ recording, reportError }) {
+      const requestFrame =
+        options.requestFrame ??
+        ((callback: () => void) => requestAnimationFrame(callback))
+      let visit: TraceSpan | undefined
+      let current: string | undefined
+      let visits = 0
+      let stopped = false
+      const enter = () => {
+        if (stopped) return
+        try {
+          if (ref.isReady?.() === false) return
+          const route = ref.getCurrentRoute()
+          const key = route && (route.key ?? route.name)
+          if (!route || key === current) return
+          current = key
+          visit?.end('success')
+          visit = undefined
+          const correlationId = `screen:${++visits}`
+          const attributes = [
+            { key: 'source', value: 'navigation' },
+            { key: 'screen', value: route.name.slice(0, 1024) },
+          ]
+          const startedAt = recording.getStats().nowMs
+          recording.mark({
+            name: 'navigation.enter',
+            correlationId,
+            attributes,
+          })
+          visit = recording.startSpan({
+            name: `screen ${route.name}`.slice(0, 200),
+            correlationId,
+            attributes,
+          })
+          requestFrame(() =>
+            requestFrame(() => {
+              if (stopped) return
+              try {
+                recording.recordMetric({
+                  name: 'navigation.transition',
+                  value: recording.getStats().nowMs - startedAt,
+                  unit: 'ms',
+                  correlationId,
+                  attributes,
+                })
+              } catch (error) {
+                reportError(error)
+              }
+            })
+          )
+        } catch (error) {
+          reportError(error)
+        }
+      }
+      // The initial route emits `ready`, not `state`; single-screen apps would record nothing.
+      const unsubscribers = [
+        ref.addListener('ready', enter),
+        ref.addListener('state', enter),
+      ]
+      enter()
+      return {
+        stop() {
+          stopped = true
+          for (const unsubscribe of unsubscribers) unsubscribe()
+          visit?.end('success')
+        },
+      }
+    },
+  }
+}
+/** For apps without React Navigation (custom tabs): pass to createNavigationPlugin, call setScreen on change. */
+export function createScreenTracker(initial?: string) {
+  let route = initial ? { name: initial } : undefined
+  const listeners = new Set<() => void>()
+  return {
+    addListener(_event: 'state' | 'ready', listener: () => void) {
+      listeners.add(listener)
+      return () => void listeners.delete(listener)
+    },
+    getCurrentRoute: () => route,
+    setScreen(name: string) {
+      if (route?.name === name) return
+      route = { name }
+      for (const listener of listeners) listener()
+    },
+  }
+}

package/src/plugins/network.ts

@@ -0,0 +1,178 @@
+import type { TracePlugin } from './TracePlugin'
+type Fetch = typeof fetch
+export interface NetworkPluginOptions {
+  /** Defaults to the global XMLHttpRequest, which backs axios and React Native's polyfilled fetch. */
+  XMLHttpRequest?: { prototype: XMLHttpRequest }
+  /** Object whose `fetch` is wrapped. Defaults to globalThis. */
+  fetchHost?: { fetch?: Fetch }
+  /** Skip matching URLs. Defaults to Metro symbolication requests. */
+  ignore?: (url: string) => boolean
+}
+/** Path without origin/query; numeric, UUID and long hex segments become `:id` so requests group. */
+export const urlTemplate = (url: string) =>
+  url
+    .split(/[?#]/)[0]
+    .replace(/^[a-z][a-z0-9+.-]*:\/\/[^/]+/i, '')
+    .replace(
+      /\/(\d+|[0-9a-f]{8}-[0-9a-f-]{27,}|[0-9a-f]{16,})(?=\/|$)/gi,
+      '/:id'
+    ) || '/'
+/**
+ * Opt-in request timing: method, URL without query, status and duration. Bodies and headers
+ * are never read. XMLHttpRequest spans end at loadend; native fetch spans (expo/fetch,
+ * nitro-fetch) end when response headers arrive, since reading bodies is left to the app.
+ */
+export function createNetworkPlugin(
+  options: NetworkPluginOptions = {}
+): TracePlugin {
+  const ignore =
+    options.ignore ?? ((url: string) => url.includes('/symbolicate'))
+  return {
+    id: 'network',
+    start({ recording, reportError }) {
+      let active = true
+      const record = (
+        method: string,
+        url: string,
+        startedAt: number,
+        status: number,
+        failure?: 'cancelled' | 'error'
+      ) => {
+        if (!active) return
+        try {
+          recording.recordSpan({
+            name: `${method} ${urlTemplate(url)}`.slice(0, 200),
+            correlationId: '',
+            timestampMs: startedAt,
+            durationMs: Math.max(0, recording.getStats().nowMs - startedAt),
+            outcome:
+              failure ?? (status === 0 || status >= 400 ? 'error' : 'success'),
+            attributes: [
+              { key: 'source', value: 'network' },
+              { key: 'method', value: method },
+              { key: 'url', value: url.split(/[?#]/)[0].slice(0, 1024) },
+              { key: 'status', value: String(status) },
+            ],
+          })
+        } catch (error) {
+          reportError(error)
+        }
+      }
+
+      const proto = (options.XMLHttpRequest ?? globalThis.XMLHttpRequest)
+        ?.prototype
+      const open = proto?.open
+      const send = proto?.send
+      const requests = new WeakMap<
+        XMLHttpRequest,
+        { method: string; url: string }
+      >()
+      const patchedOpen = function (
+        this: XMLHttpRequest,
+        method: string,
+        url: string | URL,
+        ...rest: unknown[]
+      ) {
+        if (active && !ignore(String(url)))
+          requests.set(this, {
+            method: String(method).toUpperCase(),
+            url: String(url),
+          })
+        return (open as (...args: unknown[]) => void).call(
+          this,
+          method,
+          url,
+          ...rest
+        )
+      }
+      const patchedSend = function (
+        this: XMLHttpRequest,
+        body?: Document | XMLHttpRequestBodyInit | null
+      ) {
+        const request = requests.get(this)
+        if (active && request) {
+          try {
+            const startedAt = recording.getStats().nowMs
+            let failure: 'cancelled' | 'error' | undefined
+            this.addEventListener('abort', () => (failure = 'cancelled'))
+            this.addEventListener('timeout', () => (failure = 'error'))
+            this.addEventListener('error', () => (failure = 'error'))
+            this.addEventListener('loadend', () =>
+              record(
+                request.method,
+                request.url,
+                startedAt,
+                this.status,
+                failure
+              )
+            )
+          } catch (error) {
+            reportError(error)
+          }
+        }
+        return send!.call(this, body)
+      }
+      if (proto) {
+        proto.open = patchedOpen as typeof proto.open
+        proto.send = patchedSend
+      }
+
+      // whatwg-fetch marks itself `polyfill` and already runs through the XHR hook above.
+      const host = options.fetchHost ?? (globalThis as { fetch?: Fetch })
+      const originalFetch = host.fetch
+      const wrapFetch =
+        typeof originalFetch === 'function' &&
+        !(originalFetch as Fetch & { polyfill?: boolean }).polyfill
+      const patchedFetch: Fetch = async (input, init) => {
+        const url =
+          typeof input === 'string'
+            ? input
+            : input instanceof URL
+              ? input.href
+              : input.url
+        if (!active || ignore(url)) return originalFetch!(input, init)
+        const method = String(
+          init?.method ??
+            (typeof input === 'object' && 'method' in input
+              ? input.method
+              : 'GET')
+        ).toUpperCase()
+        let startedAt = 0
+        try {
+          startedAt = recording.getStats().nowMs
+        } catch (error) {
+          reportError(error)
+        }
+        try {
+          const response = await originalFetch!(input, init)
+          record(method, url, startedAt, response.status)
+          return response
+        } catch (error) {
+          record(
+            method,
+            url,
+            startedAt,
+            0,
+            (error as { name?: string })?.name === 'AbortError'
+              ? 'cancelled'
+              : 'error'
+          )
+          throw error
+        }
+      }
+      if (wrapFetch) host.fetch = patchedFetch
+
+      return {
+        stop() {
+          active = false
+          // ponytail: if another library wrapped after us, leave our pass-through wrappers in place.
+          if (proto && proto.open === (patchedOpen as unknown))
+            proto.open = open!
+          if (proto && proto.send === patchedSend) proto.send = send!
+          if (wrapFetch && host.fetch === patchedFetch)
+            host.fetch = originalFetch
+        },
+      }
+    },
+  }
+}

package/src/plugins/orderSpans.ts

@@ -0,0 +1,22 @@
+import type { SpanEvent } from '../types'
+/** Parent-first order in O(n), including parents delivered after their children. */
+export function orderSpans(spans: readonly SpanEvent[]): SpanEvent[] {
+  const byId = new Map(spans.map((span) => [span.spanId, span]))
+  const children = new Map<string, SpanEvent[]>()
+  const ordered: SpanEvent[] = []
+  for (const span of byId.values()) {
+    if (!span.parentSpanId || !byId.has(span.parentSpanId)) ordered.push(span)
+    else {
+      const siblings = children.get(span.parentSpanId)
+      if (siblings) siblings.push(span)
+      else children.set(span.parentSpanId, [span])
+    }
+  }
+  for (let index = 0; index < ordered.length; index++) {
+    const descendants = children.get(ordered[index]!.spanId)
+    if (descendants) for (const child of descendants) ordered.push(child)
+  }
+  if (ordered.length !== byId.size)
+    throw new Error('Cannot export cyclic span parents')
+  return ordered
+}

package/src/plugins/performance.ts

@@ -0,0 +1,120 @@
+import type { TracingEntry } from '../client/TracingSink'
+import type performance from 'react-native-performance'
+import type { PerformanceObserver } from 'react-native-performance'
+import type { TracePlugin } from './TracePlugin'
+/** Default measurement-source dependencies; supports the installed RN performance API. */
+export interface PerformancePluginOptions {
+  /** Same clock used by the supplied observer's entries. */
+  performance: typeof performance
+  /** PerformanceObserver from react-native-performance. */
+  PerformanceObserver: typeof PerformanceObserver
+}
+/** Observe user timing without patching globals, clearing shared buffers or timing network bodies. */
+export function createPerformancePlugin(
+  api: PerformancePluginOptions,
+  onEntry?: (entry: TracingEntry) => void
+): TracePlugin {
+  return {
+    id: 'performance',
+    start({ recording, reportError }) {
+      const offset = recording.getStats().nowMs - api.performance.now()
+      let stopped = false
+      const ingest = (
+        entries: ReturnType<PerformanceObserver['takeRecords']>
+      ) => {
+        if (stopped) return
+        for (const entry of entries) {
+          try {
+            const timestampMs = entry.startTime + offset
+            if (timestampMs < 0) continue // Previous history is outside this recording.
+            const data = entry as typeof entry & {
+              value?: unknown
+              detail?: { id?: unknown; unit?: unknown }
+            }
+            onEntry?.({
+              name: entry.name,
+              entryType: entry.entryType,
+              durationMs: entry.duration,
+              value:
+                typeof data.value === 'string' || typeof data.value === 'number'
+                  ? data.value
+                  : undefined,
+              attributes: data.detail,
+            })
+            const context = {
+              name: entry.name.slice(0, 128),
+              correlationId:
+                typeof data.detail?.id === 'string'
+                  ? data.detail.id.slice(0, 128)
+                  : '',
+              attributes: [
+                { key: 'source', value: 'performance' },
+                { key: 'source.startTimeMs', value: String(entry.startTime) },
+              ],
+            }
+            if (entry.entryType === 'longtask')
+              recording.recordSpan({
+                ...context,
+                name: 'js.longtask',
+                timestampMs,
+                durationMs: entry.duration,
+                outcome: 'success',
+              })
+            else if (entry.entryType === 'measure')
+              recording.recordSpan({
+                ...context,
+                timestampMs,
+                durationMs: entry.duration,
+                outcome: 'success',
+              })
+            else if (entry.entryType === 'mark')
+              recording.mark({ ...context, timestampMs })
+            else if (
+              entry.entryType === 'metric' &&
+              typeof data.value === 'number' &&
+              Number.isFinite(data.value)
+            )
+              recording.recordMetric({
+                ...context,
+                timestampMs,
+                value: data.value,
+                unit:
+                  typeof data.detail?.unit === 'string'
+                    ? data.detail.unit.slice(0, 32)
+                    : 'unspecified',
+              })
+          } catch (error) {
+            reportError(error)
+          }
+        }
+      }
+      const observer = new api.PerformanceObserver((list) =>
+        ingest(list.getEntries())
+      )
+      // Global RN observers reject unknown types; react-native-performance lacks longtask.
+      const supported = (
+        api.PerformanceObserver as { supportedEntryTypes?: readonly string[] }
+      ).supportedEntryTypes
+      const entryTypes = ['mark', 'measure', 'metric', 'longtask'].filter(
+        (type) => (supported ? supported.includes(type) : type !== 'longtask')
+      )
+      try {
+        observer.observe({ entryTypes } as never)
+      } catch (error) {
+        observer.disconnect()
+        throw error
+      }
+      return {
+        stop() {
+          if (stopped) return
+          try {
+            ingest(observer.takeRecords())
+          } finally {
+            stopped = true
+            observer.disconnect()
+          }
+        },
+      }
+    },
+  }
+}

package/src/plugins/releaseProfiler.ts

@@ -0,0 +1,123 @@
+import type { TraceSpan } from '../specs/TraceSpan.nitro'
+import type { PluginContext, TracePlugin } from './TracePlugin'
+/** Injected optional react-native-release-profiler module; never imported by core. */
+export interface ReleaseProfilerApi {
+  /** Start the process-wide Hermes sampler; false means unavailable. */
+  startProfiling(): boolean | void
+  /** Stop and save a local profile artifact. */
+  stopProfiling(saveToDownloads?: boolean): Promise<string>
+}
+/** Manually controlled profiler integration. Sampling never starts on plugin setup. */
+export interface ReleaseProfilerPlugin extends TracePlugin {
+  /** Start one session owned by this plugin. */
+  startProfiling(): void
+  /** Finish profiling and return the artifact's local path. */
+  stopProfiling(): Promise<string>
+  /** Whether this plugin owns an active or stopping profile. */
+  isProfiling(): boolean
+  /** Last successful artifact; not sent to remote exporters. */
+  getProfilePath(): string | undefined
+}
+// Hermes profiling is process-wide, so two plugin instances must not compete.
+let owner: object | undefined
+/** Stops Hermes sampling for real; on RN 0.85 Android the profiler's own stop restarts it. */
+const stopHermesSampler = () => {
+  try {
+    const { Tracing } = require('../index') as typeof import('../index')
+    Tracing.disableHermesSampling()
+  } catch {
+    // No native module (tests, non-native hosts): nothing is sampling.
+  }
+}
+export interface ReleaseProfilerOptions {
+  /** Runs after every stop. Defaults to Tracing.disableHermesSampling(). */
+  stopSampler?: () => void
+}
+/** Attach manual Hermes profile controls to a recording. */
+export function createReleaseProfilerPlugin(
+  api: ReleaseProfilerApi,
+  options: ReleaseProfilerOptions = {}
+): ReleaseProfilerPlugin {
+  const identity = {}
+  let context: PluginContext | undefined
+  let active = false
+  let span: TraceSpan | undefined
+  let path: string | undefined
+  let stopping: Promise<string> | undefined
+  const plugin: ReleaseProfilerPlugin = {
+    id: 'release-profiler',
+    start(next) {
+      if (context)
+        throw new Error('Release profiler plugin is already attached')
+      context = next
+      return {
+        async stop() {
+          try {
+            if (active) await plugin.stopProfiling()
+          } finally {
+            context = undefined
+          }
+        },
+      }
+    },
+    startProfiling() {
+      if (!context)
+        throw new Error('Attach release-profiler plugin before profiling')
+      if (owner) throw new Error('A release profiler session is already active')
+      if (api.startProfiling() === false)
+        throw new Error('Hermes sampling profiler is unavailable in this build')
+      owner = identity
+      active = true
+      path = undefined
+      try {
+        span = context.recording.startSpan({
+          name: 'hermes.profile',
+          correlationId: '',
+          attributes: [{ key: 'source', value: 'release-profiler' }],
+        })
+      } catch (error) {
+        context.reportError(error)
+      }
+    },
+    stopProfiling() {
+      if (stopping) return stopping
+      if (!active)
+        return Promise.reject(
+          new Error('No release profiler session is active')
+        )
+      stopping = Promise.resolve().then(async () => {
+        try {
+          path = await api.stopProfiling(false)
+          span?.end('success')
+          // Lets a Perfetto export point at the .cpuprofile covering the span above.
+          try {
+            context?.recording.mark({
+              name: 'hermes.profile.saved',
+              correlationId: '',
+              attributes: [
+                { key: 'source', value: 'release-profiler' },
+                { key: 'path', value: path.slice(0, 512) },
+              ],
+            })
+          } catch (error) {
+            context?.reportError(error)
+          }
+          return path
+        } catch (error) {
+          span?.end('error')
+          throw error
+        } finally {
+          ;(options.stopSampler ?? stopHermesSampler)()
+          active = false
+          if (owner === identity) owner = undefined
+          span = undefined
+          stopping = undefined
+        }
+      })
+      return stopping
+    },
+    isProfiling: () => active,
+    getProfilePath: () => path,
+  }
+  return plugin
+}