react-native-otel 0.1.0 → 0.1.4

package/lib/typescript/src/instrumentation/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../../src/instrumentation/errors.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AACxC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAIvD,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1C,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IACpC,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAqBD,wBAAgB,2BAA2B,CAAC,MAAM,EAAE;IAClD,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,QAAQ,CAAC,EAAE;QAAE,MAAM,CAAC,KAAK,EAAE,YAAY,EAAE,GAAG,IAAI,CAAA;KAAE,CAAC;CACpD,GAAG,IAAI,CAqDP"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../../src/instrumentation/errors.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AACxC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAIvD,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1C,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IACpC,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAqBD,wBAAgB,2BAA2B,CAAC,MAAM,EAAE;IAClD,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,QAAQ,CAAC,EAAE;QAAE,MAAM,CAAC,KAAK,EAAE,YAAY,EAAE,GAAG,IAAI,CAAA;KAAE,CAAC;CACpD,GAAG,IAAI,CAgFP"}

package/lib/typescript/src/instrumentation/network.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"network.d.ts","sourceRoot":"","sources":["../../../../src/instrumentation/network.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAOxC,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,kBAAkB,CAAC;IAC3B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,MAAM,CAAC,EAAE,kBAAkB,CAAC;IAC5B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAqED,MAAM,WAAW,2BAA2B;IAM1C,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,2BAA2B;sBAWjB,kBAAkB,GAAG,kBAAkB;yBAmDpC,aAAa,GAAG,aAAa;mBA+BnC,UAAU,GAAG,OAAO,CAAC,KAAK,CAAC;EAqC7C;AAED,MAAM,MAAM,oBAAoB,GAAG,UAAU,CAC3C,OAAO,0BAA0B,CAClC,CAAC"}
+{"version":3,"file":"network.d.ts","sourceRoot":"","sources":["../../../../src/instrumentation/network.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAOxC,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,kBAAkB,CAAC;IAC3B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,MAAM,CAAC,EAAE,kBAAkB,CAAC;IAC5B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAqED,MAAM,WAAW,2BAA2B;IAM1C,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,2BAA2B;sBAWjB,kBAAkB,GAAG,kBAAkB;yBA6DpC,aAAa,GAAG,aAAa;mBA+BnC,UAAU,GAAG,OAAO,CAAC,KAAK,CAAC;EAqC7C;AAED,MAAM,MAAM,oBAAoB,GAAG,UAAU,CAC3C,OAAO,0BAA0B,CAClC,CAAC"}

package/lib/typescript/src/sdk.d.ts

@@ -43,6 +43,7 @@ declare class OtelSDK {
     getMeter(): Meter;
     getSensitiveKeys(): string[];
     getLogger(): OtelLogger;
+    flush(): void;
     shutdown(): Promise<void>;
 }
 export declare const otel: OtelSDK;

package/lib/typescript/src/sdk.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sdk.d.ts","sourceRoot":"","sources":["../../../src/sdk.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,YAAY,EACZ,cAAc,EACd,WAAW,EACZ,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAG/D,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAErC,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAIvC,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,cAAc,CAAC;IAEzB,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAIlC,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED,cAAM,OAAO;IACX,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,OAAO,CAAqB;IACpC,OAAO,CAAC,MAAM,CAAoB;IAClC,OAAO,CAAC,OAAO,CAAyB;IACxC,OAAO,CAAC,SAAS,CAAiC;IAClD,OAAO,CAAC,SAAS,CAA2B;IAC5C,OAAO,CAAC,eAAe,CAA6B;IACpD,OAAO,CAAC,YAAY,CAA0B;IAC9C,OAAO,CAAC,cAAc,CAAgB;IACtC,OAAO,CAAC,WAAW,CAAS;IAE5B,IAAI,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI;IA4D9B,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAIrE,OAAO,CAAC,IAAI,EAAE;QAAE,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAOpD,SAAS,IAAI,MAAM;IASnB,QAAQ,IAAI,KAAK;IASjB,gBAAgB,IAAI,MAAM,EAAE;IAI5B,SAAS,IAAI,UAAU;IASjB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAqBhC;AAED,eAAO,MAAM,IAAI,SAAgB,CAAC"}
+{"version":3,"file":"sdk.d.ts","sourceRoot":"","sources":["../../../src/sdk.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,YAAY,EACZ,cAAc,EACd,WAAW,EACZ,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAG/D,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAErC,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAIvC,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,cAAc,CAAC;IAEzB,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAIlC,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED,cAAM,OAAO;IACX,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,OAAO,CAAqB;IACpC,OAAO,CAAC,MAAM,CAAoB;IAClC,OAAO,CAAC,OAAO,CAAyB;IACxC,OAAO,CAAC,SAAS,CAAiC;IAClD,OAAO,CAAC,SAAS,CAA2B;IAC5C,OAAO,CAAC,eAAe,CAA6B;IACpD,OAAO,CAAC,YAAY,CAA0B;IAC9C,OAAO,CAAC,cAAc,CAAgB;IACtC,OAAO,CAAC,WAAW,CAAS;IAE5B,IAAI,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI;IA2E9B,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAIrE,OAAO,CAAC,IAAI,EAAE;QAAE,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAOpD,SAAS,IAAI,MAAM;IASnB,QAAQ,IAAI,KAAK;IASjB,gBAAgB,IAAI,MAAM,EAAE;IAI5B,SAAS,IAAI,UAAU;IAYvB,KAAK,IAAI,IAAI;IAWP,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAqBhC;AAED,eAAO,MAAM,IAAI,SAAgB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-otel",
-  "version": "0.1.0",
+  "version": "0.1.4",
   "description": "Lightweight OpenTelemetry SDK for React Native",
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",
@@ -36,7 +36,9 @@
     "clean": "del-cli lib",
     "prepare": "bob build",
     "typecheck": "tsc",
-    "lint": "eslint \"**/*.{js,ts,tsx}\""
+    "lint": "eslint \"**/*.{js,ts,tsx}\"",
+    "test": "jest",
+    "test:watch": "jest --watch"
   },
   "keywords": [
     "react-native",
@@ -66,15 +68,18 @@
     "@eslint/js": "^9.35.0",
     "@react-native/babel-preset": "0.83.0",
     "@react-native/eslint-config": "0.83.0",
+    "@types/jest": "^29",
     "@types/react": "^19.1.12",
     "del-cli": "^6.0.0",
     "eslint": "^9.35.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.4",
+    "jest": "^29",
     "prettier": "^2.8.8",
     "react": "19.2.0",
     "react-native": "0.83.2",
     "react-native-builder-bob": "^0.40.13",
+    "ts-jest": "^29",
     "turbo": "^2.5.6",
     "typescript": "^5.9.2"
   },

package/src/context/span-context.ts

@@ -1,17 +1,70 @@
-import { Span, NoopSpan } from '../core/span';
+import type { Span, NoopSpan } from '../core/span';
 
-// Module-level singleton. Tracks only the current active screen span.
-// Network spans do NOT touch this context (handled via activeNetworkSpans map).
-class SpanContextManager {
-  private current_: Span | NoopSpan | undefined;
+// Public interface — what external consumers see when they import spanContext.
+// Hides push/pop to prevent misuse; use tracer.startActiveSpan() or
+// tracer.withSpan() for safe nested context management.
+export interface SpanContextManagerPublic {
+  setCurrent(span: Span | NoopSpan | undefined): void;
+  current(): Span | NoopSpan | undefined;
+}
+
+// Each manual push is tracked by a unique token so that pop() can find the
+// exact entry to remove regardless of concurrent async interleaving.
+interface StackEntry {
+  span: Span | NoopSpan;
+  token: symbol;
+}
 
+class SpanContextManager implements SpanContextManagerPublic {
+  // Screen-level span set by navigation instrumentation.
+  private screenSpan_: Span | NoopSpan | undefined;
+  // Manual spans pushed by startActiveSpan / withSpan.
+  // Separate from screenSpan_ because they have different lifecycles.
+  private manualStack_: StackEntry[] = [];
+
+  // ─── Public API (backward-compatible) ──────────────────────────────────────
+
+  // Set the screen-level span. Called by navigation on route change.
+  // Clears the manual stack so stale sub-operation context from the previous
+  // screen does not leak into the new one.
   setCurrent(span: Span | NoopSpan | undefined): void {
-    this.current_ = span;
+    this.screenSpan_ = span;
+    this.manualStack_ = [];
   }
 
+  // Return the most specific active span. Manual stack takes precedence.
   current(): Span | NoopSpan | undefined {
-    return this.current_;
+    const top = this.manualStack_[this.manualStack_.length - 1];
+    return top?.span ?? this.screenSpan_;
+  }
+
+  // ─── Internal API (used by Tracer only, not re-exported from index.ts) ─────
+
+  // Push span as the active context. Returns a token required by pop().
+  /** @internal */
+  push(span: Span | NoopSpan): symbol {
+    const token = Symbol();
+    this.manualStack_.push({ span, token });
+    return token;
+  }
+
+  // Remove the entry matching token, regardless of position in the stack.
+  // Identity-based (not positional) so concurrent async operations cannot
+  // accidentally pop each other's entries.
+  /** @internal */
+  pop(token: symbol): void {
+    const idx = this.manualStack_.findIndex((e) => e.token === token);
+    if (idx !== -1) {
+      this.manualStack_.splice(idx, 1);
+    }
   }
 }
 
-export const spanContext = new SpanContextManager();
+const manager = new SpanContextManager();
+
+// External consumers get the narrowed type — push/pop are hidden.
+export const spanContext: SpanContextManagerPublic = manager;
+
+// Internal alias with the concrete type so tracer.ts can call push/pop.
+// Not re-exported from index.ts.
+export const spanContextInternal: SpanContextManager = manager;

package/src/core/ids.ts

@@ -1,15 +1,29 @@
-function randomHex(length: number): string {
-  let result = '';
-  for (let i = 0; i < length; i++) {
-    result += Math.floor(Math.random() * 16).toString(16);
+function randomBytesHex(byteCount: number): string {
+  try {
+    const bytes = new Uint8Array(byteCount);
+    crypto.getRandomValues(bytes);
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+  } catch {
+    // Fallback if crypto.getRandomValues is unavailable
+    if (__DEV__) {
+      console.warn(
+        '[react-native-otel] crypto.getRandomValues unavailable; falling back to Math.random for ID generation. IDs may collide at scale.'
+      );
+    }
+    let result = '';
+    for (let i = 0; i < byteCount * 2; i++) {
+      result += Math.floor(Math.random() * 16).toString(16);
+    }
+    return result;
   }
-  return result;
 }
 
+// 128-bit trace ID per OTel spec (32 hex chars)
 export function generateTraceId(): string {
-  return randomHex(32);
+  return randomBytesHex(16);
 }
 
+// 64-bit span ID per OTel spec (16 hex chars)
 export function generateSpanId(): string {
-  return randomHex(16);
+  return randomBytesHex(8);
 }

package/src/core/meter.ts

@@ -1,8 +1,17 @@
 import type { Attributes } from './attributes';
-import type { MetricExporter, MetricRecord } from '../exporters/types';
+import type {
+  MetricExporter,
+  MetricRecord,
+  HistogramRecord,
+} from '../exporters/types';
 import { sanitizeAttributes } from './attributes';
 import { now } from './clock';
 
+// Default bucket boundaries in milliseconds — covers typical mobile latencies.
+const DEFAULT_HISTOGRAM_BOUNDARIES = [
+  0, 5, 10, 25, 50, 75, 100, 250, 500, 1000,
+];
+
 export class Counter {
   constructor(
     private name: string,
@@ -20,20 +29,92 @@ export class Counter {
   }
 }
 
+interface HistogramBucket {
+  count: number;
+  sum: number;
+  bucketCounts: number[];
+  startTimeMs: number;
+  lastTimeMs: number;
+  attributes: Attributes;
+}
+
+export interface HistogramOptions {
+  // Explicit upper bounds for buckets, in ascending order. A +Inf bucket is
+  // always appended implicitly. Defaults to DEFAULT_HISTOGRAM_BOUNDARIES.
+  boundaries?: number[];
+}
+
 export class Histogram {
+  private readonly boundaries: number[];
+  // Keyed by serialized attributes so concurrent recordings with different
+  // attribute sets are tracked independently.
+  private buckets = new Map<string, HistogramBucket>();
+
   constructor(
     private name: string,
-    private pushToBuffer: (record: MetricRecord) => void
-  ) {}
+    private pushToBuffer: (record: MetricRecord) => void,
+    options?: HistogramOptions
+  ) {
+    this.boundaries = options?.boundaries ?? DEFAULT_HISTOGRAM_BOUNDARIES;
+  }
 
   record(value: number, attrs?: Attributes): void {
-    this.pushToBuffer({
-      type: 'histogram',
-      name: this.name,
-      value,
-      timestampMs: now(),
-      attributes: attrs ? sanitizeAttributes(attrs) : {},
-    });
+    const sanitized = attrs ? sanitizeAttributes(attrs) : {};
+    const key = JSON.stringify(sanitized);
+
+    let bucket = this.buckets.get(key);
+    if (!bucket) {
+      bucket = {
+        count: 0,
+        sum: 0,
+        bucketCounts: new Array<number>(this.boundaries.length + 1).fill(0),
+        startTimeMs: now(),
+        lastTimeMs: now(),
+        attributes: sanitized,
+      };
+      this.buckets.set(key, bucket);
+    }
+
+    bucket.count += 1;
+    bucket.sum += value;
+    bucket.lastTimeMs = now();
+
+    // Place value into its bucket (first boundary that the value is <= to).
+    let placed = false;
+    for (let i = 0; i < this.boundaries.length; i++) {
+      if (value <= this.boundaries[i]!) {
+        bucket.bucketCounts[i]! += 1;
+        placed = true;
+        break;
+      }
+    }
+    // +Inf bucket
+    if (!placed) {
+      bucket.bucketCounts[this.boundaries.length]! += 1;
+    }
+  }
+
+  // Called by Meter.flush() — drains accumulated buckets into the export buffer.
+  flush(): void {
+    for (const bucket of this.buckets.values()) {
+      const record: HistogramRecord = {
+        type: 'histogram',
+        name: this.name,
+        count: bucket.count,
+        sum: bucket.sum,
+        bucketBoundaries: this.boundaries,
+        bucketCounts: bucket.bucketCounts,
+        timestampMs: bucket.lastTimeMs,
+        attributes: bucket.attributes,
+      };
+      this.pushToBuffer(record);
+    }
+    this.buckets.clear();
+  }
+
+  // Returns whether there is any accumulated data.
+  hasData(): boolean {
+    return this.buckets.size > 0;
   }
 }
 
@@ -57,6 +138,7 @@ export class Gauge {
 export class Meter {
   private buffer: MetricRecord[] = [];
   private exporter: MetricExporter | undefined;
+  private histograms: Histogram[] = [];
 
   constructor(exporter?: MetricExporter) {
     this.exporter = exporter;
@@ -66,8 +148,10 @@ export class Meter {
     return new Counter(name, (r) => this.buffer.push(r));
   }
 
-  createHistogram(name: string): Histogram {
-    return new Histogram(name, (r) => this.buffer.push(r));
+  createHistogram(name: string, options?: HistogramOptions): Histogram {
+    const histogram = new Histogram(name, (r) => this.buffer.push(r), options);
+    this.histograms.push(histogram);
+    return histogram;
   }
 
   createGauge(name: string): Gauge {
@@ -75,6 +159,13 @@ export class Meter {
   }
 
   flush(): void {
+    // Drain all histogram buckets into the buffer first.
+    for (const histogram of this.histograms) {
+      if (histogram.hasData()) {
+        histogram.flush();
+      }
+    }
+
     if (this.buffer.length === 0) return;
     const toExport = this.buffer.splice(0, this.buffer.length);
     this.exporter?.export(toExport);

package/src/core/tracer.ts

@@ -7,7 +7,15 @@ import {
 import type { Attributes } from './attributes';
 import type { SpanContext, SpanExporter, SpanKind } from './span';
 import { Span, NoopSpan } from './span';
-import { spanContext } from '../context/span-context';
+import { spanContext, spanContextInternal } from '../context/span-context';
+
+interface SpanOptions {
+  kind?: SpanKind;
+  attributes?: Attributes;
+  // Inherit traceId from this parent. Omit to use the current active span.
+  // Pass null to force a new root trace.
+  parent?: SpanContext | null;
+}
 
 export class Tracer {
   private exporter: SpanExporter | undefined;
@@ -24,22 +32,14 @@ export class Tracer {
     this.getUserAttributes = params.getUserAttributes;
   }
 
-  startSpan(
-    name: string,
-    options?: {
-      kind?: SpanKind;
-      attributes?: Attributes;
-      // Pass the full parent context to inherit traceId.
-      // If omitted, the current screen span is used automatically.
-      // Pass null explicitly to force a new root trace.
-      parent?: SpanContext | null;
-    }
-  ): Span | NoopSpan {
+  // Create a span without making it the active context.
+  // Use startActiveSpan() when you want sub-operations to auto-parent.
+  startSpan(name: string, options?: SpanOptions): Span | NoopSpan {
     if (this.sampleRate < 1.0 && Math.random() > this.sampleRate) {
       return new NoopSpan();
     }
 
-    // Resolve parent: explicit > current screen span > none (new trace)
+    // Resolve parent: explicit > current active span > none (new root trace)
     const parent: SpanContext | undefined =
       options?.parent !== undefined
         ? options.parent ?? undefined
@@ -55,6 +55,92 @@ export class Tracer {
     });
   }
 
+  // Create a span, make it the active context for the duration of fn, then
+  // automatically end it. Sub-operations started inside fn via startSpan() will
+  // automatically parent to this span.
+  //
+  // For concurrent async work (multiple in-flight awaits), pass parent
+  // explicitly to startSpan() instead — the shared context stack is not safe
+  // for interleaved async operations.
+  startActiveSpan<T>(name: string, fn: (span: Span | NoopSpan) => T): T;
+  startActiveSpan<T>(
+    name: string,
+    options: SpanOptions,
+    fn: (span: Span | NoopSpan) => T
+  ): T;
+  startActiveSpan<T>(
+    name: string,
+    optionsOrFn: SpanOptions | ((span: Span | NoopSpan) => T),
+    fn?: (span: Span | NoopSpan) => T
+  ): T {
+    const options = typeof optionsOrFn === 'function' ? undefined : optionsOrFn;
+    const callback = typeof optionsOrFn === 'function' ? optionsOrFn : fn!;
+
+    const span = this.startSpan(name, options);
+    const token = spanContextInternal.push(span);
+
+    const cleanup = (isError: boolean, err?: unknown) => {
+      if (isError && err instanceof Error) {
+        span.setStatus('ERROR', err.message);
+      }
+      span.end();
+      spanContextInternal.pop(token);
+    };
+
+    try {
+      const result = callback(span);
+      if (result instanceof Promise) {
+        // Token-based pop fires after the promise settles, preserving identity
+        // even if other startActiveSpan calls interleave on the event loop.
+        return result.then(
+          (v) => {
+            cleanup(false);
+            return v;
+          },
+          (e: unknown) => {
+            cleanup(true, e);
+            throw e;
+          }
+        ) as T;
+      }
+      cleanup(false);
+      return result;
+    } catch (e) {
+      cleanup(true, e);
+      throw e;
+    }
+  }
+
+  // Make an existing span the active context for the duration of fn.
+  // Does NOT end the span — the caller owns its lifetime.
+  // Safe for synchronous work. For concurrent async work, see startActiveSpan.
+  withSpan<T>(span: Span | NoopSpan, fn: (span: Span | NoopSpan) => T): T {
+    const token = spanContextInternal.push(span);
+
+    const cleanup = () => spanContextInternal.pop(token);
+
+    try {
+      const result = fn(span);
+      if (result instanceof Promise) {
+        return result.then(
+          (v) => {
+            cleanup();
+            return v;
+          },
+          (e: unknown) => {
+            cleanup();
+            throw e;
+          }
+        ) as T;
+      }
+      cleanup();
+      return result;
+    } catch (e) {
+      cleanup();
+      throw e;
+    }
+  }
+
   recordEvent(name: string, attributes?: Attributes): void {
     spanContext.current()?.addEvent(name, attributes);
   }

package/src/exporters/console-exporter.ts

@@ -4,6 +4,7 @@ import type {
   LogExporter,
   ReadonlySpan,
   MetricRecord,
+  HistogramRecord,
   LogRecord,
 } from './types';
 
@@ -60,10 +61,23 @@ export class ConsoleMetricExporter implements MetricExporter {
     if (!shouldLog(this.debug)) return;
 
     for (const metric of metrics) {
-      console.log(
-        `[OTEL METRIC] ${metric.name} ${metric.type} value=${metric.value}`,
-        Object.keys(metric.attributes).length > 0 ? metric.attributes : ''
-      );
+      if (metric.type === 'histogram') {
+        const h = metric as HistogramRecord;
+        const avg = h.count > 0 ? (h.sum / h.count).toFixed(2) : '0';
+        const bucketStr = h.bucketBoundaries
+          .map((b, i) => `≤${b}:${h.bucketCounts[i]}`)
+          .concat([`+Inf:${h.bucketCounts[h.bucketBoundaries.length]}`])
+          .join(' ');
+        console.log(
+          `[OTEL METRIC] ${h.name} histogram count=${h.count} sum=${h.sum} avg=${avg} [${bucketStr}]`,
+          Object.keys(h.attributes).length > 0 ? h.attributes : ''
+        );
+      } else {
+        console.log(
+          `[OTEL METRIC] ${metric.name} ${metric.type} value=${metric.value}`,
+          Object.keys(metric.attributes).length > 0 ? metric.attributes : ''
+        );
+      }
     }
   }
 }