@goliapkg/sentori-react-native 1.3.0 → 2.1.0

package/src/runtime-metrics-network.ts

@@ -0,0 +1,103 @@
+// v2.1 W2 part 4 — network bytes auto-instrument.
+//
+// Two counters (sent / received bytes) incremented by the existing
+// fetch patch on every request/response, drained every 30 s as
+// runtime.network.bytes_sent + runtime.network.bytes_received.
+//
+// Best-effort: not every Response exposes `content-length`
+// (chunked encoding, server stripped it, gzipped without a
+// pre-decode header). For those we report 0 — undercounts vs.
+// over-attributing arbitrary numbers. Request body size is
+// estimated only when init.body is a string or has `.byteLength`;
+// FormData / Blob / ReadableStream are not measured.
+//
+// XHR is NOT instrumented here — the existing patchXhr() in
+// handlers/network.ts does the trace span work, and XHR usage in
+// 2026-era RN apps is rare enough that the engineering cost of
+// a second patch isn't justified by the missing data. If a host
+// app shows up with significant XHR traffic we add it in a patch
+// release.
+
+import { emitMetric } from '@goliapkg/sentori-core';
+
+const TICK_MS = 30_000;
+
+let _bytesSent = 0;
+let _bytesReceived = 0;
+let _timer: null | ReturnType<typeof setInterval> = null;
+
+/** Called from handlers/network.ts on every outbound request.
+ *  Cheap — two adds, no allocation. */
+export function recordNetworkBytes(sent: number, received: number): void {
+  if (sent > 0) _bytesSent += sent;
+  if (received > 0) _bytesReceived += received;
+}
+
+function estimateBodyBytes(body: BodyInit | null | undefined): number {
+  if (body == null) return 0;
+  if (typeof body === 'string') return body.length;
+  // ArrayBuffer / Uint8Array / ArrayBufferView all carry byteLength.
+  const maybe = body as { byteLength?: number };
+  if (typeof maybe.byteLength === 'number') return maybe.byteLength;
+  // FormData / Blob / ReadableStream — not measured.
+  return 0;
+}
+
+/** Estimate request bytes from a fetch init. Used by the fetch
+ *  patch in handlers/network.ts. */
+export function estimateRequestBytes(init?: RequestInit): number {
+  return estimateBodyBytes(init?.body);
+}
+
+/** Read response bytes from the Content-Length header. Returns
+ *  0 if missing or unparseable — undercount-safe. */
+export function estimateResponseBytes(headers: Headers | undefined | null): number {
+  if (!headers) return 0;
+  const v = headers.get?.('content-length');
+  if (!v) return 0;
+  const n = parseInt(v, 10);
+  return Number.isFinite(n) && n > 0 ? n : 0;
+}
+
+function emit(): void {
+  if (_bytesSent > 0) {
+    emitMetric('runtime.network.bytes_sent', _bytesSent);
+    _bytesSent = 0;
+  }
+  if (_bytesReceived > 0) {
+    emitMetric('runtime.network.bytes_received', _bytesReceived);
+    _bytesReceived = 0;
+  }
+}
+
+/** Idempotent start — second call is a no-op. */
+export function startNetworkBytesInstrument(): void {
+  if (_timer !== null) return;
+  _timer = setInterval(emit, TICK_MS);
+  (_timer as unknown as { unref?: () => void }).unref?.();
+}
+
+/** Stop the periodic emit. Idempotent. */
+export function stopNetworkBytesInstrument(): void {
+  if (_timer !== null) {
+    clearInterval(_timer);
+    _timer = null;
+  }
+}
+
+/** Test-only: force one emit tick + reset counters. */
+export function __forceNetworkEmitForTests(): void {
+  emit();
+}
+
+/** Test-only: peek raw counter state without resetting. */
+export function __peekNetworkCountersForTests(): { sent: number; received: number } {
+  return { sent: _bytesSent, received: _bytesReceived };
+}
+
+/** Test-only: reset for clean test runs. */
+export function __resetNetworkBytesForTests(): void {
+  stopNetworkBytesInstrument();
+  _bytesSent = 0;
+  _bytesReceived = 0;
+}

package/src/runtime-metrics.ts

@@ -0,0 +1,122 @@
+// v2.1 W2 part 2 — RN runtime metrics flusher + cold-start
+// instrument.
+//
+// The buffer + emit primitives live in @goliapkg/sentori-core
+// (runtime-metrics.ts). This module owns:
+//   • the periodic flush timer (30 s, coalesced w/ event flush)
+//   • the rebuffer-on-failure recovery path
+//   • the cold-start auto-instrument (one-shot at init)
+//
+// Other auto-instrument modules (FPS / heap / route-nav / network
+// bytes) ship in the W2 part 3+ chunks; each is its own file with
+// its own per-tick perf budget test gated as stop-ship in CI.
+//
+// NEVER rule: every public surface here is wrapped in safeFn
+// boundaries by the SDK init layer; the flush timer itself
+// catches all rejections + reports via the circuit breaker.
+
+import {
+  drainRuntimeMetricsForFlush,
+  emitMetric,
+  rebufferRuntimeMetrics,
+  reportInternal,
+} from '@goliapkg/sentori-core';
+
+import { getConfig, isInitialized } from './config';
+import { sendRuntimeMetricsBatch } from './transport';
+
+const FLUSH_INTERVAL_MS = 30_000;
+
+let _timer: null | ReturnType<typeof setInterval> = null;
+let _coldStartT0: null | number = null;
+let _coldStartEmitted = false;
+
+/**
+ * Drain core's runtime-metrics ring and POST to
+ * /v1/runtime-metrics:batch. Rebuffers on failure so the next
+ * tick retries; sustained outages spill into the ring's drop
+ * counter which reports to the SDK self-report channel.
+ *
+ * Returns when the round-trip settles (success or failure). Per
+ * the NEVER rule, never throws — failure is logged + rebuffered,
+ * the resolved promise's value is undefined.
+ */
+export async function flushRuntimeMetrics(): Promise<void> {
+  if (!isInitialized()) return;
+  const config = getConfig();
+  if (!config) return;
+  const batch = drainRuntimeMetricsForFlush();
+  if (batch.length === 0) return;
+  const ok = await sendRuntimeMetricsBatch(config.ingestUrl, config.token, batch);
+  if (!ok) {
+    rebufferRuntimeMetrics(batch);
+    reportInternal('runtime-metrics.flush', new Error('runtime-metrics POST failed'));
+  }
+}
+
+/**
+ * Start the 30 s flush timer. Called once from `init()`. Idempotent
+ * — repeated calls are a no-op so users that call
+ * `Sentori.init({ metrics: true })` more than once (HMR, fast
+ * refresh) don't get multiple timers.
+ */
+export function startRuntimeMetricsTimer(): void {
+  if (_timer !== null) return;
+  _timer = setInterval(() => {
+    void flushRuntimeMetrics();
+  }, FLUSH_INTERVAL_MS);
+  // Don't keep Node alive solely for this timer. RN's setInterval
+  // is a NoopRef so this is harmless there; Node + CLI tests
+  // benefit so the process can exit cleanly.
+  (_timer as unknown as { unref?: () => void }).unref?.();
+}
+
+/**
+ * Capture the wall-clock at `init()` so cold-start instrumentation
+ * has a t0. Called from init() before any other auto-instrument
+ * fires. Returns the captured t0 in millis (callers that want to
+ * stash + use it later can hold the value).
+ */
+export function markColdStartT0(): number {
+  if (_coldStartT0 === null) {
+    _coldStartT0 = Date.now();
+  }
+  return _coldStartT0;
+}
+
+/**
+ * Emit one `runtime.cold_start_ms` metric point. Idempotent per
+ * session — the second + later calls are a no-op so route-nav
+ * instrument (W2 part 3) can call this safely without worrying
+ * about double-counting.
+ *
+ * Hosts that want a more interactive-pixel-perfect cold-start
+ * boundary (TTI vs. raw init→render) can call
+ * `markTimeToFullDisplay()` and we emit that separately as
+ * `runtime.time_to_full_display_ms` (existing v1 instrument).
+ */
+export function emitColdStart(): void {
+  if (_coldStartEmitted) return;
+  if (_coldStartT0 === null) return;
+  const ms = Date.now() - _coldStartT0;
+  if (ms <= 0 || ms > 60_000) {
+    // Implausible — likely the host called emit before init or
+    // we got into a freeze-then-resume situation. Drop silently.
+    return;
+  }
+  emitMetric('runtime.cold_start_ms', ms);
+  _coldStartEmitted = true;
+}
+
+/**
+ * Test-only escape hatch: stop the timer + reset cold-start state
+ * so vitest / bun:test teardown doesn't leak intervals across runs.
+ */
+export function __resetRuntimeMetricsRnForTests(): void {
+  if (_timer !== null) {
+    clearInterval(_timer);
+    _timer = null;
+  }
+  _coldStartT0 = null;
+  _coldStartEmitted = false;
+}

package/src/track.ts

@@ -17,6 +17,7 @@
 // Hosts that don't use react-navigation can call
 // `sentori.track('$pageview', { route: 'Cart' })` themselves.
 
+import { addInternalBreadcrumb } from './breadcrumbs';
 import { getCurrentUserId } from './capture';
 import { getConfig, isInitialized } from './config';
 import { sendTrackBatch } from './transport';
@@ -74,6 +75,14 @@ export function track(name: string, props?: TrackProps, route?: string): void {
     userId: getCurrentUserId(),
   };
   _buf.push(ev);
+  // v2.0 W3 — auto-breadcrumb. When `init.capture.trackAutoBreadcrumb`
+  // is `true`, push a `{ type: 'track', data: { name, props } }`
+  // breadcrumb so the customer journey leading up to a later
+  // `captureException` / `captureMessage` is visible in the dashboard.
+  // Defaults off — see Config.trackAutoBreadcrumb docstring.
+  if (config?.trackAutoBreadcrumb === true) {
+    addInternalBreadcrumb('track', props ? { name, props } : { name });
+  }
   if (_buf.length >= MAX_BUFFER) {
     void flushTrack();
   }

package/src/transport.ts

@@ -330,6 +330,45 @@ export const sendMetricsBatch = async (
   }
 };
 
+/**
+ * v2.1 W2 — POST a batched set of auto-instrument runtime metric
+ * points. Sibling of sendMetricsBatch; different endpoint
+ * (`/v1/runtime-metrics:batch`) because the storage shape +
+ * validation rules + rate-limit budget differ — see
+ * docs/design/v2-metrics.md.
+ *
+ * Returns true on 2xx so the caller can leave the batch drained;
+ * returns false on anything else (network error / non-2xx) so the
+ * caller rebuffer-and-retries on the next flush via
+ * `rebufferRuntimeMetrics(batch)`.
+ */
+export const sendRuntimeMetricsBatch = async (
+  ingestUrl: string,
+  token: string,
+  metrics: Array<{
+    name: string;
+    tags?: Record<string, string>;
+    ts: string;
+    value: number;
+  }>,
+): Promise<boolean> => {
+  if (metrics.length === 0) return true;
+  try {
+    const resp = await fetch(`${ingestUrl}/v1/runtime-metrics:batch`, {
+      body: JSON.stringify({ metrics }),
+      headers: {
+        Authorization: `Bearer ${token}`,
+        'Content-Type': 'application/json',
+        'Sentori-Sdk': `react-native/${SDK_VERSION}`,
+      },
+      method: 'POST',
+    });
+    return resp.ok;
+  } catch {
+    return false;
+  }
+};
+
 /**
  * v0.8.2 — submit a user-supplied bug report. Fire-and-forget; resolves
  * with the server-assigned id on success or `null` on any failure.