@timber-js/app 0.2.0-alpha.21 → 0.2.0-alpha.211

package/src/server/stream-utils.ts

@@ -0,0 +1,343 @@
+/**
+ * Stream utilities for the RSC rendering pipeline.
+ *
+ * teeWithErrorPropagation — wraps native ReadableStream.tee() with:
+ * 1. Cross-branch error propagation (error on one branch cancels the other)
+ * 2. Buffer divergence monitoring (warns + cancels when threshold exceeded)
+ *
+ * This prevents two classes of bugs:
+ * - Silent stalls when one tee branch errors and the other hangs indefinitely
+ * - Unbounded memory growth when one consumer (SSR) is much slower than the other
+ *
+ * Design doc: 02-rendering-pipeline.md §"RSC → SSR → Client Hydration"
+ */
+
+import { getLogger } from './logger.ts';
+
+/** Default maximum buffer divergence before cancellation (5MB). */
+const DEFAULT_MAX_BUFFER_BYTES = 5 * 1024 * 1024;
+
+export interface TeeOptions {
+  /**
+   * Maximum byte divergence between the two branches before both are
+   * cancelled. When one branch has consumed this many more bytes than
+   * the other, the tee's internal buffer is at least this large.
+   *
+   * Default: 5MB.
+   */
+  maxBufferBytes?: number;
+}
+
+/**
+ * Tee a ReadableStream with error propagation and buffer monitoring.
+ *
+ * Delegates to the native `stream.tee()` for the actual forking, then wraps
+ * each branch in a ReadableStream that:
+ * - Tracks bytes consumed per branch
+ * - Cancels both branches if byte divergence exceeds `maxBufferBytes`
+ * - Cancels the other branch if either branch is cancelled or errors
+ *
+ * The returned streams are drop-in replacements for the native tee branches.
+ */
+export function teeWithErrorPropagation(
+  stream: ReadableStream<Uint8Array>,
+  options?: TeeOptions
+): [ReadableStream<Uint8Array>, ReadableStream<Uint8Array>] {
+  const maxBuffer = options?.maxBufferBytes ?? DEFAULT_MAX_BUFFER_BYTES;
+  const [rawBranch1, rawBranch2] = stream.tee();
+
+  // Shared state for cross-branch coordination
+  let consumed1 = 0;
+  let consumed2 = 0;
+  let cancelled = false;
+
+  // Readers and controllers are assigned when wrapBranch creates the wrapped
+  // streams. We store them so cancelBoth can cancel raw tee branches AND
+  // error the wrapped stream controllers for cross-branch propagation.
+  let rawReader1: ReadableStreamDefaultReader<Uint8Array> | undefined;
+  let rawReader2: ReadableStreamDefaultReader<Uint8Array> | undefined;
+  let controller1: ReadableStreamDefaultController<Uint8Array> | undefined;
+  let controller2: ReadableStreamDefaultController<Uint8Array> | undefined;
+
+  /**
+   * Cancel both tee branches. `initiator` is the branch index (0 or 1)
+   * that triggered the cancellation — its controller is already being
+   * closed/errored by the pull/cancel that triggered this, so we skip it.
+   * Pass -1 to cancel+error both (e.g., from the buffer divergence guard).
+   *
+   * Both raw readers are always canceled regardless of initiator, because
+   * the tee source stream is only released when both branches are canceled.
+   * ReadableStreamDefaultReader.cancel() is idempotent, so double-cancel
+   * is safe.
+   */
+  function cancelBoth(reason: unknown, initiator: number = -1): void {
+    if (cancelled) return;
+    cancelled = true;
+    // Cancel both raw readers — tee source requires both branches canceled.
+    rawReader1?.cancel(reason).catch(() => {});
+    rawReader2?.cancel(reason).catch(() => {});
+    // Error wrapped controllers so consumers see the failure.
+    // Skip the initiator's controller — it's already being closed/errored.
+    if (initiator !== 0) {
+      try {
+        controller1?.error(reason);
+      } catch {
+        /* already closed/errored */
+      }
+    }
+    if (initiator !== 1) {
+      try {
+        controller2?.error(reason);
+      } catch {
+        /* already closed/errored */
+      }
+    }
+  }
+
+  function wrapBranch(
+    branchIndex: number,
+    rawBranch: ReadableStream<Uint8Array>,
+    assignReader: (r: ReadableStreamDefaultReader<Uint8Array>) => void,
+    assignController: (c: ReadableStreamDefaultController<Uint8Array>) => void,
+    addConsumed: (n: number) => void,
+    getSelfConsumed: () => number,
+    getOtherConsumed: () => number
+  ): ReadableStream<Uint8Array> {
+    const reader = rawBranch.getReader();
+    assignReader(reader);
+
+    return new ReadableStream<Uint8Array>({
+      start(controller) {
+        assignController(controller);
+      },
+
+      async pull(controller) {
+        if (cancelled) {
+          return;
+        }
+
+        try {
+          const { done, value } = await reader.read();
+
+          // Re-check after await — cancelBoth may have fired while we
+          // were waiting on the raw reader.
+          if (cancelled) return;
+
+          if (done) {
+            try {
+              controller.close();
+            } catch {
+              /* controller already errored by cancelBoth */
+            }
+            return;
+          }
+
+          addConsumed(value.byteLength);
+
+          // Check buffer divergence: the difference in consumed bytes
+          // approximates the tee's internal buffer size.
+          const divergence = getSelfConsumed() - getOtherConsumed();
+          if (divergence > maxBuffer) {
+            const error = new Error(
+              `RSC stream tee buffer exceeded ${formatBytes(maxBuffer)} ` +
+                `(divergence: ${formatBytes(divergence)}). ` +
+                `This usually means SSR is much slower than the inline stream consumer. ` +
+                `Consider reducing RSC payload size or increasing the tee buffer limit.`
+            );
+            console.warn(`[timber] ${error.message}`);
+            cancelBoth(error);
+            return;
+          }
+
+          controller.enqueue(value);
+        } catch (err) {
+          if (!cancelled) {
+            // Source stream errored — propagate to both branches.
+            // cancelBoth with initiator skips our own controller,
+            // so we error it explicitly here.
+            cancelBoth(err, branchIndex);
+            try {
+              controller.error(err);
+            } catch {
+              /* already closed/errored */
+            }
+          }
+        }
+      },
+
+      cancel(reason) {
+        // Consumer cancelled this branch — propagate to the other
+        cancelBoth(reason, branchIndex);
+      },
+    });
+  }
+
+  const wrapped1 = wrapBranch(
+    0,
+    rawBranch1,
+    (r) => {
+      rawReader1 = r;
+    },
+    (c) => {
+      controller1 = c;
+    },
+    (n) => {
+      consumed1 += n;
+    },
+    () => consumed1,
+    () => consumed2
+  );
+
+  const wrapped2 = wrapBranch(
+    1,
+    rawBranch2,
+    (r) => {
+      rawReader2 = r;
+    },
+    (c) => {
+      controller2 = c;
+    },
+    (n) => {
+      consumed2 += n;
+    },
+    () => consumed2,
+    () => consumed1
+  );
+
+  return [wrapped1, wrapped2];
+}
+
+/**
+ * Wrap a response body with stream-lifecycle timing instrumentation.
+ *
+ * Logs firstChunk, lastChunk, close, maxGap (largest inter-chunk gap),
+ * chunk count, and byte count on stream termination (clean close OR
+ * cancellation/disconnect). Gated behind `serverTiming: 'detailed'`.
+ *
+ * Uses a manual reader pump to guarantee logging on all termination
+ * paths — TransformStream.flush() is not called on cancellation.
+ */
+export function wrapResponseWithStreamTiming(
+  body: ReadableStream<Uint8Array>,
+  startTime: number
+): ReadableStream<Uint8Array> {
+  let firstChunkMs = 0;
+  let lastChunkMs = 0;
+  let maxGapMs = 0;
+  let prevChunkTime = 0;
+  let chunks = 0;
+  let bytes = 0;
+  let cancelled = false;
+
+  function emitLog(): void {
+    const closeMs = Math.round(performance.now() - startTime);
+    getLogger().debug('stream-lifecycle', {
+      firstChunkMs,
+      lastChunkMs,
+      closeMs,
+      maxGapMs,
+      chunks,
+      bytes,
+      ...(cancelled ? { cancelled: true } : {}),
+    });
+  }
+
+  const reader = body.getReader();
+
+  return new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      try {
+        const { done, value } = await reader.read();
+        if (done) {
+          emitLog();
+          controller.close();
+          return;
+        }
+
+        const now = performance.now();
+        const relativeMs = Math.round(now - startTime);
+
+        if (chunks === 0) {
+          firstChunkMs = relativeMs;
+        } else {
+          const gap = Math.round(now - prevChunkTime);
+          if (gap > maxGapMs) maxGapMs = gap;
+        }
+
+        prevChunkTime = now;
+        lastChunkMs = relativeMs;
+        chunks++;
+        bytes += value.byteLength;
+
+        controller.enqueue(value);
+      } catch (err) {
+        emitLog();
+        controller.error(err);
+      }
+    },
+
+    cancel(reason) {
+      cancelled = true;
+      emitLog();
+      reader.cancel(reason).catch(() => {});
+    },
+  });
+}
+
+/** Format bytes as human-readable string (e.g., "5.00 MB"). */
+function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(2)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(2)} MB`;
+}
+
+/**
+ * Read a byte stream to completion under one overall deadline and return
+ * the concatenated bytes. Every read is raced against the time remaining,
+ * and the reader is cancelled on every exit, so a stalled upstream never
+ * outlives the deadline. See design/02-rendering-pipeline.md §"Always
+ * Timeout-Guard Stream Reads".
+ *
+ * @param label - Prefix for the timeout error message. Both ways the deadline
+ *   can pass (between reads, or while a read is pending) reject with the same
+ *   `${label} did not complete within ${timeoutMs}ms`.
+ */
+export async function readAllBytesWithDeadline(
+  stream: ReadableStream<Uint8Array>,
+  timeoutMs: number,
+  label: string
+): Promise<Uint8Array> {
+  const reader = stream.getReader();
+  const chunks: Uint8Array[] = [];
+  let totalLength = 0;
+  const deadline = Date.now() + timeoutMs;
+  const deadlineError = () => new Error(`${label} did not complete within ${timeoutMs}ms`);
+  try {
+    for (;;) {
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) throw deadlineError();
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      const timeout = new Promise<never>((_, reject) => {
+        timer = setTimeout(() => reject(deadlineError()), remaining);
+      });
+      let result: ReadableStreamReadResult<Uint8Array>;
+      try {
+        result = await Promise.race([reader.read(), timeout]);
+      } finally {
+        clearTimeout(timer);
+      }
+      if (result.done) break;
+      chunks.push(result.value);
+      totalLength += result.value.byteLength;
+    }
+  } finally {
+    reader.cancel().catch(() => {});
+  }
+  const bytes = new Uint8Array(totalLength);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return bytes;
+}

package/src/server/tracing.ts

@@ -1,7 +1,7 @@
 /**
  * Tracing — per-request trace ID via AsyncLocalStorage, OTEL span helpers.
  *
- * traceId() is always available in server code (middleware, access, components, actions).
+ * getTraceId() is always available in server code (middleware, access, components, actions).
  * Returns a 32-char lowercase hex string — the OTEL trace ID when an SDK is active,
  * or a crypto.randomUUID()-derived fallback otherwise.
  *
@@ -9,10 +9,10 @@
  */
 
 import { randomUUID } from 'node:crypto';
-import { traceAls, type TraceStore } from './als-registry.js';
+import { traceAls, type TraceStore } from './als-registry.ts';
 
 // Re-export the TraceStore type for public API consumers.
-export type { TraceStore } from './als-registry.js';
+export type { TraceStore } from './als-registry.ts';
 
 // ─── Public API ───────────────────────────────────────────────────────────
 
@@ -24,21 +24,21 @@ export type { TraceStore } from './als-registry.js';
  *
  * Throws if called outside a request context (no ALS store).
  */
-export function traceId(): string {
+export function getTraceId(): string {
   const store = traceAls.getStore();
   if (!store) {
     throw new Error(
-      '[timber] traceId() called outside of a request context. ' +
+      '[timber] getTraceId() called outside of a request context. ' +
         'It can only be used in middleware, access checks, server components, and server actions.'
     );
   }
-  return store.traceId;
+  return store.request.traceId;
 }
 
 /**
  * Returns the current OTEL span ID if available, undefined otherwise.
  */
-export function spanId(): string | undefined {
+export function getSpanId(): string | undefined {
   return traceAls.getStore()?.spanId;
 }
 
@@ -57,36 +57,40 @@ export function generateTraceId(): string {
  * per-request ALS scope.
  */
 export function runWithTraceId<T>(id: string, fn: () => T): T {
-  return traceAls.run({ traceId: id }, fn);
+  return traceAls.run({ request: { traceId: id } }, fn);
 }
 
 /**
- * Replace the trace ID in the current ALS store. Used when OTEL creates
- * a root span and we want to switch from the UUID fallback to the real
- * OTEL trace ID.
+ * Replace the request's trace ID. Used when OTEL creates the root span and
+ * we want to switch from the UUID fallback to the real OTEL trace ID. Writes
+ * the request's shared trace, so every scope in the request sees it —
+ * including the ones outside the span this runs in.
  */
-export function replaceTraceId(newTraceId: string, newSpanId?: string): void {
+export function replaceTraceId(newTraceId: string): void {
   const store = traceAls.getStore();
   if (store) {
-    store.traceId = newTraceId;
-    store.spanId = newSpanId;
+    store.request.traceId = newTraceId;
   }
 }
 
 /**
- * Update the span ID in the current ALS store. Used when entering a new
- * OTEL span to keep log–trace correlation accurate.
+ * Run `fn` in a new trace scope for one span: the enclosing scope's request
+ * trace, with this span's pointers. A scope per span, not a save/restore on
+ * a shared store — spans overlap (MetadataCollector does not await
+ * `timber.metadata`), and a restore that runs after a sibling's would
+ * leave the sibling's pointer behind (TIM-1538).
  */
-export function updateSpanId(newSpanId: string | undefined): void {
+function runInSpanScope<T>(
+  pointers: Pick<TraceStore, 'spanId'> | Pick<TraceStore, 'platformSpan'>,
+  fn: () => T
+): T {
   const store = traceAls.getStore();
-  if (store) {
-    store.spanId = newSpanId;
-  }
+  return store ? traceAls.run({ ...store, ...pointers }, fn) : fn();
 }
 
 /**
  * Get the current trace store, or undefined if outside a request context.
- * Framework-internal — use traceId()/spanId() in user code.
+ * Framework-internal — use getTraceId()/getSpanId() in user code.
  */
 export function getTraceStore(): TraceStore | undefined {
   return traceAls.getStore();
@@ -94,6 +98,16 @@ export function getTraceStore(): TraceStore | undefined {
 
 // ─── Dev-Mode OTEL Auto-Init ─────────────────────────────────────────────
 
+/**
+ * Well-known key marking dev tracing as initialized.
+ *
+ * The RSC entry module re-evaluates on every HMR invalidation and calls
+ * initDevTracing() again — without this guard, each call would register a
+ * fresh provider/processor and duplicate every span's output. Symbol.for()
+ * survives module re-evaluation. See TIM-1067, B49.
+ */
+const DEV_TRACING_INIT_KEY = Symbol.for('timber.dev.tracing-initialized');
+
 /**
  * Initialize a minimal OTEL SDK in dev mode so spans are recorded and
  * fed to the DevSpanProcessor for dev log output.
@@ -102,38 +116,78 @@ export function getTraceStore(): TraceStore | undefined {
  * our DevSpanProcessor alongside theirs. If no SDK is configured,
  * we create a BasicTracerProvider with our processor.
  *
- * Only called in dev mode — zero overhead in production.
+ * Idempotent across module re-evaluations (HMR) — only the first call
+ * registers. Called in dev, and in production only when TIMBER_DEBUG is
+ * set — otherwise production never loads the OTEL SDK.
  */
 export async function initDevTracing(
-  config: import('./dev-logger.js').DevLoggerConfig
+  config: import('../dev-tools/logger.ts').DevLoggerConfig
 ): Promise<void> {
+  const globals = globalThis as Record<symbol, unknown>;
+  if (globals[DEV_TRACING_INIT_KEY]) return;
+
   const api = await getOtelApi();
   if (!api) return;
 
-  const { DevSpanProcessor } = await import('./dev-span-processor.js');
-  const { BasicTracerProvider } = await import('@opentelemetry/sdk-trace-base');
-  const { AsyncLocalStorageContextManager } = await import('@opentelemetry/context-async-hooks');
-  const processor = new DevSpanProcessor(config);
-
-  // Register a context manager so OTEL can propagate the active span
-  // across async boundaries. Without this, startActiveSpan can't make
-  // spans "active" — child spans get random trace IDs and getActiveSpan()
-  // returns undefined.
-  const contextManager = new AsyncLocalStorageContextManager();
-  contextManager.enable();
-  api.context.setGlobalContextManager(contextManager);
-
-  // Create a minimal TracerProvider with our DevSpanProcessor.
-  // If the user also configures an SDK in register(), their provider
-  // will coexist — the global provider set last wins for new tracers,
-  // but our processor captures all spans from the timber.js tracer.
-  const provider = new BasicTracerProvider({
-    spanProcessors: [processor],
-  });
-  api.trace.setGlobalTracerProvider(provider);
+  // Tracing is a diagnostic: any failure to load or construct the SDK
+  // disables it with a warning and never fails the server's boot (TIM-1554).
+  try {
+    const { registerDevTracing } = await import('../dev-tools/instrumentation.ts');
+    registerDevTracing(config);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.warn(`[timber] Dev tracing disabled — failed to set up OTEL:\n  ${msg}`);
+    return;
+  }
 
   // Reset cached tracer so next getTracer() picks up the new provider
   _tracer = undefined;
+
+  globals[DEV_TRACING_INIT_KEY] = true;
+}
+
+// ─── Platform Tracer ─────────────────────────────────────────────────────
+
+/**
+ * A native platform span. Mirrors the subset of the Cloudflare Workers
+ * `Span` API that timber uses. See design/17-logging.md §"Cloudflare Native
+ * Spans" and TIM-1135.
+ */
+export interface PlatformSpan {
+  setAttribute(key: string, value: string | number | boolean): void;
+}
+
+/**
+ * Adapter-provided native tracer. Callback-scoped like Cloudflare's
+ * `tracing.enterSpan()` — the span starts when the callback is invoked and
+ * ends when it returns or its promise settles. Nesting follows the
+ * platform's async context.
+ *
+ * When registered, withSpan() wraps every framework span in a native span
+ * *in addition to* the OTEL emission — dual emission, so external OTEL
+ * collectors keep working alongside the platform's native trace view.
+ *
+ * Register via setPlatformTracer(), or by writing the
+ * Symbol.for('timber:platform-tracer') key on globalThis from
+ * adapter-generated entry code (what the Cloudflare _worker.js does).
+ */
+export interface PlatformTracer {
+  enterSpan<T>(name: string, fn: (span: PlatformSpan) => T): T;
+}
+
+// globalThis + Symbol.for so a tracer registered by adapter-generated entry
+// code (a separate module instance) is visible in both the RSC and SSR
+// environments — same pattern as the cf-bindings ALS.
+const PLATFORM_TRACER_KEY = Symbol.for('timber:platform-tracer');
+
+/** Register (or clear) the native platform tracer for this runtime. */
+export function setPlatformTracer(tracer: PlatformTracer | undefined): void {
+  (globalThis as Record<symbol, unknown>)[PLATFORM_TRACER_KEY] = tracer;
+}
+
+/** The registered native platform tracer, if any. */
+export function getPlatformTracer(): PlatformTracer | undefined {
+  return (globalThis as Record<symbol, unknown>)[PLATFORM_TRACER_KEY] as PlatformTracer | undefined;
 }
 
 // ─── OTEL Span Helpers ───────────────────────────────────────────────────
@@ -178,19 +232,47 @@ export async function getTracer(): Promise<import('@opentelemetry/api').Tracer |
 }
 
 /**
- * Run a function within an OTEL span. If OTEL is not available, runs the function
- * directly without any span overhead.
+ * Run a function within a framework span. Composes two emission channels:
+ *
+ * - **Native platform span** — when an adapter registered a PlatformTracer
+ *   (Cloudflare Workers), the fn is wrapped in platformTracer.enterSpan()
+ *   so it appears in the platform's native trace view.
+ * - **OTEL span** — when an OTEL SDK is active, the fn also runs inside an
+ *   OTEL span (dual emission). No SDK and no platform tracer = zero overhead.
  *
  * Automatically:
  * - Creates the span as a child of the current context
- * - Updates the ALS span ID for log–trace correlation
+ * - Runs fn in its own trace scope carrying the span's IDs, for log–trace
+ *   correlation and setSpanAttribute()
  * - Ends the span when the function completes
- * - Records exceptions on error
+ * - Records exceptions on error (OTEL channel)
  */
 export async function withSpan<T>(
   name: string,
   attributes: Record<string, string | number | boolean>,
   fn: () => T | Promise<T>
+): Promise<T> {
+  const platformTracer = getPlatformTracer();
+  if (!platformTracer) {
+    return runOtelSpan(name, attributes, fn);
+  }
+
+  // Native platform span wraps the OTEL emission (dual emission). The
+  // span is tracked on its own trace scope so setSpanAttribute() can reach
+  // it after creation — the platform API has no getActiveSpan() equivalent.
+  return platformTracer.enterSpan(name, (span) => {
+    for (const key of Object.keys(attributes)) {
+      span.setAttribute(key, attributes[key]);
+    }
+    return runInSpanScope({ platformSpan: span }, () => runOtelSpan(name, attributes, fn));
+  });
+}
+
+/** The OTEL half of withSpan() — no-op passthrough when no SDK is active. */
+async function runOtelSpan<T>(
+  name: string,
+  attributes: Record<string, string | number | boolean>,
+  fn: () => T | Promise<T>
 ): Promise<T> {
   const tracer = await getTracer();
   if (!tracer) {
@@ -198,24 +280,30 @@ export async function withSpan<T>(
   }
 
   const api = (await getOtelApi())!;
-  return tracer.startActiveSpan(name, { attributes }, async (span) => {
-    const prevSpanId = spanId();
-    updateSpanId(span.spanContext().spanId);
-    try {
-      const result = await fn();
-      span.setStatus({ code: api.SpanStatusCode.OK });
-      return result;
-    } catch (error) {
-      span.setStatus({ code: api.SpanStatusCode.ERROR });
-      if (error instanceof Error) {
-        span.recordException(error);
-      }
-      throw error;
-    } finally {
-      span.end();
-      updateSpanId(prevSpanId);
+  return tracer.startActiveSpan(name, { attributes }, (span) =>
+    runInSpanScope({ spanId: span.spanContext().spanId }, () => settleOtelSpan(api, span, fn))
+  );
+}
+
+/** Run `fn` and end `span` with its outcome. */
+async function settleOtelSpan<T>(
+  api: typeof import('@opentelemetry/api'),
+  span: import('@opentelemetry/api').Span,
+  fn: () => T | Promise<T>
+): Promise<T> {
+  try {
+    const result = await fn();
+    span.setStatus({ code: api.SpanStatusCode.OK });
+    return result;
+  } catch (error) {
+    span.setStatus({ code: api.SpanStatusCode.ERROR });
+    if (error instanceof Error) {
+      span.recordException(error);
     }
-  });
+    throw error;
+  } finally {
+    span.end();
+  }
 }
 
 /**
@@ -226,6 +314,12 @@ export async function setSpanAttribute(
   key: string,
   value: string | number | boolean
 ): Promise<void> {
+  // Forward to the innermost active native platform span, if any.
+  const platformSpan = traceAls.getStore()?.platformSpan;
+  if (platformSpan) {
+    platformSpan.setAttribute(key, value);
+  }
+
   const api = await getOtelApi();
   if (!api) return;
 
@@ -277,9 +371,10 @@ export function addSpanEventSync(
 
 /**
  * Try to extract the OTEL trace ID from the current active span context.
- * Returns undefined if OTEL is not active or no span exists.
+ * Returns undefined if OTEL is not active or no span exists. (The span ID
+ * reaches logs through the span's own trace scope, not from here.)
  */
-export async function getOtelTraceId(): Promise<{ traceId: string; spanId: string } | undefined> {
+export async function getOtelTraceId(): Promise<string | undefined> {
   const api = await getOtelApi();
   if (!api) return undefined;
 
@@ -292,5 +387,5 @@ export async function getOtelTraceId(): Promise<{ traceId: string; spanId: strin
     return undefined;
   }
 
-  return { traceId: ctx.traceId, spanId: ctx.spanId };
+  return ctx.traceId;
 }