react-native-nitro-tracing 0.6.0

package/src/react/useTraceViewer.ts

@@ -0,0 +1,333 @@
+import { createStore } from './store'
+import { readSnapshot } from './readSnapshot'
+import {
+  useCallback,
+  useEffect,
+  useDeferredValue,
+  useMemo,
+  useRef,
+  useState,
+  useSyncExternalStore,
+} from 'react'
+import type { TraceClient } from '../client/createTraceClient'
+import type { RecordingStats, TracePage, SpanEvent, MarkEvent } from '../types'
+import {
+  buildTraces,
+  defaultQuery,
+  queryEvents,
+  queryTraces,
+  traceForSpan,
+  type ExplorerMode,
+  type Query,
+  type Trace,
+} from './explorerModel'
+import { recordingMetrics, operationMetrics } from './viewerModel'
+import {
+  buildTimeline,
+  currentScreen,
+  defaultBudgets,
+  summarizeTopics,
+  type Budgets,
+} from './topics'
+export type Metric = ReturnType<typeof recordingMetrics>[number]
+export type Detail =
+  | { kind: 'trace'; value: Trace }
+  | { kind: 'span'; value: SpanEvent }
+  | { kind: 'mark'; value: MarkEvent }
+  | { kind: 'metric'; value: Metric }
+export type Tab = 'overview' | 'timeline' | 'explore' | 'metrics' | 'tools'
+export interface Telemetry {
+  stats?: RecordingStats
+  error?: string
+  pending?: Pick<TracePage, 'nextSequence' | 'earliestSequence'>
+}
+const empty = (): TracePage => ({
+  spans: [],
+  marks: [],
+  metrics: [],
+  nextSequence: 0,
+  earliestSequence: 0,
+  droppedEvents: 0,
+})
+export const useTraceViewer = (
+  client: TraceClient,
+  budgets?: Partial<Budgets>
+) => {
+  const snapshot = useSyncExternalStore(
+    client.subscribe,
+    client.getSnapshot,
+    client.getSnapshot
+  )
+  const [tab, setTab] = useState<Tab>('overview')
+  const [mode, setMode] = useState<ExplorerMode>('traces')
+  const [page, setPage] = useState(empty)
+  const [telemetry] = useState(() => createStore<Telemetry>({}))
+  const setStats = (stats: RecordingStats) => telemetry.set({ stats })
+  const setError = (error: string | undefined) => telemetry.set({ error })
+  const pendingPage = useRef<TracePage | undefined>(undefined)
+  const setPending = (value: TracePage | undefined) => {
+    pendingPage.current = value
+    telemetry.set({
+      pending: value
+        ? {
+            nextSequence: value.nextSequence,
+            earliestSequence: value.earliestSequence,
+          }
+        : undefined,
+    })
+  }
+  const [queries, setQueries] = useState<Record<ExplorerMode, Query>>({
+    traces: defaultQuery(),
+    spans: defaultQuery(),
+    marks: defaultQuery(),
+  })
+  const [details, setDetails] = useState<Detail[]>([])
+  const [paused, setPaused] = useState(false)
+  const [holding, setHolding] = useState(false)
+  const [metricQuery, setMetricQuery] = useState('')
+  const [metricCategory, setMetricCategory] = useState('all')
+  const [metricSort, setMetricSort] = useState('name')
+  const offsets = useRef<Record<string, number>>({})
+  const detailState = useRef<
+    Record<
+      string,
+      {
+        collapsed: string[]
+        layout: 'waterfall' | 'list'
+        attributes: string
+        offset: number
+      }
+    >
+  >({})
+  const latestPage = useRef(page)
+  const session = useRef<string | undefined>(undefined)
+  const controls = useRef({ paused, holding, detail: details.length > 0 })
+  controls.current = { paused, holding, detail: details.length > 0 }
+  latestPage.current = page
+  useEffect(() => {
+    if (!snapshot.visible) return
+    let cached: TracePage | undefined
+    let cachedRecording: ReturnType<TraceClient['getRecording']>
+    let cancelled = false
+    let timer: ReturnType<typeof setTimeout>
+    const refresh = async () => {
+      try {
+        const recording = client.getRecording()
+        if (recording) {
+          if (cachedRecording !== recording) {
+            cached = undefined
+            cachedRecording = recording
+          }
+          const next = await readSnapshot(recording, cached)
+          cached = next
+          if (cancelled || recording !== client.getRecording()) return
+          const current = recording.getStats()
+          setStats(current)
+          if (session.current !== current.sessionId) {
+            session.current = current.sessionId
+            setDetails([])
+            setPending(undefined)
+            setPage(next)
+            setHolding(false)
+            offsets.current = {}
+            detailState.current = {}
+            setQueries(
+              (previous) =>
+                Object.fromEntries(
+                  Object.entries(previous).map(([key, q]) => [
+                    key,
+                    { ...q, from: '', to: '' },
+                  ])
+                ) as Record<ExplorerMode, Query>
+            )
+          } else if (
+            controls.current.paused ||
+            controls.current.holding ||
+            controls.current.detail
+          ) {
+            if (
+              next.nextSequence !== latestPage.current.nextSequence ||
+              next.droppedEvents !== latestPage.current.droppedEvents
+            )
+              setPending(next)
+          } else {
+            setPage(next)
+            setPending(undefined)
+          }
+        }
+        if (!cancelled) setError(client.getError())
+      } catch (failure) {
+        if (!cancelled) setError(String(failure))
+      } finally {
+        if (!cancelled) timer = setTimeout(refresh, 1000)
+      }
+    }
+    void refresh()
+    return () => {
+      cancelled = true
+      clearTimeout(timer)
+    }
+  }, [client, snapshot.visible])
+  const traces = useMemo(() => buildTraces(page), [page.spans, page.marks])
+  const metrics = useMemo(
+    () => (tab === 'explore' ? [] : recordingMetrics(page)),
+    [page, tab]
+  )
+  const collectors = snapshot.collectors
+  const { appReadyMs, screenMs, requestMs, stallMs } = {
+    ...defaultBudgets,
+    ...budgets,
+  }
+  const summary = useMemo(
+    () =>
+      summarizeTopics(page, collectors ?? [], {
+        appReadyMs,
+        screenMs,
+        requestMs,
+        stallMs,
+      }),
+    [page, collectors, appReadyMs, screenMs, requestMs, stallMs]
+  )
+  const timeline = useMemo(
+    () => (tab === 'timeline' ? buildTimeline(page, summary.issues) : []),
+    [page, summary.issues, tab]
+  )
+  const screen = useMemo(() => currentScreen(page), [page.marks])
+  const operations = useMemo(
+    () => (tab === 'metrics' ? operationMetrics(page.spans) : []),
+    [page.spans, tab]
+  )
+  const query = queries[mode]
+  const deferredQuery = useDeferredValue(query)
+  const results = useMemo(
+    () =>
+      mode === 'traces'
+        ? queryTraces(traces, deferredQuery)
+        : queryEvents(
+            mode === 'spans' ? page.spans : page.marks,
+            deferredQuery
+          ),
+    [mode, traces, page.spans, page.marks, deferredQuery]
+  )
+  const updateQuery = (patch: Partial<Query>) => {
+    setHolding(true)
+    setQueries((previous) => ({
+      ...previous,
+      [mode]: { ...previous[mode], ...patch },
+    }))
+    offsets.current[mode] = 0
+  }
+  const apply = () => {
+    const pending = pendingPage.current
+    if (pending) setPage(pending)
+    setPending(undefined)
+    setHolding(false)
+  }
+  const act = (work: () => void | Promise<void>) => {
+    void Promise.resolve()
+      .then(work)
+      .catch((failure) => {
+        setError(String(failure))
+        client.reportError(failure)
+      })
+  }
+  const detail = details[details.length - 1]
+  // Stable identity lets memoized list rows skip re-rendering on live ticks.
+  const open = useCallback((next: Detail) => {
+    setHolding(true)
+    setDetails((previous) => [...previous.slice(-31), next])
+  }, [])
+  const showEvents = (mode: 'spans' | 'marks', patch: Partial<Query>) => {
+    setTab('explore')
+    setMode(mode)
+    setDetails([])
+    setQueries((previous) => ({
+      ...previous,
+      [mode]: { ...defaultQuery(), ...patch },
+    }))
+    offsets.current[mode] = 0
+    setHolding(true)
+  }
+  return {
+    ...snapshot,
+    client,
+    tab,
+    setTab: (next: Tab) => {
+      setDetails([])
+      setTab(next)
+    },
+    mode,
+    setMode,
+    page,
+    telemetry,
+    traces,
+    topics: summary.topics,
+    issues: summary.issues,
+    timeline,
+    screen,
+    results,
+    query,
+    updateQuery,
+    resetQuery: () => {
+      setQueries((previous) => ({ ...previous, [mode]: defaultQuery() }))
+      offsets.current[mode] = 0
+    },
+    loaded:
+      mode === 'traces'
+        ? traces.length
+        : mode === 'spans'
+          ? page.spans.length
+          : page.marks.length,
+    uncorrelated: useMemo(
+      () =>
+        page.spans.filter((s) => !s.correlationId).length +
+        page.marks.filter((s) => !s.correlationId).length,
+      [page.spans, page.marks]
+    ),
+    detail,
+    detailState,
+    details,
+    open,
+    back: () => setDetails((previous) => previous.slice(0, -1)),
+    traceFor: (span: SpanEvent) => traceForSpan(traces, span),
+    showSpans: (patch: Partial<Query>) => showEvents('spans', patch),
+    showMarks: (patch: Partial<Query>) => showEvents('marks', patch),
+    paused,
+    holding,
+    setHolding,
+    apply,
+    togglePause: () => {
+      if (paused) apply()
+      setPaused(!paused)
+    },
+    offsets,
+    metrics,
+    operations,
+    metricQuery,
+    setMetricQuery,
+    metricCategory,
+    setMetricCategory,
+    metricSort,
+    setMetricSort,
+    start: () => act(client.start),
+    stop: () => act(client.stop),
+    export: () => act(client.export),
+    sharePerfetto: () => act(() => client.shareTrace('perfetto')),
+    toggleProfile: () => act(client.toggleProfile),
+    shareProfile: () => act(client.shareProfile),
+    playground: () => act(client.playground),
+    playgroundResult: snapshot.playground,
+    openPlayground: () => {
+      setTab('explore')
+      setMode('traces')
+      setQueries((previous) => ({
+        ...previous,
+        traces: {
+          ...defaultQuery(),
+          correlation: snapshot.playground?.correlationId ?? '',
+        },
+      }))
+    },
+  }
+}
+export type Viewer = ReturnType<typeof useTraceViewer>

package/src/react/viewerModel.ts

@@ -0,0 +1,172 @@
+import type { MetricEvent, SpanEvent, TracePage } from '../types'
+export interface TraceGroup {
+  id: string
+  name: string
+  start: number
+  duration: number
+  errors: number
+  events: number
+}
+export const groupTraces = (page: TracePage, query: string): TraceGroup[] => {
+  const groups = new Map<string, TraceGroup>()
+  for (const event of [...page.spans, ...page.marks, ...page.metrics]) {
+    const id = event.correlationId || 'uncorrelated'
+    const end =
+      event.timestampMs +
+      ('durationMs' in event && typeof event.durationMs === 'number'
+        ? event.durationMs
+        : 0)
+    const previous = groups.get(id)
+    const start = Math.min(
+      previous?.start ?? event.timestampMs,
+      event.timestampMs
+    )
+    groups.set(id, {
+      id,
+      name:
+        previous && previous.start <= event.timestampMs
+          ? previous.name
+          : event.name,
+      start,
+      duration:
+        Math.max(previous ? previous.start + previous.duration : end, end) -
+        start,
+      errors:
+        (previous?.errors ?? 0) +
+        ('outcome' in event && event.outcome === 'error' ? 1 : 0),
+      events: (previous?.events ?? 0) + 1,
+    })
+  }
+  const search = query.toLowerCase()
+  const matchingIds = new Set(
+    [...page.spans, ...page.marks, ...page.metrics]
+      .filter((event) =>
+        `${event.name} ${event.correlationId}`.toLowerCase().includes(search)
+      )
+      .map((event) => event.correlationId || 'uncorrelated')
+  )
+  return [...groups.values()]
+    .filter((group) => !search || matchingIds.has(group.id))
+    .sort((a, b) => b.start - a.start)
+}
+export const waterfall = (spans: SpanEvent[]) => {
+  const byId = new Map(spans.map((span) => [span.spanId, span]))
+  const base = spans.length
+    ? Math.min(...spans.map((span) => span.timestampMs))
+    : 0
+  const duration = Math.max(
+    1,
+    ...spans.map((span) => span.timestampMs + span.durationMs - base)
+  )
+  return [...spans]
+    .sort(
+      (a, b) => a.timestampMs - b.timestampMs || b.durationMs - a.durationMs
+    )
+    .map((span) => {
+      const seen = new Set([span.spanId])
+      let parent = byId.get(span.parentSpanId)
+      let depth = 0
+      while (parent && depth < 8 && !seen.has(parent.spanId)) {
+        seen.add(parent.spanId)
+        depth++
+        parent = byId.get(parent.parentSpanId)
+      }
+      return {
+        span,
+        depth: Math.min(depth, 8),
+        offset: (span.timestampMs - base) / duration,
+        width: span.durationMs / duration,
+      }
+    })
+}
+const num = (value: number) =>
+  Math.abs(value) >= 100 ? value.toFixed(0) : value.toFixed(1)
+/** Human value with unit: 3653 ms → "3.65 s", 1240 MB → "1.21 GB". */
+export const formatMetric = (value: number, unit: string) => {
+  if (unit === 'ms' && Math.abs(value) >= 1000)
+    return `${(value / 1000).toFixed(2)} s`
+  if (unit === 'MB' && Math.abs(value) >= 1024)
+    return `${(value / 1024).toFixed(2)} GB`
+  if (unit === 'count') return value.toFixed(0)
+  if (unit === '%') return `${num(value)}%`
+  if (unit.endsWith('/s')) return `${num(value)}/s`
+  return `${num(value)} ${unit}`
+}
+
+export const metricSeries = (metrics: MetricEvent[]) => {
+  const groups = new Map<string, MetricEvent[]>()
+  for (const metric of metrics) {
+    const key = `${metric.name} (${metric.unit})`
+    const group = groups.get(key) ?? []
+    group.push(metric)
+    groups.set(key, group)
+  }
+  return [...groups].map(([name, retained]) => {
+    const samples = retained
+      .sort((a, b) => a.timestampMs - b.timestampMs)
+      .slice(-40)
+    const values = retained.map((sample) => sample.value).sort((a, b) => a - b)
+    return {
+      latest: retained[retained.length - 1]?.value ?? 0,
+      median: values.length
+        ? (values[Math.floor((values.length - 1) / 2)] +
+            values[Math.ceil((values.length - 1) / 2)]) /
+          2
+        : 0,
+      min: values[0] ?? 0,
+      peak: values[values.length - 1] ?? 0,
+      p95: values[Math.max(0, Math.ceil(values.length * 0.95) - 1)] ?? 0,
+      name,
+      /** Metric name without the unit suffix used for grouping. */
+      metric: retained[0].name,
+      unit: retained[0].unit,
+      samples,
+      retainedCount: retained.length,
+      startMs: samples[0]?.timestampMs ?? 0,
+      endMs: samples[samples.length - 1]?.timestampMs ?? 0,
+      max: Math.max(1, ...samples.map((sample) => Math.abs(sample.value))),
+    }
+  })
+}
+
+/** Durations are derived from retained completed spans, not additional native samples. */
+export const recordingMetrics = (page: TracePage) =>
+  metricSeries([
+    ...page.metrics,
+    ...page.spans
+      .filter((span) => span.outcome === 'success' || span.outcome === 'error')
+      .map((span) => ({
+        ...span,
+        name: `duration: ${span.name}`,
+        value: span.durationMs,
+        unit: 'ms',
+      })),
+  ])
+
+export const operationMetrics = (spans: SpanEvent[]) => {
+  const groups = new Map<string, SpanEvent[]>()
+  for (const span of spans) {
+    const group = groups.get(span.name) ?? []
+    group.push(span)
+    groups.set(span.name, group)
+  }
+  return [...groups]
+    .map(([name, samples]) => {
+      const completed = samples.filter(
+        (s) => s.outcome === 'success' || s.outcome === 'error'
+      )
+      return {
+        name,
+        count: samples.length,
+        errors: completed.filter((s) => s.outcome === 'error').length,
+        errorRate: completed.length
+          ? (completed.filter((s) => s.outcome === 'error').length /
+              completed.length) *
+            100
+          : undefined,
+        cancelled: samples.filter((s) => s.outcome === 'cancelled').length,
+        interrupted: samples.filter((s) => s.outcome === 'interrupted').length,
+      }
+    })
+    .sort((a, b) => b.count - a.count)
+}

package/src/specs/Recording.nitro.ts

@@ -0,0 +1,40 @@
+import type { HybridObject } from 'react-native-nitro-modules'
+import type { TraceSpan } from './TraceSpan.nitro'
+import type {
+  CompletedSpanOptions,
+  SpanOptions,
+  MarkOptions,
+  MetricOptions,
+  ReadOptions,
+  TracePage,
+  RecordingStats,
+  NativeSamplingOptions,
+} from '../types'
+/** Owns bounded native history. Stop before export; dispose when all readers are done. */
+export interface Recording extends HybridObject<{
+  ios: 'c++'
+  android: 'c++'
+}> {
+  /** Start a span, optionally linked to an explicit parent. */
+  startSpan(options: SpanOptions): TraceSpan
+  /** Import a completed measurement; returns its native span identity. */
+  recordSpan(options: CompletedSpanOptions): string
+  /** Append a point event. */
+  mark(options: MarkOptions): void
+  /** Append a finite numeric sample with units. */
+  recordMetric(options: MetricOptions): void
+  /** Read at most 1000 completed events without per-event callbacks. */
+  readEvents(options: ReadOptions): Promise<TracePage>
+  /** Read cheap recording counters and clock anchor. */
+  getStats(): RecordingStats
+  /** Freeze history and close active spans as interrupted. Idempotent. */
+  stop(): void
+  /** Serialize a snapshot off the JS thread; includes schema version and clock anchor. */
+  exportJson(): Promise<string>
+  /** Chrome Trace Event JSON for ui.perfetto.dev; serialized off the JS thread. */
+  exportTraceEvents(): Promise<string>
+  /** Start a native thread writing process.cpu, process.memory and ui.* frame metrics. Replaces a running sampler. */
+  startNativeSampling(options: NativeSamplingOptions): void
+  /** Stop native sampling. Idempotent; stop() and dispose() also stop it. */
+  stopNativeSampling(): void
+}

package/src/specs/TraceSpan.nitro.ts

@@ -0,0 +1,14 @@
+import type { HybridObject } from 'react-native-nitro-modules'
+import type { SpanOutcome } from '../types'
+/** A native span handle returned by Recording.startSpan. */
+export interface TraceSpan extends HybridObject<{
+  ios: 'c++'
+  android: 'c++'
+}> {
+  /** Empty when rejected by capacity limits. */
+  readonly spanId: string
+  /** Whether capacity allowed this span to be recorded. */
+  readonly recorded: boolean
+  /** Complete once. Repeated completion and completion after stop are no-ops. */
+  end(outcome: SpanOutcome): void
+}

package/src/specs/Tracing.nitro.ts

@@ -0,0 +1,14 @@
+import type { HybridObject } from 'react-native-nitro-modules'
+import type { Recording } from './Recording.nitro'
+import type { RecordingOptions } from '../types'
+/** Factory for independent native recordings. Exported as Tracing. */
+export interface Tracing extends HybridObject<{ ios: 'c++'; android: 'c++' }> {
+  /** Create an active recording with explicit validated retention limits. */
+  startRecording(options: RecordingOptions): Recording
+  /**
+   * Stop Hermes' process-wide sampling profiler. The release-profiler plugin calls this
+   * after saving a profile: on React Native 0.85 Android the profiler's own stop restarts
+   * sampling. Returns false where Hermes is not linked (iOS stops correctly itself).
+   */
+  disableHermesSampling(): boolean
+}

package/src/types/CompletedSpanOptions.ts

@@ -0,0 +1,15 @@
+import type { SpanOutcome } from './SpanOutcome'
+import type { SpanOptions } from './SpanOptions'
+/** Completed external measurement in Recording's native clock domain. */
+export interface CompletedSpanOptions extends SpanOptions {
+  /** Optional source-qualified identity, for example sentry:traceId:spanId. */
+  sourceSpanId?: string
+  /** Source-qualified parent identity; resolves even when parent ends later. */
+  sourceParentSpanId?: string
+  /** Start in milliseconds relative to recording creation. */
+  timestampMs: number
+  /** Finite nonnegative duration. */
+  durationMs: number
+  /** Terminal result from the measurement source. */
+  outcome: SpanOutcome
+}

package/src/types/EventContext.ts

@@ -0,0 +1,8 @@
+import type { TraceContext } from './TraceContext'
+/** Immutable native event identity and timing shared by recorded variants. */
+export interface EventContext extends TraceContext {
+  /** Increasing session-local completion sequence. */
+  sequence: number
+  /** Milliseconds since recording creation on its native monotonic clock. */
+  timestampMs: number
+}

package/src/types/MarkEvent.ts

@@ -0,0 +1,3 @@
+import type { EventContext } from './EventContext'
+/** Point-in-time event from Recording.readEvents. */
+export interface MarkEvent extends EventContext {}

package/src/types/MarkOptions.ts

@@ -0,0 +1,6 @@
+import type { TraceContext } from './TraceContext'
+/** Native mark, optionally imported with a translated source timestamp. */
+export interface MarkOptions extends TraceContext {
+  /** Milliseconds in the recording clock; omit to record now. */
+  timestampMs?: number
+}

package/src/types/MetricEvent.ts

@@ -0,0 +1,8 @@
+import type { EventContext } from './EventContext'
+/** Numeric sample from Recording.readEvents. */
+export interface MetricEvent extends EventContext {
+  /** Finite numeric sample. */
+  value: number
+  /** Sample unit. */
+  unit: string
+}

package/src/types/MetricOptions.ts

@@ -0,0 +1,10 @@
+import type { TraceContext } from './TraceContext'
+/** Input to Recording.recordMetric. */
+export interface MetricOptions extends TraceContext {
+  /** Optional source timestamp translated to the recording clock. */
+  timestampMs?: number
+  /** Finite numeric sample. */
+  value: number
+  /** Unit, for example bytes, byte/second, count, millisecond. */
+  unit: string
+}

package/src/types/NativeSamplingOptions.ts

@@ -0,0 +1,7 @@
+/** Native sampler settings for Recording.startNativeSampling. */
+export interface NativeSamplingOptions {
+  /** Window length for CPU, memory and frame metrics; 250–60000 ms. */
+  intervalMs: number
+  /** Observe main-thread display callbacks (CADisplayLink / Choreographer). */
+  frames: boolean
+}

package/src/types/ReadOptions.ts

@@ -0,0 +1,7 @@
+/** Bounded page query for Recording.readEvents; sequence zero starts at history. */
+export interface ReadOptions {
+  /** Exclusive completion sequence cursor. */
+  afterSequence: number
+  /** Maximum total events returned across all arrays; 1–1000. */
+  limit: number
+}

package/src/types/RecordingOptions.ts

@@ -0,0 +1,11 @@
+/** Native retention limits for Tracing.startRecording. All fields are required. */
+export interface RecordingOptions {
+  /** Maximum completed events retained; 1–100000. */
+  maxEvents: number
+  /** Retained payload budget including active spans; 1024–67108864 bytes. */
+  maxBytes: number
+  /** Maximum simultaneously active spans; 1–10000. */
+  maxActiveSpans: number
+  /** Expire abandoned spans on the next recorder access; milliseconds. */
+  spanTimeoutMs: number
+}

package/src/types/RecordingStats.ts

@@ -0,0 +1,25 @@
+/** Snapshot of a recording, returned by Recording.getStats. */
+export interface RecordingStats {
+  /** Recording identity. */
+  sessionId: string
+  /** Wall-clock anchor in Unix milliseconds, for correlation/export only. */
+  startedAtUnixMs: number
+  /** Native elapsed milliseconds at snapshot time. */
+  nowMs: number
+  /** Whether writes are accepted. */
+  recording: boolean
+  /** Retained completed events. */
+  eventCount: number
+  /** Accounted native payload bytes, including active spans. */
+  retainedBytes: number
+  /** Evicted or rejected event/span count. */
+  droppedEvents: number
+  /** Open spans. */
+  activeSpans: number
+  /** Evicted or rejected spans (part of droppedEvents). */
+  droppedSpans: number
+  /** Evicted or rejected marks (part of droppedEvents). */
+  droppedMarks: number
+  /** Evicted or rejected metric samples; rolled-over samples are not counted. */
+  droppedMetrics: number
+}