react-native-otel 0.1.0 → 0.1.5

package/src/exporters/otlp-http-exporter.ts

@@ -3,10 +3,16 @@ import type {
   LogRecord,
   MetricExporter,
   MetricRecord,
+  CounterRecord,
+  HistogramRecord,
+  GaugeRecord,
 } from './types';
 import type { Attributes } from '../core/attributes';
 import type { Resource } from '../core/resource';
 import type { ReadonlySpan, SpanExporter } from '../core/span';
+import type { StorageAdapter } from '../instrumentation/errors';
+import { Wal, fetchWithRetry } from './wal';
+import { SDK_VERSION } from '../version';
 
 // ─── OTLP attribute value serialization ──────────────────────────────────────
 
@@ -79,6 +85,7 @@ export class OtlpHttpExporter implements SpanExporter {
   private buffer: ReadonlySpan[] = [];
   private resource_: Readonly<Resource> | undefined;
   private timer_: ReturnType<typeof setInterval> | undefined;
+  private wal_: Wal<ReadonlySpan> | undefined;
 
   constructor(options: OtlpHttpExporterOptions) {
     this.tracesEndpoint = options.endpoint.replace(/\/$/, '') + '/v1/traces';
@@ -92,6 +99,8 @@ export class OtlpHttpExporter implements SpanExporter {
     this.timer_ = setInterval(() => {
       this.flush();
     }, interval);
+    // Allow Node.js to exit cleanly in test environments without calling destroy().
+    if (typeof this.timer_.unref === 'function') this.timer_.unref();
   }
 
   // Called by OtelSDK.init() after buildResource() — not part of SpanExporter.
@@ -99,6 +108,20 @@ export class OtlpHttpExporter implements SpanExporter {
     this.resource_ = resource;
   }
 
+  // Called by OtelSDK.init() when a StorageAdapter is configured.
+  // Initialises the WAL and replays any undelivered batches from the previous session.
+  setStorage(storage: StorageAdapter): void {
+    this.wal_ = new Wal<ReadonlySpan>(storage, '@react-native-otel/wal/spans');
+    this.replayWal();
+  }
+
+  private replayWal(): void {
+    if (!this.wal_) return;
+    for (const batch of this.wal_.readAll()) {
+      this.deliverBatch(batch.data as ReadonlySpan[], batch.id);
+    }
+  }
+
   export(spans: ReadonlySpan[]): void {
     this.buffer.push(...spans);
     if (this.buffer.length >= this.batchSize) {
@@ -109,7 +132,12 @@ export class OtlpHttpExporter implements SpanExporter {
   flush(): void {
     if (this.buffer.length === 0) return;
     const batch = this.buffer.splice(0);
-    this.send(batch);
+    if (this.wal_) {
+      const id = this.wal_.write(batch);
+      this.deliverBatch(batch, id);
+    } else {
+      this.deliverBatch(batch, undefined);
+    }
   }
 
   // Clear the flush timer and send any remaining buffered spans.
@@ -121,30 +149,41 @@ export class OtlpHttpExporter implements SpanExporter {
     this.flush();
   }
 
-  private send(spans: ReadonlySpan[]): void {
+  private deliverBatch(spans: ReadonlySpan[], walId: string | undefined): void {
+    const body = this.buildBody(spans);
+    fetchWithRetry(this.tracesEndpoint, {
+      method: 'POST',
+      headers: this.headers,
+      body,
+    })
+      .then((success) => {
+        if (success && walId !== undefined) {
+          this.wal_?.delete(walId);
+        }
+      })
+      .catch(() => {
+        // Leave in WAL for next session
+      });
+  }
+
+  private buildBody(spans: ReadonlySpan[]): string {
     const resourceAttrs = this.resource_
       ? toOtlpAttributes(this.resource_ as unknown as Record<string, unknown>)
       : [];
 
-    const body = JSON.stringify({
+    return JSON.stringify({
       resourceSpans: [
         {
           resource: { attributes: resourceAttrs },
           scopeSpans: [
             {
-              scope: { name: 'react-native-otel', version: '0.1.0' },
+              scope: { name: 'react-native-otel', version: SDK_VERSION },
               spans: spans.map((s) => this.toOtlpSpan(s)),
             },
           ],
         },
       ],
     });
-
-    fetch(this.tracesEndpoint, {
-      method: 'POST',
-      headers: this.headers,
-      body,
-    }).catch(() => {});
   }
 
   private toOtlpSpan(span: ReadonlySpan) {
@@ -163,6 +202,11 @@ export class OtlpHttpExporter implements SpanExporter {
         timeUnixNano: msToNano(event.timestampMs),
         attributes: toOtlpAttributes(event.attributes),
       })),
+      links: span.links.map((link) => ({
+        traceId: link.traceId,
+        spanId: link.spanId,
+        attributes: link.attributes ? toOtlpAttributes(link.attributes) : [],
+      })),
       droppedEventsCount: span.droppedEventsCount,
       status: {
         code: SPAN_STATUS_CODE[span.status] ?? 0,
@@ -175,18 +219,24 @@ export class OtlpHttpExporter implements SpanExporter {
 
 // ─── Metric exporter ──────────────────────────────────────────────────────────
 
-// OTLP aggregation temporality: 2 = CUMULATIVE
+// OTLP aggregation temporality constants
+const AGGREGATION_TEMPORALITY_DELTA = 1;
 const AGGREGATION_TEMPORALITY_CUMULATIVE = 2;
 
 export interface OtlpHttpMetricExporterOptions {
   endpoint: string;
   headers?: Record<string, string>;
+  // How often to auto-flush buffered metrics in ms. Default: 30_000.
+  flushIntervalMs?: number;
 }
 
 export class OtlpHttpMetricExporter implements MetricExporter {
   private readonly metricsEndpoint: string;
   private readonly headers: Record<string, string>;
   private resource_: Readonly<Resource> | undefined;
+  private wal_: Wal<MetricRecord> | undefined;
+  private timer_: ReturnType<typeof setInterval> | undefined;
+  private buffer_: MetricRecord[] = [];
 
   constructor(options: OtlpHttpMetricExporterOptions) {
     this.metricsEndpoint = options.endpoint.replace(/\/$/, '') + '/v1/metrics';
@@ -194,18 +244,82 @@ export class OtlpHttpMetricExporter implements MetricExporter {
       'Content-Type': 'application/json',
       ...options.headers,
     };
+
+    const interval = options.flushIntervalMs ?? 30_000;
+    this.timer_ = setInterval(() => {
+      this.flush();
+    }, interval);
+    // Allow Node.js to exit cleanly in test environments without calling destroy().
+    if (typeof this.timer_.unref === 'function') this.timer_.unref();
   }
 
   setResource(resource: Readonly<Resource>): void {
     this.resource_ = resource;
   }
 
+  setStorage(storage: StorageAdapter): void {
+    this.wal_ = new Wal<MetricRecord>(
+      storage,
+      '@react-native-otel/wal/metrics'
+    );
+    this.replayWal();
+  }
+
+  private replayWal(): void {
+    if (!this.wal_) return;
+    for (const batch of this.wal_.readAll()) {
+      this.deliverBatch(batch.data as MetricRecord[], batch.id);
+    }
+  }
+
   export(metrics: MetricRecord[]): void {
     if (metrics.length === 0) return;
-    this.send(metrics);
+    this.buffer_.push(...metrics);
+  }
+
+  // Drain buffered metrics and deliver them immediately.
+  // Called by the internal timer and also useful for testing / explicit flush.
+  flush(): void {
+    if (this.buffer_.length === 0) return;
+    const batch = this.buffer_.splice(0);
+    if (this.wal_) {
+      const id = this.wal_.write(batch);
+      this.deliverBatch(batch, id);
+    } else {
+      this.deliverBatch(batch, undefined);
+    }
+  }
+
+  // Clear the flush timer and send any remaining buffered metrics.
+  destroy(): void {
+    if (this.timer_ !== undefined) {
+      clearInterval(this.timer_);
+      this.timer_ = undefined;
+    }
+    this.flush();
+  }
+
+  private deliverBatch(
+    metrics: MetricRecord[],
+    walId: string | undefined
+  ): void {
+    const body = this.buildBody(metrics);
+    fetchWithRetry(this.metricsEndpoint, {
+      method: 'POST',
+      headers: this.headers,
+      body,
+    })
+      .then((success) => {
+        if (success && walId !== undefined) {
+          this.wal_?.delete(walId);
+        }
+      })
+      .catch(() => {
+        // Leave in WAL for next session
+      });
   }
 
-  private send(metrics: MetricRecord[]): void {
+  private buildBody(metrics: MetricRecord[]): string {
     const resourceAttrs = this.resource_
       ? toOtlpAttributes(this.resource_ as unknown as Record<string, unknown>)
       : [];
@@ -224,12 +338,11 @@ export class OtlpHttpMetricExporter implements MetricExporter {
     const otlpMetrics = Array.from(byName.entries()).map(([name, records]) => {
       const type = records[0]?.type;
 
-      // Counters → sum; histograms + gauges → gauge (no bucket data available).
       if (type === 'counter') {
         return {
           name,
           sum: {
-            dataPoints: records.map((r) => ({
+            dataPoints: (records as CounterRecord[]).map((r) => ({
               asDouble: r.value,
               startTimeUnixNano: msToNano(r.timestampMs),
               timeUnixNano: msToNano(r.timestampMs),
@@ -241,10 +354,32 @@ export class OtlpHttpMetricExporter implements MetricExporter {
         };
       }
 
+      if (type === 'histogram') {
+        return {
+          name,
+          histogram: {
+            dataPoints: (records as HistogramRecord[]).map((r) => ({
+              count: String(r.count),
+              sum: r.sum,
+              // bucketCounts in OTLP are string-encoded uint64
+              bucketCounts: r.bucketCounts.map(String),
+              // explicitBounds does not include the implicit +Inf upper bound
+              explicitBounds: r.bucketBoundaries,
+              startTimeUnixNano: msToNano(r.timestampMs),
+              timeUnixNano: msToNano(r.timestampMs),
+              attributes: toOtlpAttributes(r.attributes),
+            })),
+            // Each flush window is independent — use DELTA semantics.
+            aggregationTemporality: AGGREGATION_TEMPORALITY_DELTA,
+          },
+        };
+      }
+
+      // gauge
       return {
         name,
         gauge: {
-          dataPoints: records.map((r) => ({
+          dataPoints: (records as GaugeRecord[]).map((r) => ({
             asDouble: r.value,
             timeUnixNano: msToNano(r.timestampMs),
             attributes: toOtlpAttributes(r.attributes),
@@ -253,25 +388,19 @@ export class OtlpHttpMetricExporter implements MetricExporter {
       };
     });
 
-    const body = JSON.stringify({
+    return JSON.stringify({
       resourceMetrics: [
         {
           resource: { attributes: resourceAttrs },
           scopeMetrics: [
             {
-              scope: { name: 'react-native-otel', version: '0.1.0' },
+              scope: { name: 'react-native-otel', version: SDK_VERSION },
               metrics: otlpMetrics,
             },
           ],
         },
       ],
     });
-
-    fetch(this.metricsEndpoint, {
-      method: 'POST',
-      headers: this.headers,
-      body,
-    }).catch(() => {});
   }
 }
 
@@ -301,6 +430,7 @@ export class OtlpHttpLogExporter implements LogExporter {
   private buffer: LogRecord[] = [];
   private resource_: Readonly<Resource> | undefined;
   private timer_: ReturnType<typeof setInterval> | undefined;
+  private wal_: Wal<LogRecord> | undefined;
 
   constructor(options: OtlpHttpLogExporterOptions) {
     this.logsEndpoint = options.endpoint.replace(/\/$/, '') + '/v1/logs';
@@ -314,12 +444,27 @@ export class OtlpHttpLogExporter implements LogExporter {
     this.timer_ = setInterval(() => {
       this.flush();
     }, interval);
+    // Allow Node.js to exit cleanly in test environments without calling destroy().
+    if (typeof this.timer_.unref === 'function') this.timer_.unref();
   }
 
   setResource(resource: Readonly<Resource>): void {
     this.resource_ = resource;
   }
 
+  // Called by OtelSDK.init() when a StorageAdapter is configured.
+  setStorage(storage: StorageAdapter): void {
+    this.wal_ = new Wal<LogRecord>(storage, '@react-native-otel/wal/logs');
+    this.replayWal();
+  }
+
+  private replayWal(): void {
+    if (!this.wal_) return;
+    for (const batch of this.wal_.readAll()) {
+      this.deliverBatch(batch.data as LogRecord[], batch.id);
+    }
+  }
+
   export(logs: LogRecord[]): void {
     this.buffer.push(...logs);
     if (this.buffer.length >= this.batchSize) {
@@ -330,7 +475,12 @@ export class OtlpHttpLogExporter implements LogExporter {
   flush(): void {
     if (this.buffer.length === 0) return;
     const batch = this.buffer.splice(0);
-    this.send(batch);
+    if (this.wal_) {
+      const id = this.wal_.write(batch);
+      this.deliverBatch(batch, id);
+    } else {
+      this.deliverBatch(batch, undefined);
+    }
   }
 
   destroy(): void {
@@ -341,7 +491,19 @@ export class OtlpHttpLogExporter implements LogExporter {
     this.flush();
   }
 
-  private send(logs: LogRecord[]): void {
+  private deliverBatch(logs: LogRecord[], walId: string | undefined): void {
+    this.send(logs)
+      .then((success) => {
+        if (success && walId !== undefined) {
+          this.wal_?.delete(walId);
+        }
+      })
+      .catch(() => {
+        // Leave in WAL for next session
+      });
+  }
+
+  private send(logs: LogRecord[]): Promise<boolean> {
     const resourceAttrs = this.resource_
       ? toOtlpAttributes(this.resource_ as unknown as Record<string, unknown>)
       : [];
@@ -352,7 +514,7 @@ export class OtlpHttpLogExporter implements LogExporter {
           resource: { attributes: resourceAttrs },
           scopeLogs: [
             {
-              scope: { name: 'react-native-otel', version: '0.1.0' },
+              scope: { name: 'react-native-otel', version: SDK_VERSION },
               logRecords: logs.map((log) => ({
                 timeUnixNano: msToNano(log.timestampMs),
                 severityNumber: LOG_SEVERITY_NUMBER[log.severity] ?? 9,
@@ -368,10 +530,10 @@ export class OtlpHttpLogExporter implements LogExporter {
       ],
     });
 
-    fetch(this.logsEndpoint, {
+    return fetchWithRetry(this.logsEndpoint, {
       method: 'POST',
       headers: this.headers,
       body,
-    }).catch(() => {});
+    });
   }
 }

package/src/exporters/types.ts

@@ -3,14 +3,35 @@ import type { ReadonlySpan, SpanExporter } from '../core/span';
 
 export type { ReadonlySpan, SpanExporter };
 
-export interface MetricRecord {
-  type: 'counter' | 'histogram' | 'gauge';
+interface BaseMetricRecord {
   name: string;
-  value: number;
   timestampMs: number;
   attributes: Attributes;
 }
 
+export interface CounterRecord extends BaseMetricRecord {
+  type: 'counter';
+  value: number;
+}
+
+export interface GaugeRecord extends BaseMetricRecord {
+  type: 'gauge';
+  value: number;
+}
+
+export interface HistogramRecord extends BaseMetricRecord {
+  type: 'histogram';
+  // Aggregated data for the flush window
+  count: number;
+  sum: number;
+  // Explicit bucket upper bounds (last bucket is +Inf, implicit)
+  bucketBoundaries: number[];
+  // Length is bucketBoundaries.length + 1 (last entry = +Inf bucket)
+  bucketCounts: number[];
+}
+
+export type MetricRecord = CounterRecord | GaugeRecord | HistogramRecord;
+
 export interface LogRecord {
   timestampMs: number;
   severity: string;

package/src/exporters/wal.ts

@@ -0,0 +1,145 @@
+import type { StorageAdapter } from '../instrumentation/errors';
+
+const MAX_BATCHES = 3;
+const MAX_ITEMS_PER_BATCH = 500;
+
+// Circuit breaker: after this many consecutive delivery failures, pause for
+// CIRCUIT_OPEN_MS before attempting again.
+const CIRCUIT_BREAKER_THRESHOLD = 5;
+const CIRCUIT_OPEN_MS = 60_000;
+
+interface WalBatch<T> {
+  id: string;
+  timestamp: number;
+  data: T[];
+}
+
+// Write-ahead log backed by StorageAdapter.
+// Persists undelivered export batches so they survive force-kills.
+// Stores at most maxBatches batches; oldest are dropped when the limit is exceeded.
+export class Wal<T> {
+  constructor(
+    private readonly storage: StorageAdapter,
+    private readonly storageKey: string,
+    private readonly maxBatches = MAX_BATCHES,
+    private readonly maxItems = MAX_ITEMS_PER_BATCH
+  ) {}
+
+  // Persist a batch and return the id needed to delete it after delivery.
+  write(items: T[]): string {
+    const batches = this.readAll();
+    const id = `${Date.now()}-${Math.random().toString(36).slice(2, 7)}`;
+    batches.push({
+      id,
+      timestamp: Date.now(),
+      data: items.slice(0, this.maxItems),
+    });
+    // Keep only the most recent batches to cap storage growth.
+    const trimmed = batches.slice(-this.maxBatches);
+    this.storage.setSync(this.storageKey, JSON.stringify(trimmed));
+    return id;
+  }
+
+  // Remove a successfully delivered batch from the WAL.
+  delete(id: string): void {
+    const remaining = this.readAll().filter((b) => b.id !== id);
+    if (remaining.length === 0) {
+      this.storage.deleteSync(this.storageKey);
+    } else {
+      this.storage.setSync(this.storageKey, JSON.stringify(remaining));
+    }
+  }
+
+  // Return all pending batches (for session-start replay).
+  readAll(): WalBatch<T>[] {
+    const raw = this.storage.getSync(this.storageKey);
+    if (!raw) return [];
+    try {
+      return JSON.parse(raw) as WalBatch<T>[];
+    } catch {
+      return [];
+    }
+  }
+}
+
+// Per-endpoint circuit-breaker state.
+// Key: URL string. Stores consecutive failure count and open-until timestamp.
+interface CircuitState {
+  failures: number;
+  openUntil: number;
+}
+const circuitMap = new Map<string, CircuitState>();
+
+function getCircuit(url: string): CircuitState {
+  let state = circuitMap.get(url);
+  if (!state) {
+    state = { failures: 0, openUntil: 0 };
+    circuitMap.set(url, state);
+  }
+  return state;
+}
+
+// The fetch implementation used for all OTLP delivery.
+// Overridden by the SDK before installing fetch instrumentation so that
+// exporter calls always use the original fetch — preventing infinite recursion.
+let fetchImpl: typeof fetch | undefined;
+
+export function setFetchImpl(impl: typeof fetch): void {
+  fetchImpl = impl;
+}
+
+// Retry a fetch up to maxRetries times with exponential backoff + jitter.
+// Returns true on success, false if all retries are exhausted.
+// 4xx responses are not retried (they indicate a client-side problem).
+// After CIRCUIT_BREAKER_THRESHOLD consecutive failures the circuit opens for
+// CIRCUIT_OPEN_MS and all attempts are skipped until it closes.
+export async function fetchWithRetry(
+  url: string,
+  options: RequestInit,
+  maxRetries = 3,
+  baseDelayMs = 500
+): Promise<boolean> {
+  const circuit = getCircuit(url);
+
+  // Circuit open — bail out immediately without burning retries.
+  if (circuit.openUntil > Date.now()) {
+    return false;
+  }
+
+  // Use the override if set (pre-patch fetch), otherwise fall back to global.
+  const doFetch = fetchImpl ?? globalThis.fetch;
+
+  for (let attempt = 0; attempt < maxRetries; attempt++) {
+    try {
+      const response = await doFetch(url, options);
+      if (response.ok || (response.status >= 400 && response.status < 500)) {
+        // Reset circuit on success.
+        circuit.failures = 0;
+        circuit.openUntil = 0;
+        return true;
+      }
+      // 5xx — fall through to retry
+    } catch {
+      // Network error — fall through to retry
+    }
+    if (attempt < maxRetries - 1) {
+      // Jitter: scale by 0.5–1.0 to spread out retries under load.
+      const jitter = 0.5 + Math.random() * 0.5;
+      await new Promise<void>((r) =>
+        setTimeout(r, baseDelayMs * Math.pow(2, attempt) * jitter)
+      );
+    }
+  }
+
+  // All retries exhausted — update circuit breaker.
+  circuit.failures += 1;
+  if (circuit.failures >= CIRCUIT_BREAKER_THRESHOLD) {
+    circuit.openUntil = Date.now() + CIRCUIT_OPEN_MS;
+  }
+  return false;
+}
+
+// Reset circuit breaker state for a URL (useful in tests).
+export function resetCircuit(url: string): void {
+  circuitMap.delete(url);
+}

package/src/index.ts

@@ -1,6 +1,6 @@
 // SDK
 export { otel } from './sdk';
-export type { OtelConfig } from './sdk';
+export type { OtelConfig, NetworkAdapter } from './sdk';
 
 // Core
 export { Span, NoopSpan } from './core/span';
@@ -8,17 +8,36 @@ export type {
   SpanKind,
   SpanStatus,
   SpanEvent,
+  SpanLink,
   ReadonlySpan,
+  SpanProcessor,
 } from './core/span';
 export { Tracer } from './core/tracer';
+export type { SpanOptions } from './core/tracer';
 export { Meter, Counter, Histogram, Gauge } from './core/meter';
+export type { HistogramOptions } from './core/meter';
 export { OtelLogger } from './core/log-record';
 export type { LogSeverity } from './core/log-record';
 export type { Attributes, AttributeValue } from './core/attributes';
 export type { Resource } from './core/resource';
 
+// Samplers
+export type { Sampler } from './core/sampler';
+export {
+  AlwaysOnSampler,
+  AlwaysOffSampler,
+  TraceIdRatioSampler,
+} from './core/sampler';
+
+// Processors
+export { SimpleSpanProcessor, NoopSpanProcessor } from './core/processor';
+
+// Version
+export { SDK_VERSION } from './version';
+
 // Context
 export { spanContext } from './context/span-context';
+export type { SpanContextManagerPublic } from './context/span-context';
 
 // Exporters
 export type {
@@ -43,6 +62,11 @@ export type {
   OtlpHttpMetricExporterOptions,
   OtlpHttpLogExporterOptions,
 } from './exporters/otlp-http-exporter';
+export {
+  MultiSpanExporter,
+  MultiMetricExporter,
+  MultiLogExporter,
+} from './exporters/multi-exporter';
 
 // Instrumentation
 export { createNavigationInstrumentation } from './instrumentation/navigation';
@@ -56,6 +80,17 @@ export type {
 } from './instrumentation/network';
 export { installErrorInstrumentation } from './instrumentation/errors';
 export type { StorageAdapter } from './instrumentation/errors';
+export {
+  createFetchInstrumentation,
+  uninstallFetchInstrumentation,
+} from './instrumentation/fetch';
+export type { FetchInstrumentationOptions } from './instrumentation/fetch';
+export { installStartupInstrumentation } from './instrumentation/startup';
+export {
+  createLinkingInstrumentation,
+  recordPushNotification,
+} from './instrumentation/linking';
+export type { LinkingInstrumentation } from './instrumentation/linking';
 
 // React
 export { OtelProvider, OtelContext } from './react/OtelProvider';

package/src/instrumentation/errors.ts

@@ -92,4 +92,31 @@ export function installErrorInstrumentation(params: {
 
     originalHandler?.(error, isFatal);
   });
+
+  // Wire up unhandled Promise rejection tracking.
+  // globalThis.onunhandledrejection is available in Hermes (default RN engine since 0.70).
+  // Without this, async errors that are never .catch()-ed are silently swallowed.
+  const prevRejectionHandler = (globalThis as Record<string, unknown>)
+    .onunhandledrejection as ((event: { reason: unknown }) => void) | undefined;
+
+  (globalThis as Record<string, unknown>).onunhandledrejection = (event: {
+    reason: unknown;
+  }) => {
+    const reason = event.reason;
+    const error = reason instanceof Error ? reason : new Error(String(reason));
+
+    const span = tracer.startSpan(`unhandled_rejection.${error.name}`, {
+      kind: 'INTERNAL',
+      attributes: {
+        [ATTR_EXCEPTION_TYPE]: error.name,
+        [ATTR_EXCEPTION_MESSAGE]: error.message,
+        [ATTR_EXCEPTION_STACKTRACE]: error.stack ?? '',
+        'exception.unhandled_rejection': true,
+      },
+    });
+    span.setStatus('ERROR', error.message);
+    span.end();
+
+    prevRejectionHandler?.call(globalThis, event);
+  };
 }