react-native-otel 0.1.0

package/src/instrumentation/network.ts

@@ -0,0 +1,253 @@
+import {
+  ATTR_HTTP_REQUEST_METHOD,
+  ATTR_HTTP_RESPONSE_STATUS_CODE,
+} from '@opentelemetry/semantic-conventions';
+
+import { spanContext } from '../context/span-context';
+import { generateSpanId } from '../core/ids';
+import { Span, NoopSpan } from '../core/span';
+import { Tracer } from '../core/tracer';
+
+// Concurrent-safe: parent context is captured by value at request start
+const activeNetworkSpans = new Map<string, Span | NoopSpan>();
+
+// ─── Axios shape (subset we care about) ─────────────────────────────────────
+
+export interface AxiosRequestConfig {
+  method?: string;
+  url?: string;
+  headers?: Record<string, unknown>;
+  params?: Record<string, unknown>;
+  data?: unknown;
+  __otelId?: string;
+  [key: string]: unknown;
+}
+
+export interface AxiosResponse {
+  status: number;
+  headers?: Record<string, unknown>;
+  data?: unknown;
+  config: AxiosRequestConfig;
+  [key: string]: unknown;
+}
+
+export interface AxiosError {
+  message: string;
+  response?: AxiosResponse;
+  config?: AxiosRequestConfig;
+  [key: string]: unknown;
+}
+
+// ─── Redaction helpers ───────────────────────────────────────────────────────
+
+// Builds the set of leaf keys to redact for a given section prefix.
+// e.g. section='header', paths=['header.authorization','body.password']
+//   → Set { 'authorization' }
+function leafKeysForSection(section: string, paths: string[]): Set<string> {
+  const prefix = `${section}.`;
+  const result = new Set<string>();
+  for (const path of paths) {
+    if (path.toLowerCase().startsWith(prefix)) {
+      result.add(path.slice(prefix.length).toLowerCase());
+    }
+  }
+  return result;
+}
+
+// Shallow-redacts an object, replacing blacklisted keys with '[REDACTED]'.
+// Case-insensitive on keys. Returns the original object reference when
+// there are no sensitive keys to save an allocation.
+function redactObject(
+  obj: Record<string, unknown>,
+  sensitive: Set<string>
+): Record<string, unknown> {
+  if (sensitive.size === 0) return obj;
+  const result: Record<string, unknown> = {};
+  for (const key of Object.keys(obj)) {
+    result[key] = sensitive.has(key.toLowerCase()) ? '[REDACTED]' : obj[key];
+  }
+  return result;
+}
+
+// Tries to produce a plain object from a request/response body.
+// Handles object and JSON-string forms; skips Blobs, FormData, etc.
+function normalizeBody(data: unknown): Record<string, unknown> | undefined {
+  if (data === null || data === undefined) return undefined;
+  if (typeof data === 'object' && !Array.isArray(data)) {
+    return data as Record<string, unknown>;
+  }
+  if (typeof data === 'string') {
+    try {
+      const parsed: unknown = JSON.parse(data);
+      if (
+        parsed !== null &&
+        typeof parsed === 'object' &&
+        !Array.isArray(parsed)
+      ) {
+        return parsed as Record<string, unknown>;
+      }
+    } catch {
+      // not JSON — skip
+    }
+  }
+  return undefined;
+}
+
+// Serializes an object to a JSON string for use as a span attribute.
+// Returns undefined when serialization fails (circular refs, etc.).
+function toJsonAttr(obj: Record<string, unknown>): string | undefined {
+  try {
+    return JSON.stringify(obj);
+  } catch {
+    return undefined;
+  }
+}
+
+// ─── Factory ─────────────────────────────────────────────────────────────────
+
+export interface AxiosInstrumentationOptions {
+  // Dot-notation paths to redact. Section prefixes:
+  //   header.{key}   — request and response headers
+  //   body.{key}     — request body
+  //   param.{key}    — URL query params
+  //   response.{key} — response body
+  sensitiveKeys?: string[];
+}
+
+export function createAxiosInstrumentation(
+  tracer: Tracer,
+  options?: AxiosInstrumentationOptions
+) {
+  const paths = (options?.sensitiveKeys ?? []).map((k) => k.toLowerCase());
+
+  // Pre-compute sensitive leaf-key sets once at setup time, not per-request.
+  const sensitiveHeaders = leafKeysForSection('header', paths);
+  const sensitiveBody = leafKeysForSection('body', paths);
+  const sensitiveParams = leafKeysForSection('param', paths);
+  const sensitiveResponse = leafKeysForSection('response', paths);
+
+  return {
+    onRequest(config: AxiosRequestConfig): AxiosRequestConfig {
+      const otelId = generateSpanId();
+      const method = (config.method ?? 'GET').toUpperCase();
+      const url = config.url ?? '';
+
+      // Capture parent context NOW by value — concurrent-safe.
+      const currentSpan = spanContext.current();
+      const parent =
+        currentSpan?.traceId && currentSpan?.spanId
+          ? { traceId: currentSpan.traceId, spanId: currentSpan.spanId }
+          : null;
+
+      const span = tracer.startSpan(`http.${method} ${url}`, {
+        kind: 'CLIENT',
+        parent,
+        attributes: {
+          [ATTR_HTTP_REQUEST_METHOD]: method, // 'http.request.method'
+          'http.url': url, // stable experimental, no change
+        },
+      });
+
+      // Request headers
+      if (config.headers) {
+        const redacted = redactObject(
+          config.headers as Record<string, unknown>,
+          sensitiveHeaders
+        );
+        const serialized = toJsonAttr(redacted);
+        if (serialized) span.setAttribute('http.request.headers', serialized);
+      }
+
+      // Query params
+      if (config.params) {
+        const redacted = redactObject(config.params, sensitiveParams);
+        const serialized = toJsonAttr(redacted);
+        if (serialized) span.setAttribute('http.request.params', serialized);
+      }
+
+      // Request body
+      const reqBody = normalizeBody(config.data);
+      if (reqBody) {
+        const redacted = redactObject(reqBody, sensitiveBody);
+        const serialized = toJsonAttr(redacted);
+        if (serialized) span.setAttribute('http.request.body', serialized);
+      }
+
+      activeNetworkSpans.set(otelId, span);
+      config.__otelId = otelId;
+      return config;
+    },
+
+    onResponse(response: AxiosResponse): AxiosResponse {
+      const otelId = response.config.__otelId;
+      if (otelId) {
+        const span = activeNetworkSpans.get(otelId);
+        if (span) {
+          span.setAttribute(ATTR_HTTP_RESPONSE_STATUS_CODE, response.status);
+
+          // Response headers
+          if (response.headers) {
+            const redacted = redactObject(response.headers, sensitiveHeaders);
+            const serialized = toJsonAttr(redacted);
+            if (serialized)
+              span.setAttribute('http.response.headers', serialized);
+          }
+
+          // Response body
+          const resBody = normalizeBody(response.data);
+          if (resBody) {
+            const redacted = redactObject(resBody, sensitiveResponse);
+            const serialized = toJsonAttr(redacted);
+            if (serialized) span.setAttribute('http.response.body', serialized);
+          }
+
+          span.setStatus('OK');
+          span.end();
+          activeNetworkSpans.delete(otelId);
+        }
+      }
+      return response;
+    },
+
+    onError(error: AxiosError): Promise<never> {
+      const otelId = error.config?.__otelId;
+      if (otelId) {
+        const span = activeNetworkSpans.get(otelId);
+        if (span) {
+          span.setAttribute(
+            ATTR_HTTP_RESPONSE_STATUS_CODE,
+            error.response?.status ?? 0
+          );
+
+          // Error response headers + body when available
+          if (error.response?.headers) {
+            const redacted = redactObject(
+              error.response.headers,
+              sensitiveHeaders
+            );
+            const serialized = toJsonAttr(redacted);
+            if (serialized)
+              span.setAttribute('http.response.headers', serialized);
+          }
+
+          const errBody = normalizeBody(error.response?.data);
+          if (errBody) {
+            const redacted = redactObject(errBody, sensitiveResponse);
+            const serialized = toJsonAttr(redacted);
+            if (serialized) span.setAttribute('http.response.body', serialized);
+          }
+
+          span.recordException(error as unknown as Error);
+          span.setStatus('ERROR', error.message);
+          span.end();
+          activeNetworkSpans.delete(otelId);
+        }
+      }
+      return Promise.reject(error);
+    },
+  };
+}
+
+export type AxiosInstrumentation = ReturnType<
+  typeof createAxiosInstrumentation
+>;

package/src/react/OtelProvider.tsx

@@ -0,0 +1,98 @@
+import React, {
+  createContext,
+  Component,
+  type ErrorInfo,
+  type ReactNode,
+} from 'react';
+
+import { OtelLogger } from '../core/log-record';
+import { Meter } from '../core/meter';
+import { Tracer } from '../core/tracer';
+import { otel } from '../sdk';
+
+export interface OtelContextValue {
+  tracer: Tracer;
+  meter: Meter;
+  logger: OtelLogger;
+  recordEvent: (name: string, attributes?: Record<string, unknown>) => void;
+  setUser: (user: { id?: string; email?: string }) => void;
+}
+
+export const OtelContext = createContext<OtelContextValue | undefined>(
+  undefined
+);
+
+interface ErrorBoundaryProps {
+  children: ReactNode;
+  tracer: Tracer;
+}
+
+interface ErrorBoundaryState {
+  hasError: boolean;
+}
+
+class OtelErrorBoundary extends Component<
+  ErrorBoundaryProps,
+  ErrorBoundaryState
+> {
+  constructor(props: ErrorBoundaryProps) {
+    super(props);
+    this.state = { hasError: false };
+  }
+
+  static getDerivedStateFromError(): ErrorBoundaryState {
+    return { hasError: true };
+  }
+
+  componentDidCatch(error: Error, _info: ErrorInfo): void {
+    this.props.tracer.recordException(error, {
+      'error.source': 'react_error_boundary',
+    });
+  }
+
+  render(): ReactNode {
+    if (this.state.hasError) {
+      return null;
+    }
+    return this.props.children;
+  }
+}
+
+export interface OtelProviderProps {
+  children: ReactNode;
+  withErrorBoundary?: boolean;
+}
+
+export function OtelProvider({
+  children,
+  withErrorBoundary = false,
+}: OtelProviderProps): React.ReactElement {
+  const tracer = otel.getTracer();
+  const meter = otel.getMeter();
+  const logger = otel.getLogger();
+
+  const value: OtelContextValue = {
+    tracer,
+    meter,
+    logger,
+    recordEvent: (name, attributes) =>
+      tracer.recordEvent(
+        name,
+        attributes as Record<
+          string,
+          string | number | boolean | string[] | number[] | boolean[]
+        >
+      ),
+    setUser: (user) => otel.setUser(user),
+  };
+
+  const content = (
+    <OtelContext.Provider value={value}>{children}</OtelContext.Provider>
+  );
+
+  if (withErrorBoundary) {
+    return <OtelErrorBoundary tracer={tracer}>{content}</OtelErrorBoundary>;
+  }
+
+  return content;
+}

package/src/react/useOtel.ts

@@ -0,0 +1,14 @@
+import { useContext } from 'react';
+
+import type { OtelContextValue } from './OtelProvider';
+import { OtelContext } from './OtelProvider';
+
+export function useOtel(): OtelContextValue {
+  const ctx = useContext(OtelContext);
+  if (!ctx) {
+    throw new Error(
+      '[react-native-otel] useOtel must be used inside OtelProvider.'
+    );
+  }
+  return ctx;
+}

package/src/sdk.ts

@@ -0,0 +1,179 @@
+import type { Attributes } from './core/attributes';
+import type { Resource } from './core/resource';
+import type {
+  SpanExporter,
+  MetricExporter,
+  LogExporter,
+} from './exporters/types';
+import type { StorageAdapter } from './instrumentation/errors';
+import { spanContext } from './context/span-context';
+import { setMaxStringLength } from './core/attributes';
+import { OtelLogger } from './core/log-record';
+import { Meter } from './core/meter';
+import { buildResource } from './core/resource';
+import { Tracer } from './core/tracer';
+import { installErrorInstrumentation } from './instrumentation/errors';
+import { installLifecycleInstrumentation } from './instrumentation/lifecycle';
+
+export interface OtelConfig {
+  serviceName: string;
+  serviceVersion?: string;
+  osName?: string;
+  osVersion?: string;
+  deviceBrand?: string;
+  deviceModel?: string;
+  deviceType?: string | number;
+  appBuild?: string;
+  environment?: string;
+  exporter?: SpanExporter;
+  metricExporter?: MetricExporter;
+  logExporter?: LogExporter;
+  sampleRate?: number;
+  debug?: boolean;
+  storage?: StorageAdapter;
+  // Truncate string attribute values longer than this. Default: 1024.
+  maxAttributeStringLength?: number;
+  // Dot-notation paths to redact from network captures.
+  // Sections: header, body, param, response
+  // Examples: ['header.authorization', 'body.password', 'response.token']
+  sensitiveKeys?: string[];
+}
+
+class OtelSDK {
+  private userAttributes_: Attributes = {};
+  private tracer_: Tracer | undefined;
+  private meter_: Meter | undefined;
+  private logger_: OtelLogger | undefined;
+  private resource_: Readonly<Resource> | undefined;
+  private exporter_: SpanExporter | undefined;
+  private metricExporter_: MetricExporter | undefined;
+  private logExporter_: LogExporter | undefined;
+  private sensitiveKeys_: string[] = [];
+  private initialized = false;
+
+  init(config: OtelConfig): void {
+    if (this.initialized) return;
+    this.initialized = true;
+
+    if (config.maxAttributeStringLength !== undefined) {
+      setMaxStringLength(config.maxAttributeStringLength);
+    }
+
+    this.sensitiveKeys_ = config.sensitiveKeys ?? [];
+    this.exporter_ = config.exporter;
+    this.metricExporter_ = config.metricExporter;
+    this.logExporter_ = config.logExporter;
+
+    this.resource_ = buildResource({
+      serviceName: config.serviceName,
+      serviceVersion: config.serviceVersion ?? '0.0.0',
+      osName: config.osName ?? '',
+      osVersion: config.osVersion ?? '',
+      deviceBrand: config.deviceBrand ?? '',
+      deviceModel: config.deviceModel ?? '',
+      deviceType: config.deviceType ?? '',
+      appBuild: config.appBuild ?? '',
+      environment: config.environment ?? 'production',
+    });
+
+    // If any exporter supports resource injection (e.g. OtlpHttp*Exporter),
+    // hand it the resource so it can include it in OTLP payloads.
+    const injectResource = (exp: unknown) => {
+      if (exp && typeof exp === 'object' && 'setResource' in exp) {
+        (exp as { setResource(r: Readonly<Resource>): void }).setResource(
+          this.resource_ as Readonly<Resource>
+        );
+      }
+    };
+    injectResource(config.exporter);
+    injectResource(config.metricExporter);
+    injectResource(config.logExporter);
+
+    this.tracer_ = new Tracer({
+      exporter: config.exporter,
+      sampleRate: config.sampleRate,
+      getUserAttributes: () => ({ ...this.userAttributes_ }),
+    });
+
+    this.meter_ = new Meter(config.metricExporter);
+    this.logger_ = new OtelLogger(config.logExporter);
+
+    // Check for pending crash span and install global error handler
+    installErrorInstrumentation({
+      tracer: this.tracer_,
+      storage: config.storage,
+      exporter: config.exporter,
+    });
+
+    // Install lifecycle instrumentation
+    installLifecycleInstrumentation(this.meter_);
+  }
+
+  // Records a named event on the current screen span.
+  // Safe to call before init() — silently no-ops if SDK is not yet initialized.
+  recordEvent(name: string, properties?: Record<string, unknown>): void {
+    this.tracer_?.recordEvent(name, properties as unknown as Attributes);
+  }
+
+  setUser(user: { id?: string; email?: string }): void {
+    this.userAttributes_ = {
+      ...(user.id ? { 'user.id': user.id } : {}),
+      ...(user.email ? { 'user.email': user.email } : {}),
+    };
+  }
+
+  getTracer(): Tracer {
+    if (!this.tracer_) {
+      throw new Error(
+        '[react-native-otel] SDK not initialized. Call otel.init() first.'
+      );
+    }
+    return this.tracer_;
+  }
+
+  getMeter(): Meter {
+    if (!this.meter_) {
+      throw new Error(
+        '[react-native-otel] SDK not initialized. Call otel.init() first.'
+      );
+    }
+    return this.meter_;
+  }
+
+  getSensitiveKeys(): string[] {
+    return this.sensitiveKeys_;
+  }
+
+  getLogger(): OtelLogger {
+    if (!this.logger_) {
+      throw new Error(
+        '[react-native-otel] SDK not initialized. Call otel.init() first.'
+      );
+    }
+    return this.logger_;
+  }
+
+  async shutdown(): Promise<void> {
+    // End active screen span
+    const current = spanContext.current();
+    if (current) {
+      current.end();
+      spanContext.setCurrent(undefined);
+    }
+
+    // Flush buffered metrics
+    this.meter_?.flush();
+
+    // Flush + tear down exporter timers (e.g. OtlpHttp*Exporter)
+    const destroyExporter = (exp: unknown) => {
+      if (exp && typeof exp === 'object' && 'destroy' in exp) {
+        (exp as { destroy(): void }).destroy();
+      }
+    };
+    destroyExporter(this.exporter_);
+    destroyExporter(this.metricExporter_);
+    destroyExporter(this.logExporter_);
+  }
+}
+
+export const otel = new OtelSDK();