autotel 2.26.3 → 3.0.3

package/src/index.ts

@@ -60,12 +60,16 @@ export {
   AttributeRedactingProcessor,
   REDACTOR_PATTERNS,
   REDACTOR_PRESETS,
+  builtinPatterns,
   createAttributeRedactor,
   createRedactedSpan,
+  normalizeAttributeRedactorConfig,
   type AttributeRedactorFn,
   type AttributeRedactorPreset,
   type AttributeRedactorConfig,
   type AttributeRedactingProcessorOptions,
+  type BuiltinPatternName,
+  type MaskFn,
   type ValuePatternConfig,
 } from './attribute-redacting-processor';
 
@@ -81,7 +85,6 @@ export type {
   InstrumentOptions,
 } from './functional';
 export {
-  trace,
   instrument,
   withTracing,
   span,
@@ -89,6 +92,9 @@ export {
   withBaggage,
   ctx,
 } from './functional';
+// `trace` is the hybrid: callable like autotel's `trace(fn)` AND carries the
+// full `@opentelemetry/api` TraceAPI surface (getActiveSpan, getTracer, etc).
+export { trace } from './trace-hybrid';
 
 // Operation context (for advanced usage)
 export type { OperationContext } from './operation-context';
@@ -121,6 +127,8 @@ export {
   type RequestLogger,
   type RequestLogSnapshot,
   type RequestLoggerOptions,
+  type ForkLifecycle,
+  type ForkOptions,
 } from './request-logger';
 
 // Structured errors
@@ -145,6 +153,19 @@ export {
   type DrainPipelineOptions,
   type PipelineDrainFn,
 } from './drain-pipeline';
+export {
+  defineDrain,
+  defineHttpDrain,
+  type DrainOptions,
+  type HttpDrainOptions,
+  type HttpDrainRequest,
+} from './drain-toolkit';
+export {
+  defineEnricher,
+  type EnricherDefinition,
+  type EnrichContext,
+  type EnricherOptions,
+} from './enricher-toolkit';
 
 // Pretty log formatting
 export { formatDuration } from './pretty-log-formatter';
@@ -333,19 +354,33 @@ export {
   type TLSAttrs,
 } from './attributes';
 
-// Re-export common OpenTelemetry types and utilities
-// This allows plugins and apps to use OTel without needing separate @opentelemetry/api installation
+// Re-export common OpenTelemetry types and utilities so plugins, apps, and
+// existing OTel code can `import { ... } from 'autotel'` without also taking
+// a separate `@opentelemetry/api` dependency.
 export type {
   Span,
   SpanContext,
+  SpanAttributes,
   Tracer,
+  TracerProvider,
   Context,
+  Attributes,
+  AttributeValue,
+  Link,
   Link as SpanLink,
+  TimeInput,
+  HrTime,
+  Baggage,
+  BaggageEntry,
+  Exception,
+  TraceFlags,
+  TraceState,
   TextMapSetter,
   TextMapGetter,
 } from '@opentelemetry/api';
 export { SpanKind, ROOT_CONTEXT } from '@opentelemetry/api';
-// Note: trace exported from functional.ts, context/propagation/SpanStatusCode already exported above
+// Note: trace, context, propagation, SpanStatusCode already exported above
+// (`trace` is the hybrid; `otelTrace` is the pure TraceAPI singleton).
 
 // Export typed baggage helper
 export { defineBaggageSchema } from './trace-context';

package/src/messaging.ts

@@ -50,6 +50,7 @@ import type {
 } from '@opentelemetry/api';
 import { trace } from './functional';
 import type { TraceContext } from './trace-context';
+import { emitCorrelatedEvent } from './correlated-events';
 import { createLinkFromHeaders, extractLinksFromBatch } from './sampling';
 
 // ============================================================================
@@ -1406,7 +1407,7 @@ function extendContextForConsumer(
           producerLink.context.spanId;
       }
 
-      baseCtx.addEvent('dlq_routed', eventAttrs);
+      emitCorrelatedEvent(baseCtx, 'dlq_routed', eventAttrs);
 
       // Call user's onDLQ callback if provided
       if (config.onDLQ) {
@@ -1447,7 +1448,7 @@ function extendContextForConsumer(
         }),
       };
 
-      baseCtx.addEvent('dlq_replay', eventAttrs);
+      emitCorrelatedEvent(baseCtx, 'dlq_replay', eventAttrs);
     },
 
     recordRetry(attemptNumber: number, maxAttempts?: number): void {
@@ -1455,7 +1456,7 @@ function extendContextForConsumer(
       if (maxAttempts !== undefined) {
         baseCtx.setAttribute('messaging.retry.max_attempts', maxAttempts);
       }
-      baseCtx.addEvent('retry_attempt', {
+      emitCorrelatedEvent(baseCtx, 'retry_attempt', {
         'messaging.retry.count': attemptNumber,
         ...(maxAttempts !== undefined && {
           'messaging.retry.max_attempts': maxAttempts,
@@ -1585,7 +1586,7 @@ function extendContextForConsumer(
           event.partitions.map((p) => `${p.topic}:${p.partition}`).join(',');
       }
 
-      baseCtx.addEvent(`consumer_group_${event.type}`, eventAttrs);
+      emitCorrelatedEvent(baseCtx, `consumer_group_${event.type}`, eventAttrs);
 
       // Call user's onRebalance callback if provided
       if (config.consumerGroupTracking?.onRebalance) {
@@ -1627,7 +1628,7 @@ function extendContextForConsumer(
         );
       }
 
-      baseCtx.addEvent('consumer_group_heartbeat', {
+      emitCorrelatedEvent(baseCtx, 'consumer_group_heartbeat', {
         'messaging.consumer_group.heartbeat.healthy': healthy,
         'messaging.consumer_group.heartbeat.timestamp':
           groupState.lastHeartbeat,
@@ -1644,7 +1645,7 @@ function extendContextForConsumer(
       baseCtx.setAttribute(`${prefix}.end_offset`, lag.endOffset);
       baseCtx.setAttribute(`${prefix}.lag`, lag.lag);
 
-      baseCtx.addEvent('partition_lag_recorded', {
+      emitCorrelatedEvent(baseCtx, 'partition_lag_recorded', {
         'messaging.consumer_group.lag.topic': lag.topic,
         'messaging.consumer_group.lag.partition': lag.partition,
         'messaging.consumer_group.lag.current_offset': lag.currentOffset,
@@ -1899,7 +1900,7 @@ async function extractLagMetrics(
         ctx.setAttribute('messaging.kafka.consumer_lag', lag);
 
         // Add lag event
-        ctx.addEvent('consumer_lag_measured', {
+        emitCorrelatedEvent(ctx, 'consumer_lag_measured', {
           'messaging.kafka.consumer_lag': lag,
           'messaging.kafka.message.offset': currentOffset,
           'messaging.kafka.high_watermark': endOffset,
@@ -2119,7 +2120,7 @@ function extractAndProcessOrdering(
           }
 
           // Add event for each out-of-order message
-          ctx.addEvent('message_out_of_order', {
+          emitCorrelatedEvent(ctx, 'message_out_of_order', {
             'messaging.ordering.batch_index': i,
             'messaging.ordering.current_sequence': msgSequence,
             'messaging.ordering.expected_sequence': expectedSequence,
@@ -2155,7 +2156,7 @@ function extractAndProcessOrdering(
         duplicateCount++;
 
         // Add event for each duplicate
-        ctx.addEvent('message_duplicate', {
+        emitCorrelatedEvent(ctx, 'message_duplicate', {
           'messaging.ordering.batch_index': i,
           'messaging.message.id': msgId,
         });

package/src/redact-values.test.ts

@@ -10,18 +10,32 @@ describe('createStringRedactor', () => {
       redact = createStringRedactor('default');
     });
 
-    it('redacts emails', () => {
+    it('smart-masks emails', () => {
       expect(redact('Contact user@example.com for info')).toBe(
-        'Contact [REDACTED] for info',
+        'Contact u***@***.com for info',
       );
     });
 
-    it('redacts phone numbers', () => {
-      expect(redact('Call 555-123-4567 now')).toBe('Call [REDACTED] now');
+    it('smart-masks international phone numbers (country code + last 2 digits)', () => {
+      expect(redact('Call +33 1 23 45 67 89 now')).toBe('Call +33******89 now');
     });
 
-    it('redacts credit card numbers', () => {
-      expect(redact('Card: 4111-1111-1111-1111')).toBe('Card: [REDACTED]');
+    it('smart-masks phone numbers with parens (last 2 digits)', () => {
+      expect(redact('Call (415) 555-1234 now')).toBe('Call ********34 now');
+    });
+
+    it('smart-masks common US phone formats', () => {
+      expect(redact('Call 555-123-4567 now')).toBe('Call ********67 now');
+      expect(redact('Call 5551234567 now')).toBe('Call ********67 now');
+    });
+
+    it('does not mistake bare digit runs for phone numbers', () => {
+      // UUIDs, order ids etc. should pass through untouched.
+      expect(redact('Order: 12345678 ok')).toBe('Order: 12345678 ok');
+    });
+
+    it('smart-masks credit card numbers (last four digits preserved)', () => {
+      expect(redact('Card: 4111-1111-1111-1111')).toBe('Card: ****1111');
     });
 
     it('returns input unchanged when no patterns match', () => {
@@ -36,15 +50,15 @@ describe('createStringRedactor', () => {
       redact = createStringRedactor('strict');
     });
 
-    it('redacts JWTs', () => {
+    it('smart-masks JWTs', () => {
       const jwt =
         'eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.abc123_-def';
-      expect(redact(`Token: ${jwt}`)).toBe('Token: [REDACTED]');
+      expect(redact(`Token: ${jwt}`)).toBe('Token: eyJ***.***');
     });
 
-    it('redacts bearer tokens', () => {
+    it('smart-masks bearer tokens', () => {
       expect(redact('Authorization: Bearer abc123.xyz')).toBe(
-        'Authorization: [REDACTED]',
+        'Authorization: Bearer ***',
       );
     });
   });

package/src/redact-values.ts

@@ -18,9 +18,16 @@ export function createStringRedactor(
 
   return (value: string): string => {
     let result = value;
-    for (const { pattern, replacement } of valuePatterns) {
+    for (const { pattern, replacement, mask } of valuePatterns) {
       pattern.lastIndex = 0;
-      result = result.replaceAll(pattern, replacement ?? defaultReplacement);
+      // Smart masks (e.g. email → a***@***.com) take precedence over the
+      // static replacement so callers see the same output as the
+      // span-attribute redactor does.
+      if (mask) {
+        result = result.replaceAll(pattern, (match) => mask(match));
+      } else {
+        result = result.replaceAll(pattern, replacement ?? defaultReplacement);
+      }
     }
     return result;
   };

package/src/request-logger.test.ts

@@ -254,6 +254,97 @@ describe('log.fork()', () => {
     expect(ctx.setAttributes).not.toHaveBeenCalled();
     expect(childSpan.end).toHaveBeenCalledTimes(1);
   });
+
+  it('fork lifecycle hooks fire around child handler', async () => {
+    const ctx = createMockContext();
+    const log = getRequestLogger(ctx);
+    const childSpan = {
+      spanContext: () => ({
+        traceId: 'a'.repeat(32),
+        spanId: 'b'.repeat(16),
+      }),
+      setAttribute: vi.fn(),
+      setAttributes: vi.fn(),
+      setStatus: vi.fn(),
+      recordException: vi.fn(),
+      addEvent: vi.fn(),
+      addLink: vi.fn(),
+      addLinks: vi.fn(),
+      updateName: vi.fn(),
+      isRecording: vi.fn(() => true),
+      end: vi.fn(),
+    };
+
+    vi.spyOn(otelTrace, 'getTracer').mockReturnValue({
+      startActiveSpan: (
+        _name: string,
+        cb: (span: typeof childSpan) => Promise<void>,
+      ) => cb(childSpan),
+    } as unknown as ReturnType<typeof otelTrace.getTracer>);
+
+    const calls: string[] = [];
+    const onChildEnter = vi.fn(() => calls.push('enter'));
+    const onChildExit = vi.fn(() => calls.push('exit'));
+
+    log.fork(
+      'bg',
+      async () => {
+        calls.push('handler');
+      },
+      { lifecycle: { onChildEnter, onChildExit } },
+    );
+
+    await new Promise((resolve) => setImmediate(resolve));
+    await new Promise((resolve) => setImmediate(resolve));
+
+    expect(onChildEnter).toHaveBeenCalledTimes(1);
+    expect(onChildExit).toHaveBeenCalledTimes(1);
+    expect(calls).toEqual(['enter', 'handler', 'exit']);
+  });
+
+  it('fork onChildExit hook errors do not crash fork cleanup', async () => {
+    const ctx = createMockContext();
+    const log = getRequestLogger(ctx);
+    const consoleSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const childSpan = {
+      spanContext: () => ({
+        traceId: 'a'.repeat(32),
+        spanId: 'b'.repeat(16),
+      }),
+      setAttribute: vi.fn(),
+      setAttributes: vi.fn(),
+      setStatus: vi.fn(),
+      recordException: vi.fn(),
+      addEvent: vi.fn(),
+      addLink: vi.fn(),
+      addLinks: vi.fn(),
+      updateName: vi.fn(),
+      isRecording: vi.fn(() => true),
+      end: vi.fn(),
+    };
+
+    vi.spyOn(otelTrace, 'getTracer').mockReturnValue({
+      startActiveSpan: (
+        _name: string,
+        cb: (span: typeof childSpan) => Promise<void>,
+      ) => cb(childSpan),
+    } as unknown as ReturnType<typeof otelTrace.getTracer>);
+
+    log.fork('bg', async () => {}, {
+      lifecycle: {
+        onChildExit: () => {
+          throw new Error('hook exploded');
+        },
+      },
+    });
+
+    await new Promise((resolve) => setImmediate(resolve));
+    await new Promise((resolve) => setImmediate(resolve));
+
+    expect(childSpan.end).toHaveBeenCalledTimes(1);
+    expect(consoleSpy).toHaveBeenCalled();
+    consoleSpy.mockRestore();
+  });
 });
 
 describe('getRequestLogger', () => {

package/src/request-logger.ts

@@ -4,6 +4,7 @@ import type { TraceContext } from './trace-context';
 import { createTraceContext } from './trace-context';
 import { recordStructuredError } from './structured-error';
 import { flattenToAttributes } from './flatten-attributes';
+import { emitCorrelatedEvent } from './correlated-events';
 
 const POST_EMIT_FORK_HINT =
   "For intentional background work tied to this request, use log.fork('label', fn) when available.";
@@ -55,7 +56,11 @@ export interface RequestLogger {
   error(error: Error | string, fields?: Record<string, unknown>): void;
   getContext(): Record<string, unknown>;
   emitNow(overrides?: Record<string, unknown>): RequestLogSnapshot;
-  fork(label: string, fn: () => void | Promise<void>): void;
+  fork(
+    label: string,
+    fn: () => void | Promise<void>,
+    options?: ForkOptions,
+  ): void;
 }
 
 export interface RequestLogSnapshot {
@@ -71,6 +76,21 @@ export interface RequestLoggerOptions {
   onEmit?: (snapshot: RequestLogSnapshot) => void | Promise<void>;
 }
 
+/**
+ * Optional lifecycle hooks for adapters that need to track child loggers
+ * spawned by `log.fork()` (e.g. active logger maps in framework integrations).
+ */
+export interface ForkLifecycle {
+  /** Called after the child logger is created, before `fn` runs. */
+  onChildEnter?: (child: RequestLogger) => void;
+  /** Called after the child has finished (emit + drain), success or failure. */
+  onChildExit?: (child: RequestLogger) => void;
+}
+
+export interface ForkOptions {
+  lifecycle?: ForkLifecycle;
+}
+
 function resolveContext(ctx?: TraceContext): TraceContext {
   if (ctx) return ctx;
 
@@ -101,9 +121,9 @@ export function getRequestLogger(
     fields?: Record<string, unknown>,
   ) => {
     const attrs = fields ? flattenToAttributes(fields) : undefined;
-    activeContext.addEvent(`log.${level}`, {
+    emitCorrelatedEvent(activeContext, `log.${level}`, {
       message,
-      ...attrs,
+      ...(attrs ?? {}),
     });
   };
 
@@ -191,7 +211,7 @@ export function getRequestLogger(
         context: mergedContext,
       };
 
-      activeContext.addEvent('log.emit.manual', {
+      emitCorrelatedEvent(activeContext, 'log.emit.manual', {
         ...flattened,
       });
 
@@ -206,7 +226,11 @@ export function getRequestLogger(
       return snapshot;
     },
 
-    fork(label: string, fn: () => void | Promise<void>): void {
+    fork(
+      label: string,
+      fn: () => void | Promise<void>,
+      forkOptions?: ForkOptions,
+    ): void {
       const parentRequestId = activeContext.correlationId;
       if (typeof parentRequestId !== 'string' || parentRequestId.length === 0) {
         throw new Error(
@@ -216,6 +240,7 @@ export function getRequestLogger(
       }
 
       const tracer = otelTrace.getTracer('autotel.request-logger');
+      const lifecycle = forkOptions?.lifecycle;
       void tracer.startActiveSpan(`request.fork:${label}`, (childSpan) => {
         const childContext: TraceContext = {
           ...createTraceContext(childSpan),
@@ -229,6 +254,8 @@ export function getRequestLogger(
             _parentCorrelationId: parentRequestId,
           });
 
+          lifecycle?.onChildEnter?.(childLog);
+
           void Promise.resolve()
             .then(() => fn())
             .then(() => {
@@ -240,6 +267,14 @@ export function getRequestLogger(
               childLog.emitNow();
             })
             .finally(() => {
+              try {
+                lifecycle?.onChildExit?.(childLog);
+              } catch (hookError) {
+                console.warn(
+                  '[autotel] fork onChildExit hook threw:',
+                  hookError,
+                );
+              }
               childSpan.end();
             });
         });

package/src/structured-error.test.ts

@@ -1,10 +1,41 @@
 import { describe, expect, it, vi } from 'vitest';
+import type { Span, SpanContext } from '@opentelemetry/api';
 import {
   createStructuredError,
   getStructuredErrorAttributes,
   recordStructuredError,
 } from './structured-error';
-import type { TraceContext } from './trace-context';
+import { createTraceContext, type TraceContext } from './trace-context';
+
+function createFakeSpan(): {
+  span: Span;
+  recordException: ReturnType<typeof vi.fn>;
+  setStatus: ReturnType<typeof vi.fn>;
+  setAttributes: ReturnType<typeof vi.fn>;
+} {
+  const recordException = vi.fn();
+  const setStatus = vi.fn();
+  const setAttributes = vi.fn();
+  const spanContext: SpanContext = {
+    traceId: '0123456789abcdef0123456789abcdef',
+    spanId: '0123456789abcdef',
+    traceFlags: 1,
+  };
+  const span = {
+    spanContext: () => spanContext,
+    setAttribute: vi.fn(),
+    setAttributes,
+    setStatus,
+    recordException,
+    addEvent: vi.fn(),
+    addLink: vi.fn(),
+    addLinks: vi.fn(),
+    updateName: vi.fn(),
+    isRecording: () => true,
+    end: vi.fn(),
+  } as unknown as Span;
+  return { span, recordException, setStatus, setAttributes };
+}
 
 describe('structured-error helpers', () => {
   it('creates an error with structured diagnostic fields', () => {
@@ -104,3 +135,57 @@ describe('structured-error helpers', () => {
     );
   });
 });
+
+describe('ctx.recordError', () => {
+  it('records a structured error onto the underlying span', () => {
+    const { span, recordException, setStatus, setAttributes } =
+      createFakeSpan();
+    const ctx = createTraceContext(span);
+    const err = createStructuredError({
+      message: 'Order failed',
+      why: 'Inventory unavailable',
+      fix: 'Retry after restock',
+    });
+
+    ctx.recordError(err);
+
+    expect(recordException).toHaveBeenCalledWith(err);
+    expect(setStatus).toHaveBeenCalledWith({
+      code: 2,
+      message: 'Order failed',
+    });
+    expect(setAttributes).toHaveBeenCalledWith(
+      expect.objectContaining({
+        'error.message': 'Order failed',
+        'error.why': 'Inventory unavailable',
+        'error.fix': 'Retry after restock',
+      }),
+    );
+  });
+
+  it('coerces non-Error values to Error so it is safe in catch blocks', () => {
+    const { span, recordException, setStatus, setAttributes } =
+      createFakeSpan();
+    const ctx = createTraceContext(span);
+
+    ctx.recordError('boom');
+
+    expect(recordException).toHaveBeenCalledTimes(1);
+    const recorded = recordException.mock.calls[0][0];
+    expect(recorded).toBeInstanceOf(Error);
+    expect(recorded.message).toBe('boom');
+    expect(setStatus).toHaveBeenCalledWith({ code: 2, message: 'boom' });
+    expect(setAttributes).toHaveBeenCalled();
+  });
+});
+
+describe('ctx.track', () => {
+  it('exposes track on the trace context as the ergonomic replacement for ctx.addEvent', () => {
+    const { span } = createFakeSpan();
+    const ctx = createTraceContext(span);
+
+    expect(typeof ctx.track).toBe('function');
+    // Smoke test — should not throw without init() (track is a no-op when no queue is configured)
+    expect(() => ctx.track('test.event', { foo: 'bar' })).not.toThrow();
+  });
+});

package/src/structured-error.ts

@@ -138,10 +138,17 @@ export function getStructuredErrorAttributes(
 }
 
 export function recordStructuredError(
-  ctx: Pick<TraceContext, 'recordException' | 'setAttributes' | 'setStatus'>,
+  ctx: Pick<TraceContext, 'setAttributes' | 'setStatus'>,
   error: Error,
 ): void {
-  ctx.recordException(error);
+  const maybeRecordException = (
+    ctx as unknown as {
+      recordException?: (e: Error) => void;
+    }
+  ).recordException;
+  if (typeof maybeRecordException === 'function') {
+    maybeRecordException(error);
+  }
   ctx.setStatus({
     code: SpanStatusCode.ERROR,
     message: error.message,

package/src/trace-context.ts

@@ -8,10 +8,11 @@ import type {
   BaggageEntry,
   Context,
   Link,
-  TimeInput,
 } from '@opentelemetry/api';
 import { context, propagation } from '@opentelemetry/api';
 import { AsyncLocalStorage } from 'node:async_hooks';
+import { recordStructuredError } from './structured-error';
+import { track } from './track';
 
 type AsyncLocalBox<T> = {
   value: T;
@@ -132,14 +133,6 @@ export interface SpanMethods {
   setAttributes(attrs: Record<string, AttributeValue>): void;
   /** Set the status of the span */
   setStatus(status: { code: SpanStatusCode; message?: string }): void;
-  /** Record an exception on the span */
-  recordException(exception: Error, time?: TimeInput): void;
-  /** Add an event to the span (for logging milestones/checkpoints) */
-  addEvent(
-    name: string,
-    attributesOrStartTime?: Record<string, AttributeValue> | TimeInput,
-    startTime?: TimeInput,
-  ): void;
   /** Add a link to another span */
   addLink(link: Link): void;
   /** Add multiple links to other spans */
@@ -148,6 +141,26 @@ export interface SpanMethods {
   updateName(name: string): void;
   /** Check if the span is recording */
   isRecording(): boolean;
+  /**
+   * Record an error on the span: sets ERROR status, structured `error.*`
+   * attributes (including `why`/`fix`/`link` from `createStructuredError`),
+   * and during the OTel Span Event API back-compat window also records the
+   * exception via the legacy span event API.
+   *
+   * Replaces the deprecated `recordException` (OTEP 4430). Accepts `unknown`
+   * so it can be called directly with the value caught from a `catch` block.
+   */
+  recordError(error: unknown): void;
+  /**
+   * Emit a tracked event correlated to this span. Equivalent to the standalone
+   * `track(event, data)` but reads naturally on `ctx`. Replaces the deprecated
+   * `ctx.addEvent` (OTEP 4430) — events become correlated logs rather than
+   * span events.
+   */
+  track<Events extends Record<string, unknown> = Record<string, unknown>>(
+    event: keyof Events & string,
+    data?: Events[keyof Events & string],
+  ): void;
 }
 
 /**
@@ -411,7 +424,13 @@ export function createTraceContext<
       : never,
   };
 
-  return {
+  // `recordException` and `addEvent` are intentionally bound at runtime but
+  // omitted from the `SpanMethods` type. They exist solely so existing call
+  // sites keep working through the OTel Span Event API deprecation window
+  // (see MIGRATION.md). New code MUST go through `recordStructuredError`,
+  // `emitCorrelatedEvent`, or the request logger. The cast below is what hides
+  // these compatibility-only fields from the public type.
+  const traceCtx = {
     traceId: spanContext.traceId,
     spanId: spanContext.spanId,
     correlationId: spanContext.traceId.slice(0, 16),
@@ -424,8 +443,17 @@ export function createTraceContext<
     addLinks: span.addLinks.bind(span),
     updateName: span.updateName.bind(span),
     isRecording: span.isRecording.bind(span),
+    recordError: (error: unknown) => {
+      const err = error instanceof Error ? error : new Error(String(error));
+      recordStructuredError(traceCtx, err);
+    },
+    track: (event: string, data?: Record<string, unknown>) => {
+      track(event, data);
+    },
     ...baggageHelpers,
-  };
+  } as unknown as TraceContext<TBaggage>;
+
+  return traceCtx;
 }
 
 /**