autotel 3.6.0 → 3.7.0

package/dist/index.js

@@ -1,777 +1,975 @@
-export { httpRequestHeaderAttribute, httpResponseHeaderAttribute } from './chunk-7552UTQW.js';
-export { parseError } from './chunk-J7VGRIAJ.js';
-export { createDrainPipeline } from './chunk-KFOHQK7X.js';
-export { getCurrentWorkflowContext, isInWorkflow, traceStep, traceWorkflow } from './chunk-QF7ARNUM.js';
-import { hashJson } from './chunk-UNPLAVE7.js';
-export { attrs, autoRedactPII, dbClient, httpClient, httpServer, identify, mergeAttrs, mergeServiceResource, request, safeSetAttributes, setDevice, setError, setException, setSession, setUser, validateAttribute } from './chunk-454CH4OV.js';
-export { HTTPAttributes, ServiceAttributes, URLAttributes } from './chunk-4A53YIAX.js';
-export { traceConsumer, traceProducer } from './chunk-D4TM63S3.js';
-import { emitCorrelatedEvent } from './chunk-KIL5CUN6.js';
-export { BusinessBaggage, createSafeBaggageSchema } from './chunk-4IFSYQVX.js';
-import { resetMetrics } from './chunk-7SAWIN74.js';
-export { Metric, getMetrics, resetMetrics } from './chunk-7SAWIN74.js';
-import './chunk-5ZN622AO.js';
-export { createCounter, createHistogram, createObservableGauge, createUpDownCounter, getMeter } from './chunk-TQ5UWA7S.js';
-export { traceDB, traceHTTP, traceLLM, traceMessaging } from './chunk-N25JDZSC.js';
-import { trace as trace$1 } from './chunk-T7JO2TCP.js';
-export { ctx, instrument, markAsImmediate, span, withBaggage, withNewContext, withTracing } from './chunk-T7JO2TCP.js';
-export { createDeterministicTraceId, enrichWithTraceContext, finalizeSpan, flattenMetadata, getActiveContext, getActiveSpan, getTraceContext, getTracer, isTracing, resolveTraceUrl, runWithSpan } from './chunk-HT5JQKN2.js';
-import { resetEvents } from './chunk-UIKYE2QZ.js';
-export { Event, getEvents, resetEvents } from './chunk-UIKYE2QZ.js';
-import './chunk-LITNXTTT.js';
-import './chunk-BZHG5IZ4.js';
-export { getOperationContext, runInOperationContext } from './chunk-SEO6NAQT.js';
-import { getEventQueue, resetEventQueue, track, createTraceContext } from './chunk-66YJ66GG.js';
-export { CORRELATION_ID_BAGGAGE_KEY, defineBaggageSchema, generateCorrelationId, getCorrelationId, getEventQueue, getOrCreateCorrelationId, runWithCorrelationId, setCorrelationId, setCorrelationIdInBaggage, track } from './chunk-66YJ66GG.js';
-import { flattenToAttributes, recordStructuredError, createStructuredError } from './chunk-LVIPBYFE.js';
-export { createStructuredError, flattenToAttributes, getStructuredErrorAttributes, recordStructuredError, structuredErrorToJSON, toAttributeValue } from './chunk-LVIPBYFE.js';
-import { getLogger, getSdk, _closeEmbeddedDevtools } from './chunk-ALPYR2GC.js';
-export { BaggageSpanProcessor, createStringRedactor, init, isInitialized, isLoggerLocked, lockLogger } from './chunk-ALPYR2GC.js';
-import './chunk-CMHVQR6P.js';
-import './chunk-A4E5AQFK.js';
-export { FilteringSpanProcessor } from './chunk-WGWSHJ2N.js';
-export { NORMALIZER_PATTERNS, NORMALIZER_PRESETS, SpanNameNormalizingProcessor } from './chunk-GYR5K654.js';
-export { AttributeRedactingProcessor, REDACTOR_PATTERNS, REDACTOR_PRESETS, builtinPatterns, createAttributeRedactor, createRedactedSpan, normalizeAttributeRedactorConfig } from './chunk-RUPKBKUF.js';
-import './chunk-6UQRVUN3.js';
-export { formatDuration } from './chunk-3QXBFGKP.js';
-import './chunk-Q4EULJQY.js';
-export { AUTOTEL_SAMPLING_TAIL_EVALUATED, AUTOTEL_SAMPLING_TAIL_KEEP, AdaptiveSampler, AlwaysSampler, NeverSampler, RandomSampler, UserIdSampler, createLinkFromHeaders, extractLinksFromBatch, resolveSamplingPreset, samplingPresets } from './chunk-DPSA4QLA.js';
-import './chunk-55ER2KD5.js';
-import './chunk-J5QENANM.js';
-export { getAutotelTracer, getAutotelTracerProvider, setAutotelTracerProvider } from './chunk-HA2WBOGQ.js';
-import { trace } from '@opentelemetry/api';
-export { ROOT_CONTEXT, SpanKind, SpanStatusCode, context, trace as otelTrace, propagation } from '@opentelemetry/api';
-import { AsyncLocalStorage } from 'async_hooks';
-import { AggregationType } from '@opentelemetry/sdk-metrics';
+import { AUTOTEL_SAMPLING_TAIL_EVALUATED, AUTOTEL_SAMPLING_TAIL_KEEP, AdaptiveSampler, AlwaysSampler, NeverSampler, RandomSampler, UserIdSampler, createLinkFromHeaders, extractLinksFromBatch, resolveSamplingPreset, samplingPresets } from "./sampling.js";
+import { a as getSdk, c as isInitialized, f as createStringRedactor, i as getLogger, l as isLoggerLocked, p as BaggageSpanProcessor, s as init, t as _closeEmbeddedDevtools, u as lockLogger } from "./init-Ch6t7MNI.js";
+import { FilteringSpanProcessor } from "./filtering-span-processor.js";
+import { NORMALIZER_PATTERNS, NORMALIZER_PRESETS, SpanNameNormalizingProcessor } from "./span-name-normalizer.js";
+import { AttributeRedactingProcessor, REDACTOR_PATTERNS, REDACTOR_PRESETS, builtinPatterns, createAttributeRedactor, createRedactedSpan, normalizeAttributeRedactorConfig } from "./attribute-redacting-processor.js";
+import { n as formatDuration } from "./canonical-log-line-processor-DbBQT5vY.js";
+import { getAutotelTracer, getAutotelTracerProvider, setAutotelTracerProvider } from "./tracer-provider.js";
+import { a as CORRELATION_ID_BAGGAGE_KEY, d as setCorrelationId, f as setCorrelationIdInBaggage, l as getOrCreateCorrelationId, m as defineBaggageSchema, n as resetEventQueue, o as generateCorrelationId, p as createTraceContext, r as track, s as getCorrelationId, t as getEventQueue, u as runWithCorrelationId } from "./track-nsKVy-pj.js";
+import { a as flattenToAttributes, i as structuredErrorToJSON, n as getStructuredErrorAttributes, o as toAttributeValue, r as recordStructuredError, t as createStructuredError } from "./structured-error-9--cxBay.js";
+import { createDeterministicTraceId, enrichWithTraceContext, finalizeSpan, flattenMetadata, getActiveContext, getActiveSpan, getTraceContext, getTracer, isTracing, resolveTraceUrl, runWithSpan } from "./trace-helpers.js";
+import { n as runInOperationContext, t as getOperationContext } from "./operation-context-C-2hmmtP.js";
+import { a as trace$2, c as withTracing, i as span, n as instrument, o as withBaggage, r as markAsImmediate, s as withNewContext, t as ctx } from "./functional-BGkT8J-h.js";
+import { t as hashJson } from "./stable-hash-Cg5cT34Q.js";
+import { n as getEvents, r as resetEvents, t as Event } from "./event-_58ryBjh.js";
+import { Metric, getMetrics, resetMetrics } from "./metric.js";
+import { t as emitCorrelatedEvent } from "./correlated-events-Bzh5y-UB.js";
+import { parseError } from "./parse-error.js";
+import { createDrainPipeline } from "./drain-pipeline.js";
+import { createCounter, createHistogram, createObservableGauge, createUpDownCounter, getMeter } from "./metric-helpers.js";
+import { traceDB, traceHTTP, traceLLM, traceMessaging } from "./semantic-helpers.js";
+import { b as ServiceAttributes, f as HTTPAttributes, w as URLAttributes } from "./registry-DfXA3R1L.js";
+import { httpRequestHeaderAttribute, httpResponseHeaderAttribute } from "./semantic-conventions.js";
+import { a as identify, c as setDevice, d as setSession, f as setUser, h as autoRedactPII, i as httpServer, l as setError, m as safeSetAttributes, n as dbClient, o as mergeServiceResource, p as mergeAttrs, r as httpClient, s as request, u as setException, v as validateAttribute, y as attrs } from "./attributes-ksn4HVbd.js";
+import { traceConsumer, traceProducer } from "./messaging.js";
+import { BusinessBaggage, createSafeBaggageSchema } from "./business-baggage.js";
+import { getCurrentWorkflowContext, isInWorkflow, traceStep, traceWorkflow } from "./workflow.js";
+import { ROOT_CONTEXT, SpanKind, SpanStatusCode, context, propagation, trace as otelTrace, trace as trace$1 } from "@opentelemetry/api";
+import { AggregationType } from "@opentelemetry/sdk-metrics";
+import { AsyncLocalStorage } from "node:async_hooks";
 
-var otelMethods = {
-  // Class methods on TraceAPI — bind to the singleton.
-  setGlobalTracerProvider: trace.setGlobalTracerProvider.bind(trace),
-  getTracerProvider: trace.getTracerProvider.bind(trace),
-  getTracer: trace.getTracer.bind(trace),
-  disable: trace.disable.bind(trace),
-  // Instance fields on TraceAPI — already standalone, copy by reference.
-  wrapSpanContext: trace.wrapSpanContext,
-  isSpanContextValid: trace.isSpanContextValid,
-  deleteSpan: trace.deleteSpan,
-  getSpan: trace.getSpan,
-  getActiveSpan: trace.getActiveSpan,
-  getSpanContext: trace.getSpanContext,
-  setSpan: trace.setSpan,
-  setSpanContext: trace.setSpanContext
+//#region src/trace-hybrid.ts
+/**
+* Hybrid `trace` export: callable like autotel's `trace(fn)`, AND exposes the
+* full `@opentelemetry/api` `TraceAPI` surface (`trace.getActiveSpan()`,
+* `trace.getTracer()`, …) so existing OTel code "just works" when imported
+* from `autotel`.
+*
+* Implementation: `Object.assign` mutates the autotel `trace` function to
+* attach the OTel TraceAPI methods. Because every reference to `trace` across
+* autotel resolves to the same function instance, this is a one-time, global
+* augmentation.
+*/
+const otelMethods = {
+	setGlobalTracerProvider: trace$1.setGlobalTracerProvider.bind(trace$1),
+	getTracerProvider: trace$1.getTracerProvider.bind(trace$1),
+	getTracer: trace$1.getTracer.bind(trace$1),
+	disable: trace$1.disable.bind(trace$1),
+	wrapSpanContext: trace$1.wrapSpanContext,
+	isSpanContextValid: trace$1.isSpanContextValid,
+	deleteSpan: trace$1.deleteSpan,
+	getSpan: trace$1.getSpan,
+	getActiveSpan: trace$1.getActiveSpan,
+	getSpanContext: trace$1.getSpanContext,
+	setSpan: trace$1.setSpan,
+	setSpanContext: trace$1.setSpanContext
 };
-var trace2 = Object.assign(
-  trace$1,
-  otelMethods
-);
+const trace = Object.assign(trace$2, otelMethods);
 
-// src/define-event.ts
+//#endregion
+//#region src/define-event.ts
 function defineEvent(name, schema, options = {}) {
-  const jsonSchema = options.toJsonSchema?.(schema);
-  const schemaMetadata = jsonSchema ? {
-    source: "zod",
-    jsonSchema,
-    hash: hashJson(jsonSchema)
-  } : void 0;
-  return {
-    name,
-    schemaMetadata,
-    track(payload) {
-      const parsed = schema.safeParse(payload);
-      if (!parsed.success) {
-        throw new Error(
-          `Invalid payload for event "${name}". Schema validation failed.`
-        );
-      }
-      track(
-        name,
-        parsed.data,
-        schemaMetadata ? { schema: schemaMetadata } : void 0
-      );
-    }
-  };
+	const jsonSchema = options.toJsonSchema?.(schema);
+	const schemaMetadata = jsonSchema ? {
+		source: "zod",
+		jsonSchema,
+		hash: hashJson(jsonSchema)
+	} : void 0;
+	return {
+		name,
+		schemaMetadata,
+		track(payload) {
+			const parsed = schema.safeParse(payload);
+			if (!parsed.success) throw new Error(`Invalid payload for event "${name}". Schema validation failed.`);
+			track(name, parsed.data, schemaMetadata ? { schema: schemaMetadata } : void 0);
+		}
+	};
 }
 
-// src/shutdown.ts
+//#endregion
+//#region src/shutdown.ts
+/**
+* Graceful shutdown with flush and cleanup
+*/
+/**
+* Flush all pending telemetry
+*
+* Flushes both events events and OpenTelemetry spans to their destinations.
+* Includes timeout protection to prevent hanging in serverless environments.
+*
+* Safe to call multiple times.
+*
+* @param options - Optional configuration
+* @param options.timeout - Timeout in milliseconds (default: 2000ms)
+* @param options.forShutdown - If true, permanently disables the events queue after flush (used internally by shutdown())
+*
+* @example Manual flush in serverless
+* ```typescript
+* import { flush } from 'autotel';
+*
+* export const handler = async (event) => {
+*   // ... process event
+*   await flush(); // Flush before function returns
+*   return result;
+* };
+* ```
+*
+* @example With custom timeout
+* ```typescript
+* await flush({ timeout: 5000 }); // 5 second timeout
+* ```
+*/
 async function flush(options) {
-  const timeout = options?.timeout ?? 2e3;
-  const forShutdown = options?.forShutdown ?? false;
-  const doFlush = async () => {
-    const eventsQueue = getEventQueue();
-    if (eventsQueue) {
-      if (forShutdown) {
-        await eventsQueue.shutdown();
-      } else {
-        await eventsQueue.flush();
-      }
-    }
-    const sdk = getSdk();
-    if (sdk) {
-      try {
-        const sdkAny = sdk;
-        if (typeof sdkAny.getTracerProvider === "function") {
-          const tracerProvider = sdkAny.getTracerProvider();
-          if (tracerProvider && typeof tracerProvider.forceFlush === "function") {
-            await tracerProvider.forceFlush();
-          }
-        }
-      } catch {
-      }
-    }
-  };
-  let timeoutHandle;
-  try {
-    await Promise.race([
-      doFlush().finally(() => {
-        if (timeoutHandle) {
-          clearTimeout(timeoutHandle);
-        }
-      }),
-      new Promise((_, reject) => {
-        timeoutHandle = setTimeout(
-          () => reject(new Error("Flush timeout")),
-          timeout
-        );
-        timeoutHandle.unref();
-      })
-    ]);
-  } catch (error) {
-    if (timeoutHandle) {
-      clearTimeout(timeoutHandle);
-    }
-    const logger = getLogger();
-    logger.error(
-      {
-        err: error instanceof Error ? error : new Error(String(error))
-      },
-      "[autotel] Flush error"
-    );
-    throw error;
-  }
-}
+	const timeout = options?.timeout ?? 2e3;
+	const forShutdown = options?.forShutdown ?? false;
+	const doFlush = async () => {
+		const eventsQueue = getEventQueue();
+		if (eventsQueue) if (forShutdown) await eventsQueue.shutdown();
+		else await eventsQueue.flush();
+		const sdk = getSdk();
+		if (sdk) try {
+			const sdkAny = sdk;
+			if (typeof sdkAny.getTracerProvider === "function") {
+				const tracerProvider = sdkAny.getTracerProvider();
+				if (tracerProvider && typeof tracerProvider.forceFlush === "function") await tracerProvider.forceFlush();
+			}
+		} catch {}
+	};
+	let timeoutHandle;
+	try {
+		await Promise.race([doFlush().finally(() => {
+			if (timeoutHandle) clearTimeout(timeoutHandle);
+		}), new Promise((_, reject) => {
+			timeoutHandle = setTimeout(() => reject(/* @__PURE__ */ new Error("Flush timeout")), timeout);
+			timeoutHandle.unref();
+		})]);
+	} catch (error) {
+		if (timeoutHandle) clearTimeout(timeoutHandle);
+		getLogger().error({ err: error instanceof Error ? error : new Error(String(error)) }, "[autotel] Flush error");
+		throw error;
+	}
+}
+/**
+* Shutdown telemetry and cleanup resources
+*
+* - Flushes all pending data
+* - Shuts down OpenTelemetry SDK
+* - Cleans up resources
+*
+* Call this before process exit.
+*
+* Always performs cleanup even if flush fails, preventing resource leaks
+* in serverless handlers or tests.
+*
+* @example Express server
+* ```typescript
+* const server = app.listen(3000)
+*
+* process.on('SIGTERM', async () => {
+*   await server.close()
+*   await shutdown()
+*   process.exit(0)
+* })
+* ```
+*/
 async function shutdown() {
-  const logger = getLogger();
-  let shutdownError = null;
-  try {
-    await flush({ forShutdown: true });
-  } catch (error) {
-    const err = error instanceof Error ? error : new Error(String(error));
-    shutdownError = err;
-    logger.error(
-      {
-        err
-      },
-      "[autotel] Flush failed during shutdown, continuing cleanup"
-    );
-  }
-  try {
-    const sdk = getSdk();
-    if (sdk) {
-      await sdk.shutdown();
-    }
-  } catch (error) {
-    const err = error instanceof Error ? error : new Error(String(error));
-    const isConnectionRefused = typeof error === "object" && error !== null && "code" in error && error.code === "ECONNREFUSED";
-    if (!isConnectionRefused) {
-      if (!shutdownError) {
-        shutdownError = err;
-      }
-      logger.error({ err }, "[autotel] SDK shutdown failed");
-    }
-  } finally {
-    await _closeEmbeddedDevtools();
-    const eventsQueue = getEventQueue();
-    if (eventsQueue && typeof eventsQueue.cleanup === "function") {
-      eventsQueue.cleanup();
-    }
-    resetEvents();
-    resetMetrics();
-    resetEventQueue();
-  }
-  if (shutdownError) {
-    throw shutdownError;
-  }
-}
+	const logger = getLogger();
+	let shutdownError = null;
+	try {
+		await flush({ forShutdown: true });
+	} catch (error) {
+		const err = error instanceof Error ? error : new Error(String(error));
+		shutdownError = err;
+		logger.error({ err }, "[autotel] Flush failed during shutdown, continuing cleanup");
+	}
+	try {
+		const sdk = getSdk();
+		if (sdk) await sdk.shutdown();
+	} catch (error) {
+		const err = error instanceof Error ? error : new Error(String(error));
+		if (!(typeof error === "object" && error !== null && "code" in error && error.code === "ECONNREFUSED")) {
+			if (!shutdownError) shutdownError = err;
+			logger.error({ err }, "[autotel] SDK shutdown failed");
+		}
+	} finally {
+		await _closeEmbeddedDevtools();
+		const eventsQueue = getEventQueue();
+		if (eventsQueue && typeof eventsQueue.cleanup === "function") eventsQueue.cleanup();
+		resetEvents();
+		resetMetrics();
+		resetEventQueue();
+	}
+	if (shutdownError) throw shutdownError;
+}
+/**
+* Register automatic shutdown hooks for common signals
+*
+* Handles:
+* - SIGTERM (Docker/K8s graceful shutdown)
+* - SIGINT (Ctrl+C)
+*
+* @internal Called automatically on module load
+*/
 function registerShutdownHooks() {
-  if (typeof process === "undefined") return;
-  const signals = ["SIGTERM", "SIGINT"];
-  let shuttingDown = false;
-  for (const signal of signals) {
-    process.on(signal, async () => {
-      if (shuttingDown) return;
-      shuttingDown = true;
-      if (process.env.NODE_ENV !== "test") {
-        getLogger().info(
-          {},
-          `[autotel] Received ${signal}, flushing telemetry...`
-        );
-      }
-      try {
-        await shutdown();
-      } catch (error) {
-        getLogger().error(
-          {
-            err: error instanceof Error ? error : void 0
-          },
-          "[autotel] Error during shutdown"
-        );
-      } finally {
-        process.exit(0);
-      }
-    });
-  }
+	if (typeof process === "undefined") return;
+	const signals = ["SIGTERM", "SIGINT"];
+	let shuttingDown = false;
+	for (const signal of signals) process.on(signal, async () => {
+		if (shuttingDown) return;
+		shuttingDown = true;
+		if (process.env.NODE_ENV !== "test") getLogger().info({}, `[autotel] Received ${signal}, flushing telemetry...`);
+		try {
+			await shutdown();
+		} catch (error) {
+			getLogger().error({ err: error instanceof Error ? error : void 0 }, "[autotel] Error during shutdown");
+		} finally {
+			process.exit(0);
+		}
+	});
 }
 registerShutdownHooks();
-var POST_EMIT_FORK_HINT = "For intentional background work tied to this request, use log.fork('label', fn) when available.";
+
+//#endregion
+//#region src/request-logger.ts
+const POST_EMIT_FORK_HINT = "For intentional background work tied to this request, use log.fork('label', fn) when available.";
 function warnPostEmit(method, detail) {
-  console.warn(
-    `[autotel] ${method} called after the wide event was emitted \u2014 ${detail} This data will not appear in observability. ${POST_EMIT_FORK_HINT}`
-  );
-}
-function mergeInto(target, source) {
-  for (const key in source) {
-    const sourceVal = source[key];
-    if (sourceVal === void 0) continue;
-    const targetVal = target[key];
-    if (sourceVal !== null && typeof sourceVal === "object" && !Array.isArray(sourceVal) && targetVal !== null && typeof targetVal === "object" && !Array.isArray(targetVal)) {
-      mergeInto(
-        targetVal,
-        sourceVal
-      );
-    } else if (Array.isArray(targetVal) && Array.isArray(sourceVal)) {
-      target[key] = [...targetVal, ...sourceVal];
-    } else {
-      target[key] = sourceVal;
-    }
-  }
-}
-var requestContextStore = new AsyncLocalStorage();
-function runWithRequestContext(ctx2, fn) {
-  return requestContextStore.run(ctx2, fn);
-}
-function resolveContext(ctx2) {
-  if (ctx2) return ctx2;
-  const stored = requestContextStore.getStore();
-  if (stored) return stored;
-  const span2 = trace.getActiveSpan();
-  if (!span2) {
-    throw new Error(
-      "[autotel] getRequestLogger() requires an active span or runWithRequestContext(). Wrap your handler with trace() or use runWithRequestContext()."
-    );
-  }
-  return createTraceContext(span2);
-}
-function getRequestLogger(ctx2, options) {
-  const activeContext = resolveContext(ctx2);
-  let contextState = {};
-  let emitted = false;
-  let lastSnapshot = null;
-  const addLogEvent = (level, message, fields) => {
-    const attrs2 = fields ? flattenToAttributes(fields) : void 0;
-    emitCorrelatedEvent(activeContext, `log.${level}`, {
-      message,
-      ...attrs2 ?? {}
-    });
-  };
-  const sealCheck = (method, keys) => {
-    if (emitted) {
-      warnPostEmit(
-        method,
-        `Keys dropped: ${keys.length ? keys.join(", ") : "(empty)"}.`
-      );
-    }
-  };
-  return {
-    set(fields) {
-      sealCheck("log.set()", Object.keys(fields));
-      if (emitted) return;
-      mergeInto(contextState, fields);
-      activeContext.setAttributes(flattenToAttributes(fields));
-    },
-    info(message, fields) {
-      const keys = fields ? ["message", ...Object.keys(fields).filter((k) => k !== "requestLogs")] : ["message"];
-      sealCheck("log.info()", keys);
-      if (emitted) return;
-      addLogEvent("info", message, fields);
-      if (fields) {
-        mergeInto(contextState, fields);
-        activeContext.setAttributes(flattenToAttributes(fields));
-      }
-    },
-    warn(message, fields) {
-      const keys = fields ? ["message", ...Object.keys(fields).filter((k) => k !== "requestLogs")] : ["message"];
-      sealCheck("log.warn()", keys);
-      if (emitted) return;
-      addLogEvent("warn", message, fields);
-      activeContext.setAttribute("autotel.log.level", "warn");
-      if (fields) {
-        mergeInto(contextState, fields);
-        activeContext.setAttributes(flattenToAttributes(fields));
-      }
-    },
-    error(error, fields) {
-      const keys = fields ? [...Object.keys(fields), "error"] : ["error"];
-      sealCheck("log.error()", keys);
-      if (emitted) return;
-      const err = typeof error === "string" ? new Error(error) : error;
-      recordStructuredError(activeContext, err);
-      addLogEvent("error", err.message, fields);
-      if (fields) {
-        mergeInto(contextState, fields);
-        activeContext.setAttributes(flattenToAttributes(fields));
-      }
-      activeContext.setAttribute("autotel.log.level", "error");
-    },
-    getContext() {
-      return { ...contextState };
-    },
-    emitNow(overrides) {
-      if (emitted) {
-        warnPostEmit("log.emitNow()", "Ignoring duplicate emit.");
-        return lastSnapshot;
-      }
-      const mergedContext = {
-        ...contextState,
-        ...overrides ?? {}
-      };
-      const flattened = flattenToAttributes(mergedContext);
-      activeContext.setAttributes(flattened);
-      const snapshot = {
-        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-        traceId: activeContext.traceId,
-        spanId: activeContext.spanId,
-        correlationId: activeContext.correlationId,
-        context: mergedContext
-      };
-      emitCorrelatedEvent(activeContext, "log.emit.manual", {
-        ...flattened
-      });
-      if (options?.onEmit) {
-        Promise.resolve(options.onEmit(snapshot)).catch((error) => {
-          console.warn("[autotel] request logger onEmit failed:", error);
-        });
-      }
-      emitted = true;
-      lastSnapshot = snapshot;
-      return snapshot;
-    },
-    fork(label, fn, forkOptions) {
-      const parentRequestId = activeContext.correlationId;
-      if (typeof parentRequestId !== "string" || parentRequestId.length === 0) {
-        throw new Error(
-          "[autotel] log.fork() requires the parent logger to have a correlationId. Ensure the request was created by autotel middleware."
-        );
-      }
-      const tracer = trace.getTracer("autotel.request-logger");
-      const lifecycle = forkOptions?.lifecycle;
-      void tracer.startActiveSpan(`request.fork:${label}`, (childSpan) => {
-        const childContext = {
-          ...createTraceContext(childSpan),
-          correlationId: crypto.randomUUID()
-        };
-        requestContextStore.run(childContext, () => {
-          const childLog = getRequestLogger(childContext);
-          childLog.set({
-            operation: label,
-            _parentCorrelationId: parentRequestId
-          });
-          lifecycle?.onChildEnter?.(childLog);
-          void Promise.resolve().then(() => fn()).then(() => {
-            childLog.emitNow();
-          }).catch((err) => {
-            const error = err instanceof Error ? err : new Error(String(err));
-            childLog.error(error);
-            childLog.emitNow();
-          }).finally(() => {
-            try {
-              lifecycle?.onChildExit?.(childLog);
-            } catch (hookError) {
-              console.warn(
-                "[autotel] fork onChildExit hook threw:",
-                hookError
-              );
-            }
-            childSpan.end();
-          });
-        });
-      });
-    }
-  };
+	console.warn(`[autotel] ${method} called after the wide event was emitted — ${detail} This data will not appear in observability. ${POST_EMIT_FORK_HINT}`);
+}
+function mergeInto$1(target, source) {
+	for (const key in source) {
+		const sourceVal = source[key];
+		if (sourceVal === void 0) continue;
+		const targetVal = target[key];
+		if (sourceVal !== null && typeof sourceVal === "object" && !Array.isArray(sourceVal) && targetVal !== null && typeof targetVal === "object" && !Array.isArray(targetVal)) mergeInto$1(targetVal, sourceVal);
+		else if (Array.isArray(targetVal) && Array.isArray(sourceVal)) target[key] = [...targetVal, ...sourceVal];
+		else target[key] = sourceVal;
+	}
+}
+const requestContextStore = new AsyncLocalStorage();
+function runWithRequestContext(ctx, fn) {
+	return requestContextStore.run(ctx, fn);
+}
+function resolveContext(ctx) {
+	if (ctx) return ctx;
+	const stored = requestContextStore.getStore();
+	if (stored) return stored;
+	const span = trace$1.getActiveSpan();
+	if (!span) throw new Error("[autotel] getRequestLogger() requires an active span or runWithRequestContext(). Wrap your handler with trace() or use runWithRequestContext().");
+	return createTraceContext(span);
+}
+function getRequestLogger(ctx, options) {
+	const activeContext = resolveContext(ctx);
+	let contextState = {};
+	let emitted = false;
+	let lastSnapshot = null;
+	const addLogEvent = (level, message, fields) => {
+		const attrs = fields ? flattenToAttributes(fields) : void 0;
+		emitCorrelatedEvent(activeContext, `log.${level}`, {
+			message,
+			...attrs ?? {}
+		});
+	};
+	const sealCheck = (method, keys) => {
+		if (emitted) warnPostEmit(method, `Keys dropped: ${keys.length ? keys.join(", ") : "(empty)"}.`);
+	};
+	return {
+		set(fields) {
+			sealCheck("log.set()", Object.keys(fields));
+			if (emitted) return;
+			mergeInto$1(contextState, fields);
+			activeContext.setAttributes(flattenToAttributes(fields));
+		},
+		info(message, fields) {
+			sealCheck("log.info()", fields ? ["message", ...Object.keys(fields).filter((k) => k !== "requestLogs")] : ["message"]);
+			if (emitted) return;
+			addLogEvent("info", message, fields);
+			if (fields) {
+				mergeInto$1(contextState, fields);
+				activeContext.setAttributes(flattenToAttributes(fields));
+			}
+		},
+		warn(message, fields) {
+			sealCheck("log.warn()", fields ? ["message", ...Object.keys(fields).filter((k) => k !== "requestLogs")] : ["message"]);
+			if (emitted) return;
+			addLogEvent("warn", message, fields);
+			activeContext.setAttribute("autotel.log.level", "warn");
+			if (fields) {
+				mergeInto$1(contextState, fields);
+				activeContext.setAttributes(flattenToAttributes(fields));
+			}
+		},
+		error(error, fields) {
+			sealCheck("log.error()", fields ? [...Object.keys(fields), "error"] : ["error"]);
+			if (emitted) return;
+			const err = typeof error === "string" ? new Error(error) : error;
+			recordStructuredError(activeContext, err);
+			addLogEvent("error", err.message, fields);
+			if (fields) {
+				mergeInto$1(contextState, fields);
+				activeContext.setAttributes(flattenToAttributes(fields));
+			}
+			activeContext.setAttribute("autotel.log.level", "error");
+		},
+		getContext() {
+			return { ...contextState };
+		},
+		emitNow(overrides) {
+			if (emitted) {
+				warnPostEmit("log.emitNow()", "Ignoring duplicate emit.");
+				return lastSnapshot;
+			}
+			const mergedContext = {
+				...contextState,
+				...overrides ?? {}
+			};
+			const flattened = flattenToAttributes(mergedContext);
+			activeContext.setAttributes(flattened);
+			const snapshot = {
+				timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+				traceId: activeContext.traceId,
+				spanId: activeContext.spanId,
+				correlationId: activeContext.correlationId,
+				context: mergedContext
+			};
+			emitCorrelatedEvent(activeContext, "log.emit.manual", { ...flattened });
+			if (options?.onEmit) Promise.resolve(options.onEmit(snapshot)).catch((error) => {
+				console.warn("[autotel] request logger onEmit failed:", error);
+			});
+			emitted = true;
+			lastSnapshot = snapshot;
+			return snapshot;
+		},
+		fork(label, fn, forkOptions) {
+			const parentRequestId = activeContext.correlationId;
+			if (typeof parentRequestId !== "string" || parentRequestId.length === 0) throw new Error("[autotel] log.fork() requires the parent logger to have a correlationId. Ensure the request was created by autotel middleware.");
+			const tracer = trace$1.getTracer("autotel.request-logger");
+			const lifecycle = forkOptions?.lifecycle;
+			tracer.startActiveSpan(`request.fork:${label}`, (childSpan) => {
+				const childContext = {
+					...createTraceContext(childSpan),
+					correlationId: crypto.randomUUID()
+				};
+				requestContextStore.run(childContext, () => {
+					const childLog = getRequestLogger(childContext);
+					childLog.set({
+						operation: label,
+						_parentCorrelationId: parentRequestId
+					});
+					lifecycle?.onChildEnter?.(childLog);
+					Promise.resolve().then(() => fn()).then(() => {
+						childLog.emitNow();
+					}).catch((err) => {
+						const error = err instanceof Error ? err : new Error(String(err));
+						childLog.error(error);
+						childLog.emitNow();
+					}).finally(() => {
+						try {
+							lifecycle?.onChildExit?.(childLog);
+						} catch (hookError) {
+							console.warn("[autotel] fork onChildExit hook threw:", hookError);
+						}
+						childSpan.end();
+					});
+				});
+			});
+		}
+	};
+}
+/**
+* Returns `true` when a request-logger context can be resolved without throwing —
+* i.e. an explicit `ctx` was provided, a `runWithRequestContext()` scope is active,
+* or there is an active OpenTelemetry span.
+*
+* Use this to branch on observability availability instead of wrapping
+* {@link getRequestLogger} in try/catch.
+*/
+function hasRequestContext(ctx) {
+	if (ctx) return true;
+	if (requestContextStore.getStore()) return true;
+	return trace$1.getActiveSpan() != null;
+}
+/**
+* Like {@link getRequestLogger}, but returns `null` instead of throwing when no
+* request context is available. Intended for best-effort instrumentation where a
+* missing telemetry context must never crash business logic.
+*/
+function getRequestLoggerSafe(ctx, options) {
+	if (!hasRequestContext(ctx)) return null;
+	return getRequestLogger(ctx, options);
+}
+/**
+* A no-op {@link RequestLogger} whose methods do nothing. Used as a fallback by
+* best-effort instrumentation so wrapped handlers can run un-instrumented without
+* branching on logger presence.
+*/
+function createNoopRequestLogger() {
+	const snapshot = () => ({
+		timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+		traceId: "",
+		spanId: "",
+		correlationId: "",
+		context: {}
+	});
+	return {
+		set() {},
+		info() {},
+		warn() {},
+		error() {},
+		getContext() {
+			return {};
+		},
+		emitNow() {
+			return snapshot();
+		},
+		fork(_label, fn) {
+			Promise.resolve().then(() => fn());
+		}
+	};
 }
 
-// src/error-catalog.ts
-var catalogCodeKey = /* @__PURE__ */ Symbol.for("autotel.catalog.code");
+//#endregion
+//#region src/error-catalog.ts
+/**
+* Typed error and audit catalogs.
+*
+* Group related errors into one catalog and get a refactor-safe builder per
+* code, with autocomplete at every call site and typed message parameters.
+*
+* @example
+* ```typescript
+* import { defineErrorCatalog } from 'autotel';
+*
+* export const billing = defineErrorCatalog('billing', {
+*   PAYMENT_DECLINED: {
+*     status: 402,
+*     message: 'Card declined',
+*     why: 'The issuer rejected the charge',
+*     fix: 'Try a different payment method',
+*   },
+*   INSUFFICIENT_FUNDS: {
+*     status: 402,
+*     message: ({ available, required }: { available: number; required: number }) =>
+*       `Insufficient funds: $${available} of $${required}`,
+*   },
+* });
+*
+* throw billing.PAYMENT_DECLINED({ cause: stripeError });
+* throw billing.INSUFFICIENT_FUNDS({ available: 5, required: 100 });
+*
+* // In a catch block — refactor-safe, no magic strings:
+* if (billing.PAYMENT_DECLINED.match(err)) { ... }
+* ```
+*/
+const catalogCodeKey = Symbol.for("autotel.catalog.code");
 function readCatalogCode(error) {
-  if (error === null || typeof error !== "object") return void 0;
-  return error[catalogCodeKey];
+	if (error === null || typeof error !== "object") return void 0;
+	return error[catalogCodeKey];
 }
+/** True when `error` was produced by any autotel error catalog. */
 function isCatalogError(error) {
-  return readCatalogCode(error) !== void 0;
+	return readCatalogCode(error) !== void 0;
 }
+/** Returns the catalog code of `error`, or `undefined` if it has none. */
 function getCatalogCode(error) {
-  return readCatalogCode(error);
+	return readCatalogCode(error);
 }
+/**
+* Define a typed error catalog. Returns an object whose keys are error
+* builders. Each builder produces a {@link StructuredError} carrying the
+* entry's message, status, code, why, fix, and link.
+*/
 function defineErrorCatalog(namespace, entries) {
-  const catalog = {};
-  for (const [key, entry] of Object.entries(entries)) {
-    const code = entry.code ?? `${namespace}.${key}`;
-    const usesParams = typeof entry.message === "function" || typeof entry.why === "function";
-    const builder = ((paramsOrOptions, maybeOptions) => {
-      const params = usesParams ? paramsOrOptions : void 0;
-      const options = usesParams ? maybeOptions : paramsOrOptions;
-      const message = typeof entry.message === "function" ? entry.message(params) : entry.message;
-      const why = typeof entry.why === "function" ? entry.why(params) : entry.why;
-      const error = createStructuredError({
-        message,
-        name: entry.name ?? key,
-        code,
-        ...entry.status === void 0 ? {} : { status: entry.status },
-        ...why === void 0 ? {} : { why },
-        ...entry.fix === void 0 ? {} : { fix: entry.fix },
-        ...entry.link === void 0 ? {} : { link: entry.link },
-        ...options?.cause === void 0 ? {} : { cause: options.cause },
-        ...options?.details === void 0 ? {} : { details: options.details },
-        ...options?.internal === void 0 ? {} : { internal: options.internal }
-      });
-      Object.defineProperty(error, catalogCodeKey, {
-        value: code,
-        enumerable: false,
-        writable: false,
-        configurable: true
-      });
-      return error;
-    });
-    Object.defineProperty(builder, "code", {
-      value: code,
-      enumerable: true
-    });
-    Object.defineProperty(builder, "match", {
-      value: (error) => readCatalogCode(error) === code,
-      enumerable: false
-    });
-    catalog[key] = builder;
-  }
-  return Object.freeze(catalog);
-}
+	const catalog = {};
+	for (const [key, entry] of Object.entries(entries)) {
+		const code = entry.code ?? `${namespace}.${key}`;
+		const usesParams = typeof entry.message === "function" || typeof entry.why === "function";
+		const builder = ((paramsOrOptions, maybeOptions) => {
+			const params = usesParams ? paramsOrOptions : void 0;
+			const options = usesParams ? maybeOptions : paramsOrOptions;
+			const message = typeof entry.message === "function" ? entry.message(params) : entry.message;
+			const why = typeof entry.why === "function" ? entry.why(params) : entry.why;
+			const error = createStructuredError({
+				message,
+				name: entry.name ?? key,
+				code,
+				...entry.status === void 0 ? {} : { status: entry.status },
+				...why === void 0 ? {} : { why },
+				...entry.fix === void 0 ? {} : { fix: entry.fix },
+				...entry.link === void 0 ? {} : { link: entry.link },
+				...options?.cause === void 0 ? {} : { cause: options.cause },
+				...options?.details === void 0 ? {} : { details: options.details },
+				...options?.internal === void 0 ? {} : { internal: options.internal }
+			});
+			Object.defineProperty(error, catalogCodeKey, {
+				value: code,
+				enumerable: false,
+				writable: false,
+				configurable: true
+			});
+			return error;
+		});
+		Object.defineProperty(builder, "code", {
+			value: code,
+			enumerable: true
+		});
+		Object.defineProperty(builder, "match", {
+			value: (error) => readCatalogCode(error) === code,
+			enumerable: false
+		});
+		catalog[key] = builder;
+	}
+	return Object.freeze(catalog);
+}
+/**
+* Define a typed audit catalog. Returns typed action descriptors you can pass
+* to `track()` or audit helpers without scattering magic strings.
+*/
 function defineAuditCatalog(namespace, entries) {
-  const catalog = {};
-  for (const [key, entry] of Object.entries(entries)) {
-    const action = entry.action ?? `${namespace}.${key}`;
-    const severity = entry.severity ?? "info";
-    const descriptor = ((params) => {
-      const message = typeof entry.message === "function" ? entry.message(params) : entry.message;
-      return Object.freeze({
-        action,
-        severity,
-        ...message === void 0 ? {} : { message }
-      });
-    });
-    Object.defineProperty(descriptor, "action", {
-      value: action,
-      enumerable: true
-    });
-    Object.defineProperty(descriptor, "severity", {
-      value: severity,
-      enumerable: true
-    });
-    catalog[key] = descriptor;
-  }
-  return Object.freeze(catalog);
+	const catalog = {};
+	for (const [key, entry] of Object.entries(entries)) {
+		const action = entry.action ?? `${namespace}.${key}`;
+		const severity = entry.severity ?? "info";
+		const descriptor = ((params) => {
+			const message = typeof entry.message === "function" ? entry.message(params) : entry.message;
+			return Object.freeze({
+				action,
+				severity,
+				...message === void 0 ? {} : { message }
+			});
+		});
+		Object.defineProperty(descriptor, "action", {
+			value: action,
+			enumerable: true
+		});
+		Object.defineProperty(descriptor, "severity", {
+			value: severity,
+			enumerable: true
+		});
+		catalog[key] = descriptor;
+	}
+	return Object.freeze(catalog);
 }
 
-// src/drain-toolkit.ts
-var DEFAULT_TIMEOUT_MS = 5e3;
-var DEFAULT_RETRIES = 2;
+//#endregion
+//#region src/drain-toolkit.ts
+const DEFAULT_TIMEOUT_MS = 5e3;
+const DEFAULT_RETRIES = 2;
 function delay(ms) {
-  return new Promise((resolve) => {
-    const t = setTimeout(resolve, ms);
-    t.unref?.();
-  });
+	return new Promise((resolve) => {
+		setTimeout(resolve, ms).unref?.();
+	});
 }
 async function postWithRetry(options) {
-  const { name, request: request2, timeoutMs, retries } = options;
-  const attempts = Math.max(1, retries);
-  let lastError;
-  for (let attempt = 1; attempt <= attempts; attempt++) {
-    const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), timeoutMs);
-    timeout.unref?.();
-    try {
-      const response = await fetch(request2.url, {
-        method: "POST",
-        headers: request2.headers,
-        body: request2.body,
-        signal: controller.signal
-      });
-      if (!response.ok) {
-        throw new Error(
-          `[autotel/${name}] HTTP ${response.status} draining ${request2.url}`
-        );
-      }
-      return;
-    } catch (error) {
-      lastError = error;
-      if (attempt < attempts) {
-        await delay(100 * attempt);
-      }
-    } finally {
-      clearTimeout(timeout);
-    }
-  }
-  throw lastError;
+	const { name, request, timeoutMs, retries } = options;
+	const attempts = Math.max(1, retries);
+	let lastError;
+	for (let attempt = 1; attempt <= attempts; attempt++) {
+		const controller = new AbortController();
+		const timeout = setTimeout(() => controller.abort(), timeoutMs);
+		timeout.unref?.();
+		try {
+			const response = await fetch(request.url, {
+				method: "POST",
+				headers: request.headers,
+				body: request.body,
+				signal: controller.signal
+			});
+			if (!response.ok) throw new Error(`[autotel/${name}] HTTP ${response.status} draining ${request.url}`);
+			return;
+		} catch (error) {
+			lastError = error;
+			if (attempt < attempts) await delay(100 * attempt);
+		} finally {
+			clearTimeout(timeout);
+		}
+	}
+	throw lastError;
 }
 function defineDrain(options) {
-  return async (ctx2) => {
-    const contexts = Array.isArray(ctx2) ? ctx2 : [ctx2];
-    if (contexts.length === 0) return;
-    const config = await options.resolve();
-    if (!config) return;
-    const payloads = options.transform ? options.transform(contexts) : contexts;
-    if (payloads.length === 0) return;
-    try {
-      await options.send(payloads, config);
-    } catch (error) {
-      console.error(`[autotel/${options.name}] drain failed:`, error);
-    }
-  };
+	return async (ctx) => {
+		const contexts = Array.isArray(ctx) ? ctx : [ctx];
+		if (contexts.length === 0) return;
+		const config = await options.resolve();
+		if (!config) return;
+		const payloads = options.transform ? options.transform(contexts) : contexts;
+		if (payloads.length === 0) return;
+		try {
+			await options.send(payloads, config);
+		} catch (error) {
+			console.error(`[autotel/${options.name}] drain failed:`, error);
+		}
+	};
 }
 function defineHttpDrain(options) {
-  return defineDrain({
-    name: options.name,
-    resolve: options.resolve,
-    transform: options.transform,
-    send: async (payloads, config) => {
-      const request2 = options.encode(payloads, config);
-      if (!request2) return;
-      const timeoutMs = options.resolveTimeoutMs?.(config) ?? options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-      const retries = options.resolveRetries?.(config) ?? options.retries ?? DEFAULT_RETRIES;
-      await postWithRetry({
-        name: options.name,
-        request: request2,
-        timeoutMs,
-        retries
-      });
-    }
-  });
+	return defineDrain({
+		name: options.name,
+		resolve: options.resolve,
+		transform: options.transform,
+		send: async (payloads, config) => {
+			const request = options.encode(payloads, config);
+			if (!request) return;
+			const timeoutMs = options.resolveTimeoutMs?.(config) ?? options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+			const retries = options.resolveRetries?.(config) ?? options.retries ?? DEFAULT_RETRIES;
+			await postWithRetry({
+				name: options.name,
+				request,
+				timeoutMs,
+				retries
+			});
+		}
+	});
 }
 
-// src/enricher-toolkit.ts
+//#endregion
+//#region src/enricher-toolkit.ts
 function isPlainObject(value) {
-  return value !== null && typeof value === "object" && !Array.isArray(value);
-}
-function mergeInto2(target, source) {
-  for (const key in source) {
-    const sourceVal = source[key];
-    if (sourceVal === void 0) continue;
-    const targetVal = target[key];
-    if (isPlainObject(sourceVal) && isPlainObject(targetVal)) {
-      mergeInto2(targetVal, sourceVal);
-    } else {
-      target[key] = sourceVal;
-    }
-  }
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function mergeInto(target, source) {
+	for (const key in source) {
+		const sourceVal = source[key];
+		if (sourceVal === void 0) continue;
+		const targetVal = target[key];
+		if (isPlainObject(sourceVal) && isPlainObject(targetVal)) mergeInto(targetVal, sourceVal);
+		else target[key] = sourceVal;
+	}
 }
 function defineEnricher(def, options = {}) {
-  return (ctx2) => {
-    let computed;
-    try {
-      computed = def.compute(ctx2);
-    } catch (error) {
-      console.error(`[autotel/${def.name}] enrich failed:`, error);
-      return;
-    }
-    if (!computed) return;
-    if (options.overwrite || !isPlainObject(ctx2.event[def.field])) {
-      ctx2.event[def.field] = computed;
-      return;
-    }
-    mergeInto2(
-      ctx2.event[def.field],
-      computed
-    );
-  };
-}
-var GEN_AI_DURATION_BUCKETS_SECONDS = Object.freeze(
-  [0.01, 0.05, 0.1, 0.25, 0.5, 1, 2, 5, 10, 20, 30, 60, 120, 300]
-);
-var GEN_AI_TOKEN_USAGE_BUCKETS = Object.freeze([
-  1,
-  4,
-  16,
-  64,
-  256,
-  1024,
-  4096,
-  16384,
-  65536,
-  262144,
-  1048576,
-  4194304
+	return (ctx) => {
+		let computed;
+		try {
+			computed = def.compute(ctx);
+		} catch (error) {
+			console.error(`[autotel/${def.name}] enrich failed:`, error);
+			return;
+		}
+		if (!computed) return;
+		if (options.overwrite || !isPlainObject(ctx.event[def.field])) {
+			ctx.event[def.field] = computed;
+			return;
+		}
+		mergeInto(ctx.event[def.field], computed);
+	};
+}
+
+//#endregion
+//#region src/gen-ai-metrics.ts
+/**
+* LLM-tuned histogram buckets.
+*
+* Default OpenTelemetry histogram buckets target HTTP latency (0ms–10s)
+* and small counter values. LLM workloads have very different shapes:
+*
+*   - **Duration**: single-token prompts can be fast (50ms), long
+*     generations and reasoning models can run for minutes. Default buckets
+*     crush everything above 10s into one bucket.
+*   - **Token usage**: heavily right-skewed. A single request can range
+*     from tens of tokens to the million-token context windows.
+*   - **Cost (USD)**: per-request values are tiny (fractions of a cent),
+*     so linear buckets waste resolution at the low end.
+*
+* This module exposes empirically-chosen bucket arrays and a View helper
+* so users can apply them to their `MeterProvider` without knowing the
+* exact instrument names emitted by OpenAI/Anthropic/Traceloop plugins.
+*
+* @example
+* ```typescript
+* import { NodeSDK } from '@opentelemetry/sdk-node';
+* import { genAiMetricViews } from 'autotel';
+*
+* const sdk = new NodeSDK({
+*   serviceName: 'my-agent',
+*   views: [...genAiMetricViews()],
+* });
+* sdk.start();
+* ```
+*/
+/**
+* Duration buckets for LLM operations, in **seconds**. Covers fast
+* completions (50ms) through long-running reasoning jobs (5 min).
+*
+* Aligns with the OTel GenAI semantic conventions' published advice for
+* `gen_ai.client.operation.duration`.
+*/
+const GEN_AI_DURATION_BUCKETS_SECONDS = Object.freeze([
+	.01,
+	.05,
+	.1,
+	.25,
+	.5,
+	1,
+	2,
+	5,
+	10,
+	20,
+	30,
+	60,
+	120,
+	300
+]);
+/**
+* Token-count buckets for prompt, completion, and total token histograms.
+* Ranges from tiny prompts to million-token context windows.
+*
+* Aligns with the OTel GenAI semantic conventions' published advice for
+* `gen_ai.client.token.usage`.
+*/
+const GEN_AI_TOKEN_USAGE_BUCKETS = Object.freeze([
+	1,
+	4,
+	16,
+	64,
+	256,
+	1024,
+	4096,
+	16384,
+	65536,
+	262144,
+	1048576,
+	4194304
 ]);
-var GEN_AI_COST_USD_BUCKETS = Object.freeze([
-  1e-5,
-  1e-4,
-  1e-3,
-  5e-3,
-  0.01,
-  0.05,
-  0.1,
-  0.5,
-  1,
-  5,
-  10,
-  50
+/**
+* USD cost buckets. Sub-cent resolution at the low end (fractions of a
+* cent per small call) up to tens of dollars (batch jobs, Opus/o1 runs).
+*/
+const GEN_AI_COST_USD_BUCKETS = Object.freeze([
+	1e-5,
+	1e-4,
+	.001,
+	.005,
+	.01,
+	.05,
+	.1,
+	.5,
+	1,
+	5,
+	10,
+	50
 ]);
+/**
+* Instrument-level advice object for `createHistogram(name, advice)`.
+* Use when you control the instrument creation (e.g. custom business
+* LLM metrics); `genAiMetricViews()` is better when the metric comes
+* from a third-party plugin.
+*/
 function llmHistogramAdvice(kind) {
-  const boundaries = kind === "duration" ? GEN_AI_DURATION_BUCKETS_SECONDS : kind === "tokens" ? GEN_AI_TOKEN_USAGE_BUCKETS : GEN_AI_COST_USD_BUCKETS;
-  return { advice: { explicitBucketBoundaries: [...boundaries] } };
-}
+	return { advice: { explicitBucketBoundaries: [...kind === "duration" ? GEN_AI_DURATION_BUCKETS_SECONDS : kind === "tokens" ? GEN_AI_TOKEN_USAGE_BUCKETS : GEN_AI_COST_USD_BUCKETS] } };
+}
+/**
+* Returns `View`s that re-bucket the standard OTel GenAI histograms. Pass
+* the result to your `MeterProvider`'s `views` option.
+*
+* Matches instrument names emitted by:
+* - OpenTelemetry GenAI autoinstrumentation
+* - OpenInference / OpenLLMetry (traceloop)
+* - Arize Phoenix, LangSmith, etc. that follow the OTel spec
+*
+* Add more instrument patterns via the `extra` argument if you emit
+* custom LLM metrics.
+*/
 function genAiMetricViews(extra = []) {
-  const defaults = [
-    { instrumentName: "gen_ai.client.operation.duration", kind: "duration" },
-    { instrumentName: "gen_ai.client.token.usage", kind: "tokens" },
-    // Autotel-emitted cost metric. No-op if you don't emit it.
-    { instrumentName: "gen_ai.client.cost.usd", kind: "cost" }
-  ];
-  return [...defaults, ...extra].map(
-    ({ instrumentName, kind }) => ({
-      instrumentName,
-      aggregation: {
-        type: AggregationType.EXPLICIT_BUCKET_HISTOGRAM,
-        options: {
-          boundaries: kind === "duration" ? [...GEN_AI_DURATION_BUCKETS_SECONDS] : kind === "tokens" ? [...GEN_AI_TOKEN_USAGE_BUCKETS] : [...GEN_AI_COST_USD_BUCKETS]
-        }
-      }
-    })
-  );
+	return [...[
+		{
+			instrumentName: "gen_ai.client.operation.duration",
+			kind: "duration"
+		},
+		{
+			instrumentName: "gen_ai.client.token.usage",
+			kind: "tokens"
+		},
+		{
+			instrumentName: "gen_ai.client.cost.usd",
+			kind: "cost"
+		}
+	], ...extra].map(({ instrumentName, kind }) => ({
+		instrumentName,
+		aggregation: {
+			type: AggregationType.EXPLICIT_BUCKET_HISTOGRAM,
+			options: { boundaries: kind === "duration" ? [...GEN_AI_DURATION_BUCKETS_SECONDS] : kind === "tokens" ? [...GEN_AI_TOKEN_USAGE_BUCKETS] : [...GEN_AI_COST_USD_BUCKETS] }
+		}
+	}));
 }
 
-// src/gen-ai-events.ts
-function recordPromptSent(ctx2, event = {}) {
-  emitCorrelatedEvent(ctx2, "gen_ai.prompt.sent", buildPromptSentAttrs(event));
-}
-function recordResponseReceived(ctx2, event = {}) {
-  emitCorrelatedEvent(
-    ctx2,
-    "gen_ai.response.received",
-    buildResponseAttrs(event)
-  );
-}
-function recordRetry(ctx2, event) {
-  emitCorrelatedEvent(ctx2, "gen_ai.retry", buildRetryAttrs(event));
-}
-function recordToolCall(ctx2, event) {
-  emitCorrelatedEvent(ctx2, "gen_ai.tool.call", buildToolCallAttrs(event));
-}
-function recordStreamFirstToken(ctx2, event = {}) {
-  emitCorrelatedEvent(
-    ctx2,
-    "gen_ai.stream.first_token",
-    buildStreamFirstTokenAttrs(event)
-  );
+//#endregion
+//#region src/gen-ai-events.ts
+/**
+* Record that a prompt was dispatched to the provider. Typically called
+* before `await provider.chat.completions.create(...)`.
+*/
+function recordPromptSent(ctx, event = {}) {
+	emitCorrelatedEvent(ctx, "gen_ai.prompt.sent", buildPromptSentAttrs(event));
+}
+/**
+* Record a successful provider response. Call after the response arrives
+* (for non-streaming) or after the stream completes.
+*/
+function recordResponseReceived(ctx, event = {}) {
+	emitCorrelatedEvent(ctx, "gen_ai.response.received", buildResponseAttrs(event));
+}
+/**
+* Record a retry attempt on an LLM call. Call *before* sleeping for
+* `delayMs` so the event timestamp accurately marks when the retry
+* decision was made.
+*/
+function recordRetry(ctx, event) {
+	emitCorrelatedEvent(ctx, "gen_ai.retry", buildRetryAttrs(event));
+}
+/**
+* Record a tool / function call made in the course of an agent step.
+* Emits an event rather than a child span because many frameworks fire
+* several tool calls within a single provider response.
+*/
+function recordToolCall(ctx, event) {
+	emitCorrelatedEvent(ctx, "gen_ai.tool.call", buildToolCallAttrs(event));
+}
+/**
+* Record the time-to-first-token for a streaming response. Pair with
+* `recordResponseReceived` at the end so the span carries both the TTFT
+* marker and the final usage numbers.
+*/
+function recordStreamFirstToken(ctx, event = {}) {
+	emitCorrelatedEvent(ctx, "gen_ai.stream.first_token", buildStreamFirstTokenAttrs(event));
 }
 function buildPromptSentAttrs(event) {
-  const attrs2 = {};
-  if (event.model) attrs2["gen_ai.request.model"] = event.model;
-  if (event.promptTokens !== void 0)
-    attrs2["gen_ai.usage.input_tokens"] = event.promptTokens;
-  if (event.messageCount !== void 0)
-    attrs2["gen_ai.request.message_count"] = event.messageCount;
-  if (event.operation) attrs2["gen_ai.operation.name"] = event.operation;
-  return attrs2;
+	const attrs = {};
+	if (event.model) attrs["gen_ai.request.model"] = event.model;
+	if (event.promptTokens !== void 0) attrs["gen_ai.usage.input_tokens"] = event.promptTokens;
+	if (event.messageCount !== void 0) attrs["gen_ai.request.message_count"] = event.messageCount;
+	if (event.operation) attrs["gen_ai.operation.name"] = event.operation;
+	return attrs;
 }
 function buildResponseAttrs(event) {
-  const attrs2 = {};
-  if (event.model) attrs2["gen_ai.response.model"] = event.model;
-  if (event.promptTokens !== void 0)
-    attrs2["gen_ai.usage.input_tokens"] = event.promptTokens;
-  if (event.completionTokens !== void 0)
-    attrs2["gen_ai.usage.output_tokens"] = event.completionTokens;
-  if (event.totalTokens !== void 0)
-    attrs2["gen_ai.usage.total_tokens"] = event.totalTokens;
-  if (event.finishReasons && event.finishReasons.length > 0) {
-    attrs2["gen_ai.response.finish_reasons"] = event.finishReasons.join(",");
-  }
-  return attrs2;
+	const attrs = {};
+	if (event.model) attrs["gen_ai.response.model"] = event.model;
+	if (event.promptTokens !== void 0) attrs["gen_ai.usage.input_tokens"] = event.promptTokens;
+	if (event.completionTokens !== void 0) attrs["gen_ai.usage.output_tokens"] = event.completionTokens;
+	if (event.totalTokens !== void 0) attrs["gen_ai.usage.total_tokens"] = event.totalTokens;
+	if (event.finishReasons && event.finishReasons.length > 0) attrs["gen_ai.response.finish_reasons"] = event.finishReasons.join(",");
+	return attrs;
 }
 function buildRetryAttrs(event) {
-  const attrs2 = { "retry.attempt": event.attempt };
-  if (event.reason) attrs2["retry.reason"] = event.reason;
-  if (event.delayMs !== void 0) attrs2["retry.delay_ms"] = event.delayMs;
-  if (event.statusCode !== void 0)
-    attrs2["http.response.status_code"] = event.statusCode;
-  return attrs2;
+	const attrs = { "retry.attempt": event.attempt };
+	if (event.reason) attrs["retry.reason"] = event.reason;
+	if (event.delayMs !== void 0) attrs["retry.delay_ms"] = event.delayMs;
+	if (event.statusCode !== void 0) attrs["http.response.status_code"] = event.statusCode;
+	return attrs;
 }
 function buildToolCallAttrs(event) {
-  const attrs2 = { "gen_ai.tool.name": event.toolName };
-  if (event.toolCallId) attrs2["gen_ai.tool.call.id"] = event.toolCallId;
-  if (event.arguments) attrs2["gen_ai.tool.arguments"] = event.arguments;
-  return attrs2;
+	const attrs = { "gen_ai.tool.name": event.toolName };
+	if (event.toolCallId) attrs["gen_ai.tool.call.id"] = event.toolCallId;
+	if (event.arguments) attrs["gen_ai.tool.arguments"] = event.arguments;
+	return attrs;
 }
 function buildStreamFirstTokenAttrs(event) {
-  const attrs2 = {};
-  if (event.tokensSoFar !== void 0)
-    attrs2["gen_ai.stream.tokens_so_far"] = event.tokensSoFar;
-  return attrs2;
+	const attrs = {};
+	if (event.tokensSoFar !== void 0) attrs["gen_ai.stream.tokens_so_far"] = event.tokensSoFar;
+	return attrs;
 }
 
-// src/gen-ai-cost.ts
-var GEN_AI_COST_ATTRIBUTE = "gen_ai.usage.cost.usd";
-var MODEL_PRICING = {
-  // OpenAI
-  "gpt-4o": { inputPer1M: 2.5, outputPer1M: 10 },
-  "gpt-4o-mini": { inputPer1M: 0.15, outputPer1M: 0.6 },
-  "gpt-4.1": { inputPer1M: 2, outputPer1M: 8 },
-  "gpt-4.1-mini": { inputPer1M: 0.4, outputPer1M: 1.6 },
-  "gpt-4.1-nano": { inputPer1M: 0.1, outputPer1M: 0.4 },
-  "o3-mini": { inputPer1M: 1.1, outputPer1M: 4.4 },
-  // Anthropic Claude
-  "claude-opus-4": { inputPer1M: 15, outputPer1M: 75 },
-  "claude-sonnet-4": { inputPer1M: 3, outputPer1M: 15 },
-  "claude-3-5-sonnet": { inputPer1M: 3, outputPer1M: 15 },
-  "claude-3-5-haiku": { inputPer1M: 0.8, outputPer1M: 4 },
-  "claude-3-opus": { inputPer1M: 15, outputPer1M: 75 },
-  "claude-3-haiku": { inputPer1M: 0.25, outputPer1M: 1.25 },
-  // Google Gemini
-  "gemini-1.5-pro": { inputPer1M: 1.25, outputPer1M: 5 },
-  "gemini-1.5-flash": { inputPer1M: 0.075, outputPer1M: 0.3 },
-  "gemini-2.0-flash": { inputPer1M: 0.1, outputPer1M: 0.4 }
+//#endregion
+//#region src/gen-ai-cost.ts
+/** Span attribute key autotel sets for an estimated call cost. */
+const GEN_AI_COST_ATTRIBUTE = "gen_ai.usage.cost.usd";
+/**
+* Approximate public list prices (USD per 1M tokens) at the time of writing.
+* Prices change; treat these as convenience defaults, not a billing source of
+* truth. Override per call via `options.pricing` or mutate this table at init.
+* Matching is exact first, then by longest key prefix, so versioned model ids
+* (`claude-sonnet-4-6-20251101`) resolve to a base entry (`claude-sonnet-4-6`).
+*/
+const MODEL_PRICING = {
+	"gpt-4o": {
+		inputPer1M: 2.5,
+		outputPer1M: 10
+	},
+	"gpt-4o-mini": {
+		inputPer1M: .15,
+		outputPer1M: .6
+	},
+	"gpt-4.1": {
+		inputPer1M: 2,
+		outputPer1M: 8
+	},
+	"gpt-4.1-mini": {
+		inputPer1M: .4,
+		outputPer1M: 1.6
+	},
+	"gpt-4.1-nano": {
+		inputPer1M: .1,
+		outputPer1M: .4
+	},
+	"o3-mini": {
+		inputPer1M: 1.1,
+		outputPer1M: 4.4
+	},
+	"claude-opus-4": {
+		inputPer1M: 15,
+		outputPer1M: 75
+	},
+	"claude-sonnet-4": {
+		inputPer1M: 3,
+		outputPer1M: 15
+	},
+	"claude-3-5-sonnet": {
+		inputPer1M: 3,
+		outputPer1M: 15
+	},
+	"claude-3-5-haiku": {
+		inputPer1M: .8,
+		outputPer1M: 4
+	},
+	"claude-3-opus": {
+		inputPer1M: 15,
+		outputPer1M: 75
+	},
+	"claude-3-haiku": {
+		inputPer1M: .25,
+		outputPer1M: 1.25
+	},
+	"gemini-1.5-pro": {
+		inputPer1M: 1.25,
+		outputPer1M: 5
+	},
+	"gemini-1.5-flash": {
+		inputPer1M: .075,
+		outputPer1M: .3
+	},
+	"gemini-2.0-flash": {
+		inputPer1M: .1,
+		outputPer1M: .4
+	}
 };
 function resolvePricing(table, model) {
-  const exact = table[model];
-  if (exact) return exact;
-  let best;
-  let bestLength = 0;
-  for (const key of Object.keys(table)) {
-    if (model.startsWith(key) && key.length > bestLength) {
-      best = table[key];
-      bestLength = key.length;
-    }
-  }
-  return best;
+	const exact = table[model];
+	if (exact) return exact;
+	let best;
+	let bestLength = 0;
+	for (const key of Object.keys(table)) if (model.startsWith(key) && key.length > bestLength) {
+		best = table[key];
+		bestLength = key.length;
+	}
+	return best;
 }
 function round(value) {
-  return Math.round(value * 1e6) / 1e6;
+	return Math.round(value * 1e6) / 1e6;
 }
+/**
+* Estimate the USD cost of an LLM call. Returns `undefined` when the model has
+* no known pricing (supply one via `options.pricing`).
+*/
 function estimateLLMCost(model, usage, options) {
-  const table = options?.pricing ? { ...MODEL_PRICING, ...options.pricing } : MODEL_PRICING;
-  const price = resolvePricing(table, model);
-  if (!price) return void 0;
-  const cachedInput = usage.cachedInputTokens ?? 0;
-  const billedInput = Math.max(0, (usage.inputTokens ?? 0) - cachedInput);
-  const output = usage.outputTokens ?? 0;
-  const cachedRate = price.cachedInputPer1M ?? price.inputPer1M;
-  const cost = billedInput / 1e6 * price.inputPer1M + cachedInput / 1e6 * cachedRate + output / 1e6 * price.outputPer1M;
-  return round(cost);
-}
-function recordLLMCost(ctx2, model, usage, options) {
-  const cost = estimateLLMCost(model, usage, options);
-  if (cost !== void 0) {
-    ctx2.setAttribute(GEN_AI_COST_ATTRIBUTE, cost);
-  }
-  return cost;
+	const price = resolvePricing(options?.pricing ? {
+		...MODEL_PRICING,
+		...options.pricing
+	} : MODEL_PRICING, model);
+	if (!price) return void 0;
+	const cachedInput = usage.cachedInputTokens ?? 0;
+	const billedInput = Math.max(0, (usage.inputTokens ?? 0) - cachedInput);
+	const output = usage.outputTokens ?? 0;
+	const cachedRate = price.cachedInputPer1M ?? price.inputPer1M;
+	return round(billedInput / 1e6 * price.inputPer1M + cachedInput / 1e6 * cachedRate + output / 1e6 * price.outputPer1M);
+}
+/**
+* Estimate cost and record it on `ctx` as the `gen_ai.usage.cost.usd` span
+* attribute. Returns the estimated cost, or `undefined` when the model is
+* unknown (in which case no attribute is set).
+*/
+function recordLLMCost(ctx, model, usage, options) {
+	const cost = estimateLLMCost(model, usage, options);
+	if (cost !== void 0) ctx.setAttribute(GEN_AI_COST_ATTRIBUTE, cost);
+	return cost;
 }
 
-export { GEN_AI_COST_ATTRIBUTE, GEN_AI_COST_USD_BUCKETS, GEN_AI_DURATION_BUCKETS_SECONDS, GEN_AI_TOKEN_USAGE_BUCKETS, MODEL_PRICING, defineAuditCatalog, defineDrain, defineEnricher, defineErrorCatalog, defineEvent, defineHttpDrain, estimateLLMCost, flush, genAiMetricViews, getCatalogCode, getRequestLogger, isCatalogError, llmHistogramAdvice, recordLLMCost, recordPromptSent, recordResponseReceived, recordRetry, recordStreamFirstToken, recordToolCall, runWithRequestContext, shutdown, trace2 as trace };
-//# sourceMappingURL=index.js.map
+//#endregion
+export { AUTOTEL_SAMPLING_TAIL_EVALUATED, AUTOTEL_SAMPLING_TAIL_KEEP, AdaptiveSampler, AlwaysSampler, AttributeRedactingProcessor, BaggageSpanProcessor, BusinessBaggage, CORRELATION_ID_BAGGAGE_KEY, Event, FilteringSpanProcessor, GEN_AI_COST_ATTRIBUTE, GEN_AI_COST_USD_BUCKETS, GEN_AI_DURATION_BUCKETS_SECONDS, GEN_AI_TOKEN_USAGE_BUCKETS, HTTPAttributes, MODEL_PRICING, Metric, NORMALIZER_PATTERNS, NORMALIZER_PRESETS, NeverSampler, REDACTOR_PATTERNS, REDACTOR_PRESETS, ROOT_CONTEXT, RandomSampler, ServiceAttributes, SpanKind, SpanNameNormalizingProcessor, SpanStatusCode, URLAttributes, UserIdSampler, attrs, autoRedactPII, builtinPatterns, context, createAttributeRedactor, createCounter, createDeterministicTraceId, createDrainPipeline, createHistogram, createLinkFromHeaders, createNoopRequestLogger, createObservableGauge, createRedactedSpan, createSafeBaggageSchema, createStringRedactor, createStructuredError, createUpDownCounter, ctx, dbClient, defineAuditCatalog, defineBaggageSchema, defineDrain, defineEnricher, defineErrorCatalog, defineEvent, defineHttpDrain, enrichWithTraceContext, estimateLLMCost, extractLinksFromBatch, finalizeSpan, flattenMetadata, flattenToAttributes, flush, formatDuration, genAiMetricViews, generateCorrelationId, getActiveContext, getActiveSpan, getAutotelTracer, getAutotelTracerProvider, getCatalogCode, getCorrelationId, getCurrentWorkflowContext, getEventQueue, getEvents, getMeter, getMetrics, getOperationContext, getOrCreateCorrelationId, getRequestLogger, getRequestLoggerSafe, getStructuredErrorAttributes, getTraceContext, getTracer, hasRequestContext, httpClient, httpRequestHeaderAttribute, httpResponseHeaderAttribute, httpServer, identify, init, instrument, isCatalogError, isInWorkflow, isInitialized, isLoggerLocked, isTracing, llmHistogramAdvice, lockLogger, markAsImmediate, mergeAttrs, mergeServiceResource, normalizeAttributeRedactorConfig, otelTrace, parseError, propagation, recordLLMCost, recordPromptSent, recordResponseReceived, recordRetry, recordStreamFirstToken, recordStructuredError, recordToolCall, request, resetEvents, resetMetrics, resolveSamplingPreset, resolveTraceUrl, runInOperationContext, runWithCorrelationId, runWithRequestContext, runWithSpan, safeSetAttributes, samplingPresets, setAutotelTracerProvider, setCorrelationId, setCorrelationIdInBaggage, setDevice, setError, setException, setSession, setUser, shutdown, span, structuredErrorToJSON, toAttributeValue, trace, traceConsumer, traceDB, traceHTTP, traceLLM, traceMessaging, traceProducer, traceStep, traceWorkflow, track, validateAttribute, withBaggage, withNewContext, withTracing };
 //# sourceMappingURL=index.js.map