react-native-nitro-tracing 0.6.0

package/lib/commonjs/client.cjs

@@ -0,0 +1,767 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __esm = (fn, res, err) => function __init() {
+  if (err) throw err[0];
+  try {
+    return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+  } catch (e) {
+    throw err = [e], e;
+  }
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  Tracing: () => Tracing
+});
+var import_react_native_nitro_modules, Tracing;
+var init_src = __esm({
+  "src/index.ts"() {
+    "use strict";
+    import_react_native_nitro_modules = require("react-native-nitro-modules");
+    Tracing = import_react_native_nitro_modules.NitroModules.createHybridObject("Tracing");
+  }
+});
+
+// client.ts
+var client_exports = {};
+__export(client_exports, {
+  createTraceClient: () => createTraceClient
+});
+module.exports = __toCommonJS(client_exports);
+
+// src/plugins/runtimeMetrics.ts
+var nativeHost = () => {
+  const { AppState } = require("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)
+  };
+};
+function createRuntimeMetricsPlugin(options = {}, host) {
+  const interval = options.intervalMs ?? 1e3;
+  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;
+      let frame;
+      let started = 0;
+      let previousFrame;
+      let frames = 0;
+      let maxGap = 0;
+      let longGaps = 0;
+      const reset = () => {
+        started = api.now();
+        frames = 0;
+        maxGap = 0;
+        longGaps = 0;
+      };
+      const emit = (name, value, unit) => {
+        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 !== void 0) {
+          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 * 1e3 / 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 !== void 0) api.cancelFrame(frame);
+        frame = void 0;
+      };
+      const change = (next) => {
+        if (stopped || next === active) return;
+        active = next;
+        previousFrame = void 0;
+        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();
+        }
+      };
+    }
+  };
+}
+
+// src/client/TracingSink.ts
+function formatTracingEntry(entry) {
+  const attributes = entry.attributes;
+  const id = attributes?.id;
+  const suffix = typeof id === "string" ? ` [${id.slice(-6)}]` : "";
+  const details = Object.entries(attributes ?? {}).filter(([key, value]) => key !== "id" && value !== void 0).map(([key, value]) => `${key}=${value}`);
+  const detail = details.length ? ` {${details.join(" ")}}` : "";
+  const label = entry.entryType === "metric" ? `${entry.name}=${entry.value}` : entry.entryType === "measure" ? `${entry.name} ${entry.durationMs.toFixed(0)}ms` : entry.name;
+  return `${label}${suffix}${detail}`;
+}
+
+// src/plugins/performance.ts
+function createPerformancePlugin(api, onEntry) {
+  return {
+    id: "performance",
+    start({ recording, reportError }) {
+      const offset = recording.getStats().nowMs - api.performance.now();
+      let stopped = false;
+      const ingest = (entries) => {
+        if (stopped) return;
+        for (const entry of entries) {
+          try {
+            const timestampMs = entry.startTime + offset;
+            if (timestampMs < 0) continue;
+            const data = entry;
+            onEntry?.({
+              name: entry.name,
+              entryType: entry.entryType,
+              durationMs: entry.duration,
+              value: typeof data.value === "string" || typeof data.value === "number" ? data.value : void 0,
+              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())
+      );
+      const supported = api.PerformanceObserver.supportedEntryTypes;
+      const entryTypes = ["mark", "measure", "metric", "longtask"].filter(
+        (type) => supported ? supported.includes(type) : type !== "longtask"
+      );
+      try {
+        observer.observe({ entryTypes });
+      } catch (error) {
+        observer.disconnect();
+        throw error;
+      }
+      return {
+        stop() {
+          if (stopped) return;
+          try {
+            ingest(observer.takeRecords());
+          } finally {
+            stopped = true;
+            observer.disconnect();
+          }
+        }
+      };
+    }
+  };
+}
+
+// src/plugins/startPlugins.ts
+function startPlugins(recording, plugins, onError) {
+  const handles = [];
+  const ids = /* @__PURE__ */ new Set();
+  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) => {
+    try {
+      onError(error);
+    } catch {
+    }
+  };
+  for (const plugin of plugins) {
+    try {
+      handles.push(plugin.start({ recording, reportError }));
+    } catch (error) {
+      reportError(error);
+    }
+  }
+  let stopping;
+  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;
+    }
+  };
+}
+
+// src/client/playground.ts
+var delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+var recordPlayground = async (current) => {
+  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) => 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 = [];
+    const metrics = [];
+    let afterSequence = 0;
+    for (let pageIndex = 0; pageIndex < 100; pageIndex++) {
+      const page = await current.readEvents({ afterSequence, limit: 1e3 });
+      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 < 1e3)
+        break;
+      afterSequence = page.nextSequence;
+    }
+    const concurrent = spans.filter(
+      (span) => span.name === "playground.concurrent"
+    );
+    const repeatedEvents = spans.filter(
+      (span) => span.spanId === repeated.spanId
+    );
+    const 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;
+  }
+};
+
+// src/client/createTraceClient.ts
+var defaultPerformanceApi = () => {
+  try {
+    const module2 = require("react-native-performance");
+    return {
+      performance: module2.default,
+      PerformanceObserver: module2.PerformanceObserver
+    };
+  } catch {
+    const global = globalThis;
+    return global.performance && global.PerformanceObserver ? global : void 0;
+  }
+};
+function createTraceClient(options = {}) {
+  let recording;
+  let handle;
+  const readinessStartMs = globalThis.performance.now();
+  let readyReported = false;
+  let enabled = false;
+  let disposed = false;
+  let pending = 0;
+  let tail = Promise.resolve();
+  let snapshot = {
+    visible: false,
+    recording: false,
+    busy: false,
+    disposed: false,
+    profiling: false
+  };
+  const listeners = /* @__PURE__ */ new Set();
+  const marks = /* @__PURE__ */ new Map();
+  const publish = (next = {}) => {
+    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 {
+      }
+    }
+  };
+  const reportError = (error) => {
+    publish({ error: String(error) });
+    try {
+      options.onError?.(error);
+    } catch {
+    }
+  };
+  const safely = (work) => {
+    try {
+      return work();
+    } catch (error) {
+      reportError(error);
+      return void 0;
+    }
+  };
+  const emit = (entry) => {
+    if (options.sink)
+      safely(() => options.sink(formatTracingEntry(entry), entry));
+  };
+  const enqueue = (work) => {
+    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 = void 0;
+      recording?.stop();
+      marks.clear();
+      publish();
+    }
+  };
+  const startCurrent = async () => {
+    await stopCurrent();
+    if (disposed) throw new Error("Trace client is disposed");
+    recording?.dispose();
+    recording = void 0;
+    const { Tracing: Tracing2 } = (init_src(), __toCommonJS(src_exports));
+    recording = Tracing2.startRecording({
+      // ~1-2 hours of spans for UAT sessions; metric samples use at most half.
+      maxEvents: 1e4,
+      maxBytes: 6 * 1024 * 1024,
+      maxActiveSpans: 256,
+      spanTimeoutMs: 30 * 60 * 1e3,
+      ...options.recordingOptions
+    });
+    publish({ error: void 0, playground: void 0 });
+    try {
+      const plugins = [...options.plugins ?? []];
+      const api = options.performance === false ? void 0 : options.performance ?? defaultPerformanceApi();
+      if (api)
+        plugins.unshift(
+          createPerformancePlugin(api, options.sink ? emit : void 0)
+        );
+      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 = void 0;
+      }
+      throw error;
+    }
+    enabled = true;
+    if (options.autoProfile && options.profiler)
+      safely(() => options.profiler.startProfiling());
+    publish();
+  };
+  const context = (name, attributes) => ({
+    name,
+    correlationId: String(attributes?.id ?? ""),
+    attributes: Object.entries(attributes ?? {}).filter(([, value]) => value !== void 0).slice(0, 32).map(([key, value]) => ({
+      key: key.slice(0, 64),
+      value: String(value).slice(0, 512)
+    }))
+  });
+  const trace = {
+    mark(name, attributes) {
+      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: /* @__PURE__ */ new Map(), emitted: /* @__PURE__ */ 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, value, attributes) {
+      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(name, fn, attributes) {
+      const started = enabled && options.sink ? globalThis.performance.now() : void 0;
+      const span = safely(
+        () => enabled ? recording?.startSpan(context(name, attributes)) : void 0
+      );
+      try {
+        const value = await fn();
+        safely(() => span?.end("success"));
+        return value;
+      } catch (error) {
+        safely(() => span?.end("error"));
+        throw error;
+      } finally {
+        if (started !== void 0)
+          emit({
+            name,
+            entryType: "measure",
+            durationMs: Math.max(0, globalThis.performance.now() - started),
+            attributes
+          });
+      }
+    },
+    measureSince(name, startName, id, attributes) {
+      safely(() => {
+        if (!enabled || !recording) return;
+        const bucket = marks.get(id);
+        const start = bucket?.marks.get(startName);
+        if (start === void 0 || 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) {
+      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) {
+      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 = "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) => {
+      trace.mark("flag", { source: "flag", note });
+      const profiler = options.profiler;
+      const windowMs = options.flagProfileMs ?? 1e4;
+      if (!profiler || windowMs <= 0) return;
+      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 = void 0;
+            listeners.clear();
+          }
+        }
+      });
+      tail = result.catch(reportError);
+      return result;
+    }
+  };
+}
+//# sourceMappingURL=client.cjs.map