react-native-nitro-tracing 0.6.0

package/src/client/createTraceClient.ts

@@ -0,0 +1,439 @@
+import {
+  createRuntimeMetricsPlugin,
+  type RuntimeMetricsOptions,
+} from '../plugins/runtimeMetrics'
+import {
+  formatTracingEntry,
+  type TracingEntry,
+  type TracingSink,
+} from './TracingSink'
+import type { Recording } from '../specs/Recording.nitro'
+import type { RecordingOptions } from '../types'
+import type { PerformancePluginOptions } from '../plugins/performance'
+import { createPerformancePlugin } from '../plugins/performance'
+import { startPlugins } from '../plugins/startPlugins'
+import type { PluginHandle, TracePlugin } from '../plugins/TracePlugin'
+import type { ReleaseProfilerPlugin } from '../plugins/releaseProfiler'
+import { recordPlayground, type PlaygroundReport } from './playground'
+
+/** `recording`: lossless native schema. `perfetto`: Chrome Trace Events for ui.perfetto.dev. */
+export type TraceFormat = 'recording' | 'perfetto'
+export type ClientAttributes = Record<
+  string,
+  string | number | boolean | undefined
+>
+export interface TraceClientOptions {
+  /** Optional app log/breadcrumb output; failures never affect measured work. */
+  sink?: TracingSink
+  plugins?: TracePlugin[]
+  performance?: false | PerformancePluginOptions
+  /** Opt in to foreground JS event-loop and frame-callback metrics. */
+  runtimeMetrics?: boolean | RuntimeMetricsOptions
+  onError?: (error: unknown) => void
+  recordingOptions?: Partial<RecordingOptions>
+  /** Serialize and deliver a recording; `format` picks raw recording JSON or Perfetto trace events. */
+  share?: (recording: Recording, format: TraceFormat) => Promise<void>
+  shareProfile?: (path: string) => Promise<void>
+  /** Start Hermes sampling with each recording; stopped and saved with it. */
+  autoProfile?: boolean
+  /**
+   * CPU profile window captured by `flag()` when a profiler is attached and idle.
+   * Default 10000 ms; 0 records only the flag mark.
+   */
+  flagProfileMs?: number
+  profiler?: ReleaseProfilerPlugin
+}
+export interface TraceClientSnapshot {
+  visible: boolean
+  recording: boolean
+  busy: boolean
+  disposed: boolean
+  error?: string
+  profiling: boolean
+  profilePath?: string
+  playground?: PlaygroundReport
+  /** Plugin IDs started for the current recording, so the UI can tell untracked from quiet. */
+  collectors?: string[]
+}
+/** react-native-performance when installed (existing marks live in its buffer), else RN's global Web Performance API. */
+const defaultPerformanceApi = (): PerformancePluginOptions | undefined => {
+  try {
+    // Directly inside `try` so Metro treats the optional peer as optional.
+    const module =
+      require('react-native-performance') as typeof import('react-native-performance')
+    return {
+      performance: module.default,
+      PerformanceObserver: module.PerformanceObserver,
+    }
+  } catch {
+    const global = globalThis as unknown as Partial<PerformancePluginOptions>
+    return global.performance && global.PerformanceObserver
+      ? (global as PerformancePluginOptions)
+      : undefined
+  }
+}
+/** Each client exclusively owns its recording and producers. Consumers must dispose it. */
+export function createTraceClient(options: TraceClientOptions = {}) {
+  let recording: Recording | undefined
+  let handle: PluginHandle | undefined
+  const readinessStartMs = globalThis.performance.now()
+  let readyReported = false
+  let enabled = false
+  let disposed = false
+  let pending = 0
+  let tail = Promise.resolve()
+  let snapshot: TraceClientSnapshot = {
+    visible: false,
+    recording: false,
+    busy: false,
+    disposed: false,
+    profiling: false,
+  }
+  const listeners = new Set<() => void>()
+  const marks = new Map<
+    string,
+    { marks: Map<string, number>; emitted: Set<string> }
+  >()
+  const publish = (next: Partial<TraceClientSnapshot> = {}) => {
+    snapshot = {
+      ...snapshot,
+      recording: enabled,
+      disposed,
+      busy: pending > 0,
+      profiling: options.profiler?.isProfiling() ?? false,
+      profilePath: options.profiler?.getProfilePath(),
+      ...next,
+    }
+    for (const listener of listeners) {
+      try {
+        listener()
+      } catch {
+        /* Observers cannot interrupt recording ownership. */
+      }
+    }
+  }
+  const reportError = (error: unknown) => {
+    publish({ error: String(error) })
+    try {
+      options.onError?.(error)
+    } catch {
+      /* Diagnostics cannot change measured operations. */
+    }
+  }
+  const safely = <T>(work: () => T): T | undefined => {
+    try {
+      return work()
+    } catch (error) {
+      reportError(error)
+      return undefined
+    }
+  }
+  const emit = (entry: TracingEntry) => {
+    if (options.sink)
+      safely(() => options.sink!(formatTracingEntry(entry), entry))
+  }
+  const enqueue = (work: () => Promise<void>) => {
+    if (disposed) return Promise.reject(new Error('Trace client is disposed'))
+    pending++
+    publish()
+    const result = tail.then(async () => {
+      try {
+        if (disposed) throw new Error('Trace client is disposed')
+        await work()
+      } finally {
+        pending--
+        publish()
+      }
+    })
+    tail = result.catch(reportError)
+    return result
+  }
+  const stopCurrent = async () => {
+    enabled = false
+    try {
+      await handle?.stop()
+    } finally {
+      handle = undefined
+      recording?.stop()
+      marks.clear()
+      publish()
+    }
+  }
+  const startCurrent = async () => {
+    await stopCurrent()
+    if (disposed) throw new Error('Trace client is disposed')
+    recording?.dispose()
+    recording = undefined
+    const { Tracing } = require('../index') as typeof import('../index')
+    recording = Tracing.startRecording({
+      // ~1-2 hours of spans for UAT sessions; metric samples use at most half.
+      maxEvents: 10000,
+      maxBytes: 6 * 1024 * 1024,
+      maxActiveSpans: 256,
+      spanTimeoutMs: 30 * 60 * 1000,
+      ...options.recordingOptions,
+    })
+    publish({ error: undefined, playground: undefined })
+    try {
+      const plugins = [...(options.plugins ?? [])]
+      const api =
+        options.performance === false
+          ? undefined
+          : (options.performance ?? defaultPerformanceApi())
+      if (api)
+        plugins.unshift(
+          createPerformancePlugin(api, options.sink ? emit : undefined)
+        )
+      if (options.runtimeMetrics)
+        plugins.push(
+          createRuntimeMetricsPlugin(
+            options.runtimeMetrics === true ? {} : options.runtimeMetrics
+          )
+        )
+      if (options.profiler) plugins.push(options.profiler)
+      handle = startPlugins(recording, plugins, reportError)
+      publish({ collectors: plugins.map((plugin) => plugin.id) })
+    } catch (error) {
+      try {
+        await stopCurrent()
+      } catch (cleanupError) {
+        reportError(cleanupError)
+      }
+      try {
+        recording?.dispose()
+      } finally {
+        recording = undefined
+      }
+      throw error
+    }
+    enabled = true
+    if (options.autoProfile && options.profiler)
+      safely(() => options.profiler!.startProfiling())
+    publish()
+  }
+  const context = (name: string, attributes?: ClientAttributes) => ({
+    name,
+    correlationId: String(attributes?.id ?? ''),
+    attributes: Object.entries(attributes ?? {})
+      .filter(([, value]) => value !== undefined)
+      .slice(0, 32)
+      .map(([key, value]) => ({
+        key: key.slice(0, 64),
+        value: String(value).slice(0, 512),
+      })),
+  })
+  const trace = {
+    mark(name: string, attributes?: ClientAttributes) {
+      safely(() => {
+        if (!enabled || !recording) return
+        recording.mark(context(name, attributes))
+        emit({ name, entryType: 'mark', durationMs: 0, attributes })
+        if (typeof attributes?.id === 'string') {
+          let bucket = marks.get(attributes.id)
+          if (!bucket) {
+            if (marks.size >= 512) marks.delete(marks.keys().next().value!)
+            bucket = { marks: new Map(), emitted: new Set() }
+            marks.set(attributes.id, bucket)
+          }
+          if (bucket.marks.size >= 64 && !bucket.marks.has(name))
+            bucket.marks.delete(bucket.marks.keys().next().value!)
+          bucket.marks.set(name, recording.getStats().nowMs)
+        }
+      })
+    },
+    metric(
+      name: string,
+      value: number | string,
+      attributes?: ClientAttributes
+    ) {
+      safely(() => {
+        if (!enabled || !recording) return
+        const numeric = Number(value)
+        if (Number.isFinite(numeric))
+          recording.recordMetric({
+            ...context(name, attributes),
+            value: numeric,
+            unit: String(attributes?.unit ?? 'count'),
+          })
+        else recording.mark(context(name, { ...attributes, value }))
+        emit({ name, entryType: 'metric', durationMs: 0, value, attributes })
+      })
+    },
+    async measure<T>(
+      name: string,
+      fn: () => Promise<T>,
+      attributes?: ClientAttributes
+    ): Promise<T> {
+      const started =
+        enabled && options.sink ? globalThis.performance.now() : undefined
+      const span = safely(() =>
+        enabled ? recording?.startSpan(context(name, attributes)) : undefined
+      )
+      try {
+        const value = await fn()
+        safely(() => span?.end('success'))
+        return value
+      } catch (error) {
+        safely(() => span?.end('error'))
+        throw error
+      } finally {
+        if (started !== undefined)
+          emit({
+            name,
+            entryType: 'measure',
+            durationMs: Math.max(0, globalThis.performance.now() - started),
+            attributes,
+          })
+      }
+    },
+    measureSince(
+      name: string,
+      startName: string,
+      id: string,
+      attributes?: ClientAttributes
+    ) {
+      safely(() => {
+        if (!enabled || !recording) return
+        const bucket = marks.get(id)
+        const start = bucket?.marks.get(startName)
+        if (
+          start === undefined ||
+          bucket!.emitted.has(name) ||
+          bucket!.emitted.size >= 64
+        )
+          return
+        bucket!.emitted.add(name)
+        const durationMs = Math.max(0, recording.getStats().nowMs - start)
+        recording.recordSpan({
+          ...context(name, { ...attributes, id, startName }),
+          timestampMs: start,
+          durationMs,
+          outcome: 'success',
+        })
+        emit({
+          name,
+          entryType: 'measure',
+          durationMs,
+          attributes: { ...attributes, id },
+        })
+      })
+    },
+    clear(id: string) {
+      marks.delete(id)
+    },
+  }
+  return {
+    /** Once per client lifetime: elapsed time from client creation to the app-defined ready signal. */
+    reportAppReady() {
+      if (readyReported || !enabled) return
+      readyReported = true
+      trace.metric(
+        'app.ready.after_tracer_init',
+        Math.max(0, globalThis.performance.now() - readinessStartMs),
+        {
+          unit: 'ms',
+          source: 'app-readiness',
+          definition:
+            'Tracer initialization to app ready signal; excludes earlier JS and native startup',
+        }
+      )
+    },
+    trace,
+    start: () => enqueue(startCurrent),
+    stop: () => enqueue(stopCurrent),
+    clear: () =>
+      enqueue(async () => {
+        const wasEnabled = enabled
+        await startCurrent()
+        if (!wasEnabled) await stopCurrent()
+      }),
+    getRecording: () => recording,
+    getError: () => snapshot.error,
+    getSnapshot: () => snapshot,
+    subscribe(listener: () => void) {
+      listeners.add(listener)
+      return () => {
+        listeners.delete(listener)
+      }
+    },
+    open() {
+      if (!disposed) publish({ visible: true })
+    },
+    close() {
+      publish({ visible: false })
+    },
+    reportError,
+    canShare: Boolean(options.share),
+    canProfile: Boolean(options.profiler),
+    canShareProfile: Boolean(options.shareProfile),
+    export: () =>
+      enqueue(async () => {
+        if (!recording || !options.share) return
+        await stopCurrent()
+        await options.share(recording, 'recording')
+      }),
+    /** Share a snapshot while recording continues, e.g. right after catching a problem. */
+    shareTrace: (format: TraceFormat = 'perfetto') =>
+      enqueue(async () => {
+        if (recording && options.share) await options.share(recording, format)
+      }),
+    /**
+     * Mark the moment a tester saw a problem. With an idle profiler this also captures
+     * a bounded Hermes profile, so the flag ships with what the JS thread was doing.
+     */
+    flag: (note?: string) => {
+      trace.mark('flag', { source: 'flag', note })
+      const profiler = options.profiler
+      const windowMs = options.flagProfileMs ?? 10000
+      if (!profiler || windowMs <= 0) return
+      // enqueue already reports failures; the catches only avoid unhandled rejections.
+      enqueue(async () => {
+        if (!enabled || profiler.isProfiling()) return
+        profiler.startProfiling()
+        setTimeout(() => {
+          enqueue(async () => {
+            if (profiler.isProfiling()) await profiler.stopProfiling()
+          }).catch(() => {})
+        }, windowMs)
+      }).catch(() => {})
+    },
+    toggleProfile: () =>
+      enqueue(async () => {
+        if (!enabled || !options.profiler) return
+        if (options.profiler.isProfiling())
+          await options.profiler.stopProfiling()
+        else options.profiler.startProfiling()
+      }),
+    shareProfile: () =>
+      enqueue(async () => {
+        const path = options.profiler?.getProfilePath()
+        if (path) await options.shareProfile?.(path)
+      }),
+    playground: () =>
+      enqueue(async () => {
+        if (enabled && recording)
+          publish({ playground: await recordPlayground(recording) })
+      }),
+    dispose() {
+      if (disposed) return tail
+      disposed = true
+      enabled = false
+      publish({ visible: false })
+      const result = tail.then(async () => {
+        try {
+          await stopCurrent()
+        } finally {
+          try {
+            recording?.dispose()
+          } finally {
+            recording = undefined
+            listeners.clear()
+          }
+        }
+      })
+      tail = result.catch(reportError)
+      return result
+    },
+  }
+}
+export type TraceClient = ReturnType<typeof createTraceClient>

package/src/client/playground.ts

@@ -0,0 +1,143 @@
+import type { Recording } from '../specs/Recording.nitro'
+import type { SpanEvent, MetricEvent } from '../types'
+export type PlaygroundCheckId =
+  'nested' | 'concurrency' | 'cancelled' | 'idempotent' | 'error' | 'metrics'
+export interface PlaygroundReport {
+  correlationId: string
+  checks: { id: PlaygroundCheckId; passed: boolean }[]
+  passed: boolean
+}
+const delay = (ms: number) =>
+  new Promise<void>((resolve) => setTimeout(resolve, ms))
+/** Adds a small isolated scenario; never resets or stops the user's recording. */
+export const recordPlayground = async (
+  current: Recording
+): Promise<PlaygroundReport> => {
+  const identity = current.startSpan({
+    name: 'playground.run',
+    correlationId: '',
+    attributes: [],
+  })
+  const correlationId = `playground-${identity.spanId}`
+  identity.end('success')
+  const root = current.startSpan({
+    name: 'playground.pipeline',
+    correlationId,
+    attributes: [{ key: 'source', value: 'playground' }],
+  })
+  const start = (name: string) =>
+    current.startSpan({
+      name,
+      correlationId,
+      parentSpanId: root.spanId,
+      attributes: [],
+    })
+  try {
+    const first = start('playground.concurrent')
+    const second = start('playground.concurrent')
+    await Promise.all([
+      delay(30).then(() => first.end('success')),
+      delay(60).then(() => second.end('success')),
+    ])
+    const cancelled = start('playground.cancelled')
+    cancelled.end('cancelled')
+    const repeated = start('playground.idempotent')
+    repeated.end('success')
+    repeated.end('error')
+    const failed = start('playground.error')
+    failed.end('error')
+    for (const value of [20, 45, 80])
+      current.recordMetric({
+        name: 'playground.throughput',
+        correlationId,
+        attributes: [],
+        value,
+        unit: 'byte/second',
+      })
+    root.end('success')
+    const spans: SpanEvent[] = []
+    const metrics: MetricEvent[] = []
+    let afterSequence = 0
+    // Native recordings cap at 100000 events. Retain only this scenario while scanning.
+    for (let pageIndex = 0; pageIndex < 100; pageIndex++) {
+      const page = await current.readEvents({ afterSequence, limit: 1000 })
+      spans.push(
+        ...page.spans.filter(
+          (event) =>
+            event.correlationId === correlationId ||
+            event.spanId === root.spanId
+        )
+      )
+      metrics.push(
+        ...page.metrics.filter((event) => event.correlationId === correlationId)
+      )
+      if (
+        page.nextSequence <= afterSequence ||
+        page.spans.length + page.marks.length + page.metrics.length < 1000
+      )
+        break
+      afterSequence = page.nextSequence
+    }
+    const concurrent = spans.filter(
+      (span) => span.name === 'playground.concurrent'
+    )
+    const repeatedEvents = spans.filter(
+      (span) => span.spanId === repeated.spanId
+    )
+    const checks: PlaygroundReport['checks'] = [
+      {
+        id: 'nested',
+        passed:
+          spans.length === 6 &&
+          spans
+            .filter((span) => span.spanId !== root.spanId)
+            .every((span) => span.parentSpanId === root.spanId),
+      },
+      {
+        id: 'concurrency',
+        passed:
+          concurrent.length === 2 &&
+          concurrent[0].spanId !== concurrent[1].spanId &&
+          Math.max(...concurrent.map((span) => span.timestampMs)) <=
+            Math.min(
+              ...concurrent.map((span) => span.timestampMs + span.durationMs)
+            ),
+      },
+      {
+        id: 'cancelled',
+        passed: spans.some(
+          (span) =>
+            span.spanId === cancelled.spanId && span.outcome === 'cancelled'
+        ),
+      },
+      {
+        id: 'idempotent',
+        passed:
+          repeatedEvents.length === 1 &&
+          repeatedEvents[0].outcome === 'success',
+      },
+      {
+        id: 'error',
+        passed: spans.some(
+          (span) => span.spanId === failed.spanId && span.outcome === 'error'
+        ),
+      },
+      {
+        id: 'metrics',
+        passed:
+          metrics.length === 3 &&
+          metrics.map((metric) => metric.value).join(',') === '20,45,80',
+      },
+    ]
+    return {
+      correlationId,
+      checks,
+      passed: checks.every((check) => check.passed),
+    }
+  } catch (error) {
+    try {
+      root.end('error')
+    } catch {}
+    throw error
+  }
+}

package/src/expo/ExpoAdapter.ts

@@ -0,0 +1,71 @@
+import * as FileSystem from 'expo-file-system/legacy'
+import * as Sharing from 'expo-sharing'
+import type { TraceClient, TraceFormat } from '../client/createTraceClient'
+import type { Recording } from '../specs/Recording.nitro'
+export interface ExpoSharingOptions {
+  dialogTitle?: string
+}
+/** Native OS file sharing. No remote upload or file-path export to telemetry. */
+export function createExpoTraceSharing(options: ExpoSharingOptions = {}) {
+  const shareFile = async (uri: string, mimeType: string) => {
+    if (!(await Sharing.isAvailableAsync()))
+      throw new Error('Native file sharing is unavailable on this device')
+    await Sharing.shareAsync(uri, {
+      mimeType,
+      dialogTitle: options.dialogTitle ?? 'Share performance recording',
+    })
+  }
+  return {
+    async share(recording: Recording, format: TraceFormat = 'recording') {
+      if (!FileSystem.cacheDirectory)
+        throw new Error('Application cache is unavailable')
+      const prefix = format === 'perfetto' ? 'perfetto-trace' : 'native-trace'
+      const uri = `${FileSystem.cacheDirectory}${prefix}-${
+        recording.getStats().sessionId
+      }-${Date.now()}.json`
+      // Both formats serialize off the JS thread; only the finished string crosses JSI.
+      const json =
+        format === 'perfetto'
+          ? await recording.exportTraceEvents()
+          : await recording.exportJson()
+      try {
+        await FileSystem.writeAsStringAsync(uri, json, {
+          encoding: FileSystem.EncodingType.UTF8,
+        })
+        await shareFile(uri, 'application/json')
+      } finally {
+        await FileSystem.deleteAsync(uri, { idempotent: true })
+      }
+    },
+    async shareProfile(path: string) {
+      await shareFile(
+        path.startsWith('file://') ? path : `file://${path}`,
+        'application/octet-stream'
+      )
+    },
+  }
+}
+/** Register only in a development build. The consumer owns client disposal. */
+export async function registerTraceDevMenu(
+  client: TraceClient,
+  options: {
+    name?: string
+    registerDevMenuItems?: typeof import('expo-dev-client').registerDevMenuItems
+  } = {}
+) {
+  try {
+    const register =
+      options.registerDevMenuItems ??
+      (require('expo-dev-client') as typeof import('expo-dev-client'))
+        .registerDevMenuItems
+    await register([
+      {
+        name: options.name ?? 'Performance inspector',
+        shouldCollapse: true,
+        callback: () => client.open(),
+      },
+    ])
+  } catch (error) {
+    client.reportError(error)
+  }
+}

package/src/expo/index.ts

@@ -0,0 +1,2 @@
+export { createExpoTraceSharing, registerTraceDevMenu } from './ExpoAdapter'
+export type { ExpoSharingOptions } from './ExpoAdapter'

package/src/index.ts

@@ -0,0 +1,8 @@
+import { NitroModules } from 'react-native-nitro-modules'
+import type { Tracing as TracingFactory } from './specs/Tracing.nitro'
+/** Native recording factory. See Recording for ownership and cleanup. */
+export const Tracing =
+  NitroModules.createHybridObject<TracingFactory>('Tracing')
+export type { Recording } from './specs/Recording.nitro'
+export type { TraceSpan } from './specs/TraceSpan.nitro'
+export type * from './types'

package/src/plugins/TracePlugin.ts

@@ -0,0 +1,22 @@
+import type { Recording } from '../specs/Recording.nitro'
+/** Shared native destination supplied to measurement and export plugins. */
+export interface PluginContext {
+  /** Active native recording. */
+  recording: Recording
+  /** Surface plugin failures without changing application operations. */
+  reportError(error: unknown): void
+}
+/** Cleanup owned by a started plugin. */
+export interface PluginHandle {
+  /** Disconnect observers and finish export before native recording disposal. */
+  stop(): void | Promise<void>
+  /** Optional exporter flush after sources stop and native history freezes. */
+  flush?(): void | Promise<void>
+}
+/** Optional measurement source, exporter or profiler integration. */
+export interface TracePlugin {
+  /** Unique stable configuration identity. */
+  readonly id: string
+  /** Start once per recording; must roll back resources if setup throws. */
+  start(context: PluginContext): PluginHandle
+}