react-native-nitro-tracing 0.6.0

package/src/plugins/runtimeMetrics.ts

@@ -0,0 +1,131 @@
+import type { TracePlugin } from './TracePlugin'
+export interface RuntimeMetricsOptions {
+  /** Reporting interval in ms, minimum 250; default 1000. */
+  intervalMs?: number
+  /** Observe JS requestAnimationFrame callbacks (not native UI frames). Default true. */
+  frames?: boolean
+}
+/** Injectable clock/lifecycle surface for deterministic tests and alternate hosts. */
+export interface RuntimeMetricsHost {
+  now(): number
+  isActive(): boolean
+  subscribe(listener: (active: boolean) => void): () => void
+  requestFrame(callback: () => void): number
+  cancelFrame(id: number): void
+}
+const nativeHost = (): RuntimeMetricsHost => {
+  const { AppState } = require('react-native') as typeof import('react-native')
+  return {
+    now: () => globalThis.performance.now(),
+    isActive: () => AppState.currentState === 'active',
+    subscribe: (listener) => {
+      const subscription = AppState.addEventListener('change', (state) =>
+        listener(state === 'active')
+      )
+      return () => subscription.remove()
+    },
+    requestFrame: (callback) => requestAnimationFrame(callback),
+    cancelFrame: (id) => cancelAnimationFrame(id),
+  }
+}
+/** Low-volume foreground JS health samples. No per-frame native calls or UI FPS claims. */
+export function createRuntimeMetricsPlugin(
+  options: RuntimeMetricsOptions = {},
+  host?: RuntimeMetricsHost
+): TracePlugin {
+  const interval = options.intervalMs ?? 1000
+  if (!Number.isFinite(interval) || interval < 250)
+    throw new Error('Runtime metrics interval must be at least 250ms')
+  return {
+    id: 'runtime-metrics',
+    start({ recording, reportError }) {
+      const api = host ?? nativeHost()
+      let stopped = false
+      let active = false
+      let timer: ReturnType<typeof setTimeout> | undefined
+      let frame: number | undefined
+      let started = 0
+      let previousFrame: number | undefined
+      let frames = 0
+      let maxGap = 0
+      let longGaps = 0
+      const reset = () => {
+        started = api.now()
+        frames = 0
+        maxGap = 0
+        longGaps = 0
+      }
+      const emit = (name: string, value: number, unit: string) => {
+        try {
+          recording.recordMetric({
+            name,
+            value,
+            unit,
+            correlationId: '',
+            attributes: [
+              { key: 'source', value: 'js-runtime' },
+              { key: 'scope', value: 'foreground' },
+              { key: 'windowMs', value: String(api.now() - started) },
+            ],
+          })
+        } catch (error) {
+          reportError(error)
+        }
+      }
+      const onFrame = () => {
+        if (stopped || !active) return
+        const now = api.now()
+        if (previousFrame !== undefined) {
+          const gap = Math.max(0, now - previousFrame)
+          maxGap = Math.max(maxGap, gap)
+          if (gap > 50) longGaps++
+        }
+        previousFrame = now
+        frames++
+        frame = api.requestFrame(onFrame)
+      }
+      const tick = () => {
+        if (stopped || !active) return
+        const elapsed = api.now() - started
+        emit('js.event_loop.delay', Math.max(0, elapsed - interval), 'ms')
+        if (options.frames !== false && elapsed > 0) {
+          emit(
+            'js.frame_callback.rate',
+            (frames * 1000) / elapsed,
+            'callbacks/s'
+          )
+          if (frames > 1) emit('js.frame_gap.max', maxGap, 'ms')
+          emit('js.frame_gap.over_50ms', longGaps, 'count')
+        }
+        reset()
+        timer = setTimeout(tick, interval)
+      }
+      const suspend = () => {
+        clearTimeout(timer)
+        if (frame !== undefined) api.cancelFrame(frame)
+        frame = undefined
+      }
+      const change = (next: boolean) => {
+        if (stopped || next === active) return
+        active = next
+        previousFrame = undefined
+        suspend()
+        reset()
+        if (active) {
+          timer = setTimeout(tick, interval)
+          if (options.frames !== false) frame = api.requestFrame(onFrame)
+        }
+      }
+      const unsubscribe = api.subscribe(change)
+      change(api.isActive())
+      return {
+        stop() {
+          stopped = true
+          active = false
+          suspend()
+          unsubscribe()
+        },
+      }
+    },
+  }
+}

package/src/plugins/sentry.ts

@@ -0,0 +1,176 @@
+import type * as Sentry from '@sentry/react-native'
+import type { SpanEvent } from '../types'
+import type { TracePlugin } from './TracePlugin'
+import { orderSpans } from './orderSpans'
+/** Optional Sentry capabilities; SDK initialization and consent remain app-owned. */
+export interface SentryPluginOptions {
+  /** Inject an installed SDK. This module has no runtime SDK dependency. */
+  sentry: Pick<typeof Sentry, 'getClient' | 'spanToJSON' | 'startInactiveSpan'>
+  /** Capture observable SDK spans locally. Defaults to false; sampling applies. */
+  captureSpans?: boolean
+  /** Explicitly opt into sending retained span names/timing/status to Sentry on stop. Defaults to false. */
+  exportSpans?: boolean
+  /** Only these sanitized custom attribute keys may leave the device. Defaults to none. */
+  exportedAttributeKeys?: readonly string[]
+}
+/** Optional SDK measurements and opt-in export; neither direction is enabled implicitly. */
+export function createSentryPlugin(options: SentryPluginOptions): TracePlugin {
+  return {
+    id: 'sentry',
+    start({ recording, reportError }) {
+      const { sentry } = options
+      const stats = recording.getStats()
+      const anchor = stats.startedAtUnixMs
+      const client = sentry.getClient()
+      if (options.captureSpans && !client)
+        throw new Error('Initialize Sentry before enabling local capture')
+      /** Sentry as the measurement layer: its frame and app-start data use the native metric names. */
+      const recordMeasurements = (
+        data: ReturnType<typeof sentry.spanToJSON>,
+        start: number,
+        anchorMs: number
+      ) => {
+        const end = (data.timestamp ?? data.start_timestamp) * 1000 - anchorMs
+        const metric = (name: string, value: unknown, unit: string) => {
+          if (typeof value !== 'number' || !Number.isFinite(value)) return
+          recording.recordMetric({
+            name,
+            value,
+            unit,
+            timestampMs: Math.max(0, end),
+            correlationId: data.trace_id,
+            attributes: [
+              { key: 'source', value: 'sentry' },
+              {
+                key: 'span',
+                value: (data.description || data.op || '').slice(0, 256),
+              },
+            ],
+          })
+        }
+        // Set by Sentry's nativeFrames integration on spans it measured.
+        metric('ui.frames.total', data.data?.['frames.total'], 'count')
+        metric('ui.frames.slow', data.data?.['frames.slow'], 'count')
+        metric('ui.frames.frozen', data.data?.['frames.frozen'], 'count')
+        // appStart integration spans: app.start.cold / app.start.warm.
+        if (data.op === 'app.start.cold' || data.op === 'app.start.warm')
+          metric(data.op, end - start, 'ms')
+      }
+      const unsubscribe = options.captureSpans
+        ? client!.on('spanEnd', (span) => {
+            try {
+              const data = sentry.spanToJSON(span)
+              if (data.data?.['nitro.exported'] || data.timestamp === undefined)
+                return
+              const start = data.start_timestamp * 1000 - anchor
+              if (start < 0) return
+              recording.recordSpan({
+                name: (data.description || data.op || 'sentry.span').slice(
+                  0,
+                  128
+                ),
+                correlationId: data.trace_id,
+                timestampMs: start,
+                sourceSpanId: `sentry:${data.trace_id}:${data.span_id}`,
+                sourceParentSpanId: data.parent_span_id
+                  ? `sentry:${data.trace_id}:${data.parent_span_id}`
+                  : undefined,
+                durationMs: Math.max(
+                  0,
+                  (data.timestamp - data.start_timestamp) * 1000
+                ),
+                outcome:
+                  data.status && data.status !== 'ok' ? 'error' : 'success',
+                attributes: [
+                  { key: 'source', value: 'sentry' },
+                  { key: 'sentry.span_id', value: data.span_id },
+                  {
+                    key: 'sentry.parent_span_id',
+                    value: data.parent_span_id || '',
+                  },
+                ],
+              })
+              recordMeasurements(data, start, anchor)
+            } catch (error) {
+              reportError(error)
+            }
+          })
+        : undefined
+      return {
+        stop() {
+          unsubscribe?.()
+        },
+        async flush() {
+          if (options.exportSpans !== true) return
+          if (!sentry.getClient())
+            throw new Error('Initialize Sentry before exporting traces')
+          const spans: SpanEvent[] = []
+          let cursor = 0
+          while (true) {
+            const page = await recording.readEvents({
+              afterSequence: cursor,
+              limit: 1000,
+            })
+            spans.push(
+              ...page.spans.filter(
+                (s) =>
+                  !s.attributes.some(
+                    (a) => a.key === 'source' && a.value === 'sentry'
+                  )
+              )
+            )
+            if (page.nextSequence === cursor) break
+            cursor = page.nextSequence
+          }
+          const ordered = orderSpans(spans)
+          const handles = new Map<
+            string,
+            ReturnType<typeof sentry.startInactiveSpan>
+          >()
+          const keys = new Set(options.exportedAttributeKeys ?? [])
+          for (let index = 0; index < ordered.length; index++) {
+            if (index > 0 && index % 250 === 0)
+              await new Promise<void>((resolve) => setTimeout(resolve, 0))
+            const span = ordered[index]!
+            const id = span.spanId
+            const parentSpan = handles.get(span.parentSpanId)
+            const exported = sentry.startInactiveSpan({
+              name: span.name,
+              op: 'nitro.trace',
+              startTime: (anchor + span.timestampMs) / 1000,
+              parentSpan: parentSpan ?? null,
+              forceTransaction: !parentSpan,
+              attributes: {
+                ...Object.fromEntries(
+                  span.attributes
+                    .filter((a) => keys.has(a.key))
+                    .map((a) => [a.key, a.value])
+                ),
+                'nitro.exported': true,
+                'nitro.span_id': id,
+                'nitro.parent_missing': Boolean(
+                  span.parentSpanId && !parentSpan
+                ),
+                'nitro.outcome': span.outcome,
+              },
+            })
+            exported.setStatus(
+              span.outcome === 'success'
+                ? { code: 1 }
+                : { code: 2, message: span.outcome }
+            )
+            handles.set(id, exported)
+          }
+          for (let index = ordered.length - 1; index >= 0; index--) {
+            const span = ordered[index]!
+            handles
+              .get(span.spanId)!
+              .end((anchor + span.timestampMs + span.durationMs) / 1000)
+            if (index > 0 && index % 250 === 0)
+              await new Promise<void>((resolve) => setTimeout(resolve, 0))
+          }
+        },
+      }
+    },
+  }
+}

package/src/plugins/startPlugins.ts

@@ -0,0 +1,58 @@
+import type { Recording } from '../specs/Recording.nitro'
+import type { PluginHandle, TracePlugin } from './TracePlugin'
+/** Start optional integrations. Failures are isolated; stop waits for all cleanup. */
+export function startPlugins(
+  recording: Recording,
+  plugins: readonly TracePlugin[],
+  onError: (error: unknown) => void
+): PluginHandle {
+  const handles: PluginHandle[] = []
+  const ids = new Set<string>()
+  for (const plugin of plugins) {
+    if (ids.has(plugin.id))
+      throw new Error(`Duplicate tracing plugin: ${plugin.id}`)
+    ids.add(plugin.id)
+  }
+  const reportError = (error: unknown) => {
+    try {
+      onError(error)
+    } catch {
+      /* Error reporters cannot break capture. */
+    }
+  }
+  for (const plugin of plugins) {
+    try {
+      handles.push(plugin.start({ recording, reportError }))
+    } catch (error) {
+      reportError(error)
+    }
+  }
+  let stopping: Promise<void> | undefined
+  return {
+    stop() {
+      if (!stopping)
+        stopping = (async () => {
+          for (const handle of [...handles].reverse()) {
+            try {
+              await handle.stop()
+            } catch (error) {
+              reportError(error)
+            }
+          }
+          try {
+            recording.stop()
+          } catch (error) {
+            reportError(error)
+          }
+          for (const handle of handles) {
+            try {
+              await handle.flush?.()
+            } catch (error) {
+              reportError(error)
+            }
+          }
+        })()
+      return stopping
+    },
+  }
+}