autotel 7.0.1 → 7.2.0

package/dist/{init-DDyaLzeg.js → init-DzAdgcFM.js}

@@ -1,694 +1,1038 @@
-import { _ as readProperty, f as describeValue, h as isFunction, i as asNumber, l as asString, r as asFunction, s as asRecord, t as asBoolean } from "./values-BenyvWKz.js";
+import { _ as readProperty, d as asStringRecord, f as describeValue, h as isFunction, i as asNumber, l as asString, r as asFunction, s as asRecord, t as asBoolean } from "./values-BenyvWKz.js";
 import { getForceFlushableProvider } from "./tracer-provider.js";
 import { getConfig as getConfig$1 } from "./config.js";
-import { AUTOTEL_SAMPLING_RATE, resolveSamplingPreset, samplingPresets } from "./sampling.js";
+import { r as recordStructuredError } from "./structured-error-YIuka-FE.js";
 import { n as safeRequire, t as requireModule } from "./node-require-DSPjaw_l.js";
-import { TailSamplingSpanProcessor } from "./tail-sampling-processor.js";
 import { FilteringSpanProcessor } from "./filtering-span-processor.js";
 import { PolicyLogRecordProcessor, policySpanFilter, setPolicies, watchPolicyFile } from "./policy.js";
 import { SpanNameNormalizingProcessor } from "./span-name-normalizer.js";
 import { AttributeRedactingProcessor, REDACTOR_PRESETS, normalizeAttributeRedactorConfig } from "./attribute-redacting-processor.js";
 import { t as PrettyConsoleExporter } from "./pretty-console-exporter-DqKl_q9z.js";
-import { loadYamlConfig } from "./yaml-config.js";
 import { t as CanonicalLogLineProcessor } from "./canonical-log-line-processor-hFUmS__K.js";
-import { r as recordStructuredError } from "./structured-error-YIuka-FE.js";
 import { resetMetrics } from "./metric.js";
 import { NodeSDK } from "@opentelemetry/sdk-node";
 import { AlwaysOffSampler, AlwaysOnSampler, BatchSpanProcessor, ConsoleSpanExporter, ParentBasedSampler, SamplingDecision, SimpleSpanProcessor, TraceIdRatioBasedSampler } from "@opentelemetry/sdk-trace-base";
 import { resourceFromAttributes } from "@opentelemetry/resources";
 import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from "@opentelemetry/semantic-conventions";
-import { context, propagation, trace } from "@opentelemetry/api";
+import { TraceFlags, context, propagation, trace } from "@opentelemetry/api";
+import * as nodeAsyncHooks from "node:async_hooks";
 import { PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
 import { BatchLogRecordProcessor } from "@opentelemetry/sdk-logs";
+import * as nodeFs from "node:fs";
+import path from "node:path";
 import { constants } from "node:os";
-import * as nodeAsyncHooks from "node:async_hooks";
 import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
 import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
 import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-http";
 
-//#region src/init-logger.ts
-const LOG_LEVELS = {
-	debug: 0,
-	info: 1,
-	warn: 2,
-	error: 3
-};
-/** Silent logger used until and unless the application opts into diagnostics. */
-const silentLogger = {
-	info: () => {},
-	warn: () => {},
-	error: () => {},
-	debug: () => {}
-};
-/** Apply the resolved silence and minimum-level settings to a logger. */
-function wrapLogger(base, silent, minLevel) {
-	if (silent) return silentLogger;
-	const threshold = LOG_LEVELS[minLevel];
-	const wrap = (fn, level) => {
-		if (LOG_LEVELS[level] < threshold) return (() => {});
-		return ((...args) => fn(...args));
-	};
-	return {
-		debug: wrap(base.debug, "debug"),
-		info: wrap(base.info, "info"),
-		warn: wrap(base.warn, "warn"),
-		error: wrap(base.error, "error")
-	};
-}
-
-//#endregion
-//#region src/posthog-logs.ts
-var RedactingLogRecordProcessor = class {
-	wrapped;
-	redact;
-	constructor(wrapped, redact) {
-		this.wrapped = wrapped;
-		this.redact = redact;
+//#region src/rate-limiter.ts
+/**
+* Token bucket rate limiter
+*
+* Allows bursts up to burstCapacity, then smooths to maxEventsPerSecond.
+* Thread-safe for async operations.
+*/
+var TokenBucketRateLimiter = class {
+	tokens;
+	maxTokens;
+	refillRate;
+	lastRefill;
+	constructor(config) {
+		this.maxTokens = config.burstCapacity || config.maxEventsPerSecond * 2;
+		this.tokens = this.maxTokens;
+		this.refillRate = config.maxEventsPerSecond / 1e3;
+		this.lastRefill = Date.now();
 	}
-	onEmit(logRecord, context) {
-		const body = asString(logRecord.body);
-		if (body) logRecord.body = this.redact(body);
-		if (logRecord.attributes) for (const [key, value] of Object.entries(logRecord.attributes)) {
-			const text = asString(value);
-			if (text !== void 0) logRecord.attributes[key] = this.redact(text);
-			else if (Array.isArray(value)) logRecord.attributes[key] = value.map((item) => {
-				const entry = asString(item);
-				return entry === void 0 ? item : this.redact(entry);
-			});
+	/**
+	* Try to consume a token (allow an event)
+	* Returns true if allowed, false if rate limit exceeded
+	*/
+	tryConsume(count = 1) {
+		this.refill();
+		if (this.tokens >= count) {
+			this.tokens -= count;
+			return true;
 		}
-		this.wrapped.onEmit(logRecord, context);
+		return false;
 	}
-	shutdown() {
-		return this.wrapped.shutdown();
+	/**
+	* Wait until a token is available (async rate limiting)
+	* Returns a promise that resolves when the event can be processed
+	*/
+	async waitForToken(count = 1) {
+		this.refill();
+		if (this.tokens >= count) {
+			this.tokens -= count;
+			return;
+		}
+		const tokensNeeded = count - this.tokens;
+		const waitMs = Math.ceil(tokensNeeded / this.refillRate);
+		await new Promise((resolve) => setTimeout(resolve, waitMs));
+		return this.waitForToken(count);
 	}
-	forceFlush() {
-		return this.wrapped.forceFlush();
+	/**
+	* Refill tokens based on elapsed time
+	*/
+	refill() {
+		const now = Date.now();
+		const tokensToAdd = (now - this.lastRefill) * this.refillRate;
+		this.tokens = Math.min(this.maxTokens, this.tokens + tokensToAdd);
+		this.lastRefill = now;
+	}
+	/**
+	* Get current available tokens (for testing/debugging)
+	*/
+	getAvailableTokens() {
+		this.refill();
+		return Math.floor(this.tokens);
+	}
+	/**
+	* Reset the rate limiter (for testing)
+	*/
+	reset() {
+		this.tokens = this.maxTokens;
+		this.lastRefill = Date.now();
 	}
 };
-/**
-* Build log record processors for PostHog OTLP logs integration.
-*
-* Resolution order:
-* 1. config.url if provided
-* 2. POSTHOG_LOGS_URL env var
-* 3. Empty array (disabled)
-*/
-function buildPostHogLogProcessors(config, stringRedactor) {
-	const url = config?.url || process.env.POSTHOG_LOGS_URL;
-	if (!url) return [];
-	const sdkLogs = safeRequire("@opentelemetry/sdk-logs");
-	const exporterModule = safeRequire("@opentelemetry/exporter-logs-otlp-http");
-	if (!sdkLogs || !exporterModule) return [];
-	const exporter = new exporterModule.OTLPLogExporter({ url });
-	let processor = new sdkLogs.BatchLogRecordProcessor({ exporter });
-	if (stringRedactor) processor = new RedactingLogRecordProcessor(processor, stringRedactor);
-	return [processor];
-}
 
 //#endregion
-//#region src/baggage-span-processor.ts
+//#region src/correlation-id.ts
 /**
-* Span processor that automatically copies baggage entries to span attributes
+* Correlation ID utilities for event-driven observability
 *
-* This makes baggage visible in trace UIs (Jaeger, Grafana, DataDog, etc.)
-* without manually calling ctx.setAttribute() for each baggage entry.
+* Provides a stable join key across events, logs, and spans even when traces fragment.
+* Format: 16 hex chars (64 bits), crypto-random, URL-safe.
 *
-* @example Enable in init()
+* Lifecycle:
+* 1. Generated at boundary root (HTTP server span, message process span, cron job span)
+* 2. Reused within context (nested work shares it via AsyncLocalStorage)
+* 3. Propagated via baggage (optional, default OFF to avoid header bloat)
+*
+* @example Basic usage
 * ```typescript
-* init({
-*   service: 'my-app',
-*   baggage: true // Uses default 'baggage.' prefix
-* });
+* import { generateCorrelationId, getCorrelationId } from 'autotel/correlation-id';
 *
-* // Now baggage automatically appears as span attributes
-* await withBaggage({
-*   baggage: { 'tenant.id': 't1', 'user.id': 'u1' },
-*   fn: async () => {
-*     // Span has baggage.tenant.id and baggage.user.id attributes!
-*   }
-* });
-* ```
+* // Generate a new correlation ID
+* const id = generateCorrelationId();
+* // Returns: 'a1b2c3d4e5f67890'
 *
-* @example Custom prefix
-* ```typescript
-* init({
-*   service: 'my-app',
-*   baggage: 'ctx' // Uses 'ctx.' prefix
-* });
-* // Creates attributes: ctx.tenant.id, ctx.user.id
+* // Get current correlation ID from context
+* const currentId = getCorrelationId();
 * ```
 */
-var BaggageSpanProcessor = class {
-	prefix;
-	constructor(options = {}) {
-		this.prefix = options.prefix ?? "baggage.";
-	}
-	onStart(span, parentContext) {
-		let baggage = propagation.getBaggage(parentContext);
-		if (!baggage) baggage = propagation.getBaggage(context.active());
-		if (!baggage) try {
-			const { getActiveContextWithBaggage } = requireModule("./trace-context");
-			const storedContext = getActiveContextWithBaggage();
-			baggage = propagation.getBaggage(storedContext);
-		} catch {}
-		if (!baggage) return;
-		for (const [key, entry] of baggage.getAllEntries()) span.setAttribute(`${this.prefix}${key}`, entry.value);
-	}
-	onEnd(_span) {}
-	async shutdown() {}
-	async forceFlush() {}
-};
-
-//#endregion
-//#region src/redact-values.ts
-/** Standalone string redaction for use outside the span processor pipeline. */
-function createStringRedactor(config) {
-	const resolved = typeof config === "string" ? REDACTOR_PRESETS[config] : config;
-	const valuePatterns = resolved.valuePatterns ?? [];
-	const defaultReplacement = resolved.replacement ?? "[REDACTED]";
-	return (value) => {
-		let result = value;
-		for (const { pattern, replacement, mask } of valuePatterns) {
-			pattern.lastIndex = 0;
-			result = mask ? result.replaceAll(pattern, (match) => mask(match)) : result.replaceAll(pattern, replacement ?? defaultReplacement);
-		}
-		return result;
-	};
-}
-
-//#endregion
-//#region src/env-config.ts
 /**
-* Validate URL format
+* AsyncLocalStorage for storing correlation ID
+* This allows correlation IDs to persist across async boundaries
 */
-function isValidUrl(urlString) {
-	try {
-		const url = new URL(urlString);
-		return url.protocol === "http:" || url.protocol === "https:";
-	} catch {
-		return false;
-	}
-}
+const correlationStorage = new nodeAsyncHooks.AsyncLocalStorage();
 /**
-* Resolve OpenTelemetry environment variables from process.env
+* Baggage key for correlation ID propagation
 */
-function resolveOtelEnv() {
-	const env = {};
-	if (process.env.OTEL_SERVICE_NAME) {
-		const value = process.env.OTEL_SERVICE_NAME.trim();
-		if (value) env.OTEL_SERVICE_NAME = value;
-	}
-	if (process.env.OTEL_EXPORTER_OTLP_ENDPOINT) {
-		const value = process.env.OTEL_EXPORTER_OTLP_ENDPOINT.trim();
-		if (value && isValidUrl(value)) env.OTEL_EXPORTER_OTLP_ENDPOINT = value;
-	}
-	if (process.env.OTEL_EXPORTER_OTLP_HEADERS) {
-		const value = process.env.OTEL_EXPORTER_OTLP_HEADERS.trim();
-		if (value) env.OTEL_EXPORTER_OTLP_HEADERS = value;
-	}
-	if (process.env.OTEL_RESOURCE_ATTRIBUTES) {
-		const value = process.env.OTEL_RESOURCE_ATTRIBUTES.trim();
-		if (value) env.OTEL_RESOURCE_ATTRIBUTES = value;
-	}
-	if (process.env.OTEL_EXPORTER_OTLP_PROTOCOL) {
-		const value = process.env.OTEL_EXPORTER_OTLP_PROTOCOL.trim().toLowerCase();
-		if (value === "http" || value === "http/json") env.OTEL_EXPORTER_OTLP_PROTOCOL = "http";
-		else if (value === "http/protobuf" || value === "grpc") env.OTEL_EXPORTER_OTLP_PROTOCOL = value;
-	}
-	if (process.env.OTEL_TRACES_SAMPLER) {
-		const value = process.env.OTEL_TRACES_SAMPLER.trim();
-		if (value) env.OTEL_TRACES_SAMPLER = value;
-	}
-	if (process.env.OTEL_TRACES_SAMPLER_ARG) {
-		const value = process.env.OTEL_TRACES_SAMPLER_ARG.trim();
-		if (value) env.OTEL_TRACES_SAMPLER_ARG = value;
-	}
-	return env;
-}
-function parseRatioSamplerArg(samplerName, samplerArg) {
-	if (samplerArg === void 0) return 1;
-	const ratio = Number(samplerArg);
-	if (!Number.isFinite(ratio) || ratio < 0 || ratio > 1) {
-		console.error(`[autotel] Invalid OTEL_TRACES_SAMPLER_ARG="${samplerArg}" for ${samplerName}. Expected a number in [0..1]. Falling back to 1.0.`);
-		return 1;
-	}
-	return ratio;
-}
-function warnOnUnusedSamplerArg(samplerName, samplerArg) {
-	if (samplerArg !== void 0) console.error(`[autotel] OTEL_TRACES_SAMPLER_ARG is not used by OTEL_TRACES_SAMPLER="${samplerName}". Ignoring value "${samplerArg}".`);
+const CORRELATION_ID_BAGGAGE_KEY = "autotel.correlation_id";
+/**
+* Generate a new correlation ID
+*
+* Format: 16 hex chars (64 bits), crypto-random, URL-safe
+*
+* @returns A new correlation ID
+*
+* @example
+* ```typescript
+* const id = generateCorrelationId();
+* // Returns: 'a1b2c3d4e5f67890'
+* ```
+*/
+function generateCorrelationId() {
+	const bytes = /* @__PURE__ */ new Uint8Array(8);
+	crypto.getRandomValues(bytes);
+	return [...bytes].map((b) => b.toString(16).padStart(2, "0")).join("");
 }
-function createSamplerFromEnv(env) {
-	const samplerName = env.OTEL_TRACES_SAMPLER;
-	if (!samplerName) return;
-	switch (samplerName) {
-		case "always_on":
-			warnOnUnusedSamplerArg(samplerName, env.OTEL_TRACES_SAMPLER_ARG);
-			return new AlwaysOnSampler();
-		case "always_off":
-			warnOnUnusedSamplerArg(samplerName, env.OTEL_TRACES_SAMPLER_ARG);
-			return new AlwaysOffSampler();
-		case "traceidratio": return new TraceIdRatioBasedSampler(parseRatioSamplerArg(samplerName, env.OTEL_TRACES_SAMPLER_ARG));
-		case "parentbased_always_on":
-			warnOnUnusedSamplerArg(samplerName, env.OTEL_TRACES_SAMPLER_ARG);
-			return new ParentBasedSampler({ root: new AlwaysOnSampler() });
-		case "parentbased_always_off":
-			warnOnUnusedSamplerArg(samplerName, env.OTEL_TRACES_SAMPLER_ARG);
-			return new ParentBasedSampler({ root: new AlwaysOffSampler() });
-		case "parentbased_traceidratio": return new ParentBasedSampler({ root: new TraceIdRatioBasedSampler(parseRatioSamplerArg(samplerName, env.OTEL_TRACES_SAMPLER_ARG)) });
-		case "jaeger_remote":
-		case "parentbased_jaeger_remote":
-		case "xray":
-			console.error(`[autotel] OTEL_TRACES_SAMPLER="${samplerName}" is not supported yet by autotel. Falling back to the next sampler source.`);
-			return;
-		default:
-			console.error(`[autotel] Unknown OTEL_TRACES_SAMPLER="${samplerName}". Falling back to the next sampler source.`);
-			return;
-	}
+/**
+* Get the current correlation ID from context
+*
+* Resolution order:
+* 1. AsyncLocalStorage (from explicit setCorrelationId or runWithCorrelationId)
+* 2. Baggage (if propagated from upstream)
+* 3. Active span's trace ID (first 16 chars as fallback)
+* 4. undefined (if not in any context)
+*
+* @returns Current correlation ID or undefined
+*
+* @example
+* ```typescript
+* const id = getCorrelationId();
+* if (id) {
+*   console.log('Correlation ID:', id);
+* }
+* ```
+*/
+function getCorrelationId() {
+	const storedId = correlationStorage.getStore()?.value;
+	if (storedId) return storedId;
+	const activeContext = context.active();
+	const baggageEntry = propagation.getBaggage(activeContext)?.getEntry(CORRELATION_ID_BAGGAGE_KEY);
+	if (baggageEntry?.value) return baggageEntry.value;
+	const span = trace.getActiveSpan();
+	if (span) return span.spanContext().traceId.slice(0, 16);
 }
 /**
-* Parse OTEL_RESOURCE_ATTRIBUTES from comma-separated key=value pairs
-* Example: "service.version=1.0.0,deployment.environment=production"
+* Get or create a correlation ID
+*
+* If a correlation ID exists in the current context, returns it.
+* Otherwise, generates a new one.
+*
+* @returns Existing or new correlation ID
+*
+* @example
+* ```typescript
+* const id = getOrCreateCorrelationId();
+* // Always returns a valid correlation ID
+* ```
 */
-function parseResourceAttributes(input) {
-	if (!input || input.trim() === "") return {};
-	const attributes = {};
-	const pairs = input.split(",");
-	for (const pair of pairs) {
-		const trimmedPair = pair.trim();
-		if (!trimmedPair) continue;
-		const equalIndex = trimmedPair.indexOf("=");
-		if (equalIndex === -1) continue;
-		const key = trimmedPair.slice(0, equalIndex).trim();
-		const value = trimmedPair.slice(equalIndex + 1).trim();
-		if (key && value) attributes[key] = value;
-	}
-	return attributes;
+function getOrCreateCorrelationId() {
+	return getCorrelationId() ?? generateCorrelationId();
 }
 /**
-* Parse OTEL_EXPORTER_OTLP_HEADERS from comma-separated key=value pairs
-* Example: "api-key=secret123,x-custom-header=value"
+* Run a function with a specific correlation ID in context
+*
+* The correlation ID will be available via getCorrelationId() throughout
+* the execution of the function and any async operations it spawns.
+*
+* @param correlationId - Correlation ID to use
+* @param fn - Function to execute
+* @returns The return value of the function
+*
+* @example
+* ```typescript
+* await runWithCorrelationId('abc123', async () => {
+*   // getCorrelationId() returns 'abc123' here
+*   await processRequest();
+* });
+* ```
 */
-function parseOtlpHeaders(input) {
-	if (!input || input.trim() === "") return {};
-	const headers = {};
-	const pairs = input.split(",");
-	for (const pair of pairs) {
-		const trimmedPair = pair.trim();
-		if (!trimmedPair) continue;
-		const equalIndex = trimmedPair.indexOf("=");
-		if (equalIndex === -1) continue;
-		const key = trimmedPair.slice(0, equalIndex).trim();
-		const value = trimmedPair.slice(equalIndex + 1).trim();
-		if (key && value) headers[key] = value;
-	}
-	return headers;
+function runWithCorrelationId(correlationId, fn) {
+	return correlationStorage.run({ value: correlationId }, fn);
 }
 /**
-* Convert resolved environment variables to config
+* Set correlation ID in the current context (mutates context)
+*
+* Note: This updates the AsyncLocalStorage context. For proper scoping
+* across async boundaries, prefer runWithCorrelationId() instead.
+*
+* @param correlationId - Correlation ID to set
+*
+* @example
+* ```typescript
+* setCorrelationId('abc123');
+* // Now getCorrelationId() returns 'abc123'
+* ```
 */
-function envToConfig(env) {
-	const config = {};
-	if (env.OTEL_SERVICE_NAME) config.service = env.OTEL_SERVICE_NAME;
-	if (env.OTEL_EXPORTER_OTLP_ENDPOINT) config.endpoint = env.OTEL_EXPORTER_OTLP_ENDPOINT;
-	if (env.OTEL_EXPORTER_OTLP_PROTOCOL) config.protocol = env.OTEL_EXPORTER_OTLP_PROTOCOL;
-	if (env.OTEL_EXPORTER_OTLP_HEADERS) config.headers = parseOtlpHeaders(env.OTEL_EXPORTER_OTLP_HEADERS);
-	const resourceAttrs = parseResourceAttributes(env.OTEL_RESOURCE_ATTRIBUTES);
-	if (Object.keys(resourceAttrs).length > 0) config.resourceAttributes = resourceAttrs;
-	const sampler = createSamplerFromEnv(env);
-	if (sampler) config.otelSampler = sampler;
-	return config;
+function setCorrelationId(correlationId) {
+	enterOrRun(correlationStorage, correlationId);
 }
 /**
-* Main function to resolve config from environment variables
+* Set correlation ID in baggage for propagation
+*
+* This adds the correlation ID to the W3C baggage header, allowing it
+* to be propagated to downstream services.
+*
+* Note: Only use this when you explicitly want cross-service propagation.
+* Default is OFF to avoid header bloat.
+*
+* @param correlationId - Correlation ID to propagate
+* @returns New context with baggage set
+*
+* @example
+* ```typescript
+* const newContext = setCorrelationIdInBaggage('abc123');
+* context.with(newContext, () => {
+*   // Baggage will be propagated in outgoing requests
+* });
+* ```
 */
-function resolveConfigFromEnv() {
-	return envToConfig(resolveOtelEnv());
+function setCorrelationIdInBaggage(correlationId) {
+	const activeContext = context.active();
+	let baggage = propagation.getBaggage(activeContext) ?? propagation.createBaggage();
+	baggage = baggage.setEntry(CORRELATION_ID_BAGGAGE_KEY, { value: correlationId });
+	return propagation.setBaggage(activeContext, baggage);
 }
-
-//#endregion
-//#region src/devtools.ts
-const defaultHost = "127.0.0.1";
-const defaultPort = 4318;
-function resolveDevtoolsConfig(config) {
-	if (!config) return {
-		enabled: false,
-		endpoint: void 0,
-		embedded: false,
-		host: defaultHost,
-		port: defaultPort,
-		verbose: false
-	};
-	if (config === true) return {
-		enabled: true,
-		endpoint: `http://${defaultHost}:${defaultPort}`,
-		embedded: false,
-		host: defaultHost,
-		port: defaultPort,
-		verbose: false
-	};
-	const enabled = config.enabled ?? true;
-	const host = config.host ?? defaultHost;
-	const port = config.port ?? defaultPort;
-	const endpoint = config.endpoint ?? `http://${host}:${port}`;
-	return {
-		enabled,
-		endpoint: enabled ? endpoint : void 0,
-		embedded: enabled && (config.embedded ?? false),
-		host,
-		port,
-		verbose: config.verbose ?? false
-	};
+/**
+* Get the correlation storage instance (for internal use in init/shutdown)
+*/
+function getCorrelationStorage() {
+	return correlationStorage;
 }
 
 //#endregion
-//#region src/process-handlers.ts
-let removeOwnedHandlers = [];
-/**
-* Tracked separately from `removeOwnedHandlers` because the exit flush outlives
-* a call to `installProcessHandlers`, which clears that list before installing
-* its own signal listeners.
-*/
-let removeExitFlush;
+//#region src/event-queue.ts
+const DEFAULT_CONFIG$2 = {
+	maxSize: 5e4,
+	batchSize: 100,
+	flushInterval: 1e4,
+	maxRetries: 3,
+	rateLimit: {
+		maxEventsPerSecond: 100,
+		burstCapacity: 200
+	}
+};
 /**
-* Shared across every path that can end the process: signals, fatal errors and
-* a clean exit. They can overlap — a container stopping a job that has just
-* finished its work sends SIGTERM while the exit flush is still draining — and
-* a second shutdown would tear down queues the first is still using.
+* Get subscriber name for metrics (stable, low-cardinality)
+*
+* Priority:
+* 1. Explicit config: subscriber.name
+* 2. Class static property (if available)
+* 3. Fallback: lowercase class name without "Subscriber" suffix
 */
-let shutdownInFlight;
+function getSubscriberName(subscriber) {
+	if (subscriber.name) return subscriber.name.toLowerCase();
+	return (subscriber.constructor?.name || "unknown").replace(/Subscriber$/i, "").toLowerCase();
+}
 /**
-* The clean-exit flush, while it runs. Doubles as the latch that keeps a
-* re-emitted `beforeExit` from flushing twice, and as the thing a shutdown
-* waits on rather than tearing down queues mid-drain.
+* Subscribers whose `shutdown()` has run. Terminal for the client they wrap, so
+* a queue rebuilt from the same config must not reuse them.
 */
-let exitFlushInFlight;
-const DEFAULT_SHUTDOWN_TIMEOUT_MS = 2e3;
-function runShutdownOnce(shutdown, timeoutMs) {
-	if (shutdownInFlight) return shutdownInFlight;
-	let timeoutHandle;
-	const shutdownAttempt = Promise.resolve(exitFlushInFlight).then(shutdown).catch(() => void 0);
-	const timeout = new Promise((resolve) => {
-		timeoutHandle = setTimeout(resolve, timeoutMs);
-		timeoutHandle.unref();
-	});
-	shutdownInFlight = Promise.race([shutdownAttempt, timeout]).then(() => {
-		if (timeoutHandle) clearTimeout(timeoutHandle);
-	});
-	return shutdownInFlight;
-}
-const DEFAULT_SIGNALS = ["SIGTERM", "SIGINT"];
-function signalExitCode(signal) {
-	return 128 + constants.signals[signal];
-}
+const shutDownSubscribers = /* @__PURE__ */ new WeakSet();
 /**
-* Surface a fatal error before shutting down.
+* Events queue with batching and backpressure
 *
-* Registering an `uncaughtException` / `unhandledRejection` listener overrides
-* Node's default of printing the stack to stderr, so without this a crash under
-* `fatalErrors` would exit silently. Autotel's own logger is silent by default,
-* so we print to stderr directly to guarantee the crash stays visible.
+* Features:
+* - Batches events for efficient sending
+* - Bounded queue with drop-oldest policy (prod) or blocking (dev)
+* - Exponential backoff retry
+* - Rate limiting to prevent overwhelming subscribers
+* - Graceful flush on shutdown
 */
-function reportFatalError(error, event) {
-	const err = error instanceof Error ? error : new Error(String(error));
-	console.error(`[autotel] ${event}, flushing telemetry then exiting`, err);
-}
-function installProcessHandlers(config, shutdown) {
-	uninstallProcessHandlers();
-	const timeoutMs = config.shutdownTimeoutMs ?? DEFAULT_SHUTDOWN_TIMEOUT_MS;
-	let exitScheduled = false;
-	let resolvedExitCode = 0;
-	let fatalLatched = false;
-	const shutdownAndExit = (exitCode, fatal) => {
-		if (fatal) {
-			if (!fatalLatched) {
-				resolvedExitCode = exitCode;
-				fatalLatched = true;
-			}
-		} else if (!exitScheduled && !fatalLatched) resolvedExitCode = exitCode;
-		if (exitScheduled) return;
-		exitScheduled = true;
-		runShutdownOnce(shutdown, timeoutMs).then(() => {
-			process.exit(resolvedExitCode);
-		});
-	};
-	for (const signal of config.signals ?? DEFAULT_SIGNALS) {
-		const listener = () => {
-			shutdownAndExit(signalExitCode(signal), false);
+var EventQueue = class {
+	queue = [];
+	flushTimer = null;
+	config;
+	subscribers;
+	rateLimiter;
+	flushPromise = null;
+	isShuttingDown = false;
+	metrics = null;
+	observableCleanups = [];
+	subscriberHealthy = /* @__PURE__ */ new Map();
+	constructor(subscribers, config) {
+		const live = subscribers.filter((s) => !shutDownSubscribers.has(s));
+		if (live.length < subscribers.length) getLogger().warn({ subscribers: subscribers.filter((s) => shutDownSubscribers.has(s)).map((s) => getSubscriberName(s)) }, "[autotel] Subscriber already shut down, events will not be delivered; pass new subscriber instances to init()");
+		this.subscribers = live;
+		this.config = {
+			...DEFAULT_CONFIG$2,
+			...config
 		};
-		process.on(signal, listener);
-		removeOwnedHandlers.push(() => {
-			process.removeListener(signal, listener);
-		});
+		this.rateLimiter = this.config.rateLimit ? new TokenBucketRateLimiter(this.config.rateLimit) : null;
+		for (const subscriber of this.subscribers) {
+			const name = getSubscriberName(subscriber);
+			this.subscriberHealthy.set(name, true);
+		}
+		this.initMetrics();
 	}
-	if (config.fatalErrors ?? true) {
-		const uncaughtExceptionListener = (error) => {
-			reportFatalError(error, "uncaughtException");
-			shutdownAndExit(1, true);
+	/**
+	* Initialize OTel metrics for queue observability
+	*/
+	initMetrics() {
+		const meter = getConfig$1().meter;
+		const queueSize = meter.createObservableGauge("autotel.event_delivery.queue.size", {
+			description: "Current number of events in the delivery queue",
+			unit: "count"
+		});
+		const queueSizeCallback = (observableResult) => {
+			observableResult.observe(this.queue.length);
 		};
-		const unhandledRejectionListener = (reason) => {
-			reportFatalError(reason, "unhandledRejection");
-			shutdownAndExit(1, true);
+		queueSize.addCallback(queueSizeCallback);
+		this.observableCleanups.push(() => queueSize.removeCallback(queueSizeCallback));
+		const oldestAge = meter.createObservableGauge("autotel.event_delivery.queue.oldest_age_ms", {
+			description: "Age of the oldest event in the queue in milliseconds",
+			unit: "ms"
+		});
+		const oldestAgeCallback = (observableResult) => {
+			if (this.queue.length > 0) {
+				const oldest = this.queue[0];
+				const ageMs = Date.now() - oldest.timestamp;
+				observableResult.observe(ageMs);
+			} else observableResult.observe(0);
 		};
-		process.on("uncaughtException", uncaughtExceptionListener);
-		process.on("unhandledRejection", unhandledRejectionListener);
-		removeOwnedHandlers.push(() => {
-			process.removeListener("uncaughtException", uncaughtExceptionListener);
-		}, () => {
-			process.removeListener("unhandledRejection", unhandledRejectionListener);
+		oldestAge.addCallback(oldestAgeCallback);
+		this.observableCleanups.push(() => oldestAge.removeCallback(oldestAgeCallback));
+		const delivered = meter.createCounter("autotel.event_delivery.queue.delivered", {
+			description: "Number of events successfully delivered to subscribers",
+			unit: "count"
 		});
-	}
-}
-/**
-* Flush telemetry when the process runs to completion.
-*
-* The signal and fatal-error handlers above cover a process that is stopped or
-* that crashes. Neither fires when a script simply finishes: the event loop
-* drains and Node exits, taking whatever the batch span processor was still
-* holding with it. `beforeExit` is the only hook for that case, and it is the
-* one that matters for CLIs, cron jobs, CI steps and serverless handlers.
-*
-* A flush, never a shutdown: `beforeExit` fires on *any* event-loop drain, not
-* only the final one, so tearing the SDK down here would silently kill
-* telemetry in a process that goes on to do more work.
-*/
-function installExitFlush(flushTelemetry, timeoutMs = DEFAULT_SHUTDOWN_TIMEOUT_MS) {
-	removeExitFlush?.();
-	exitFlushInFlight = void 0;
-	const listener = (code) => {
-		if (exitFlushInFlight || shutdownInFlight) return;
-		const deadline = setTimeout(() => {
-			process.exit(process.exitCode ?? code);
-		}, timeoutMs);
-		exitFlushInFlight = flushTelemetry().catch(() => void 0).finally(() => {
-			clearTimeout(deadline);
+		const failed = meter.createCounter("autotel.event_delivery.queue.failed", {
+			description: "Number of events that failed delivery after all retry attempts",
+			unit: "count"
 		});
-	};
-	process.on("beforeExit", listener);
-	removeExitFlush = () => {
-		process.removeListener("beforeExit", listener);
-		removeExitFlush = void 0;
-	};
-}
-function uninstallProcessHandlers() {
-	for (const removeHandler of removeOwnedHandlers) removeHandler();
-	removeOwnedHandlers = [];
-	removeExitFlush?.();
-	shutdownInFlight = void 0;
-	exitFlushInFlight = void 0;
-}
-
-//#endregion
-//#region src/rate-limiter.ts
-/**
-* Token bucket rate limiter
-*
-* Allows bursts up to burstCapacity, then smooths to maxEventsPerSecond.
-* Thread-safe for async operations.
-*/
-var TokenBucketRateLimiter = class {
-	tokens;
-	maxTokens;
-	refillRate;
-	lastRefill;
-	constructor(config) {
-		this.maxTokens = config.burstCapacity || config.maxEventsPerSecond * 2;
-		this.tokens = this.maxTokens;
-		this.refillRate = config.maxEventsPerSecond / 1e3;
-		this.lastRefill = Date.now();
+		const dropped = meter.createCounter("autotel.event_delivery.queue.dropped", {
+			description: "Number of events dropped from the queue",
+			unit: "count"
+		});
+		const latency = meter.createHistogram("autotel.event_delivery.queue.latency_ms", {
+			description: "Event delivery latency from enqueue to successful send",
+			unit: "ms"
+		});
+		const subscriberHealth = meter.createObservableGauge("autotel.event_delivery.subscriber.health", {
+			description: "Subscriber health status (1=healthy, 0=unhealthy)",
+			unit: "1"
+		});
+		const subscriberHealthCallback = (observableResult) => {
+			for (const [subscriberName, isHealthy] of this.subscriberHealthy) observableResult.observe(isHealthy ? 1 : 0, { subscriber: subscriberName });
+		};
+		subscriberHealth.addCallback(subscriberHealthCallback);
+		this.observableCleanups.push(() => subscriberHealth.removeCallback(subscriberHealthCallback));
+		this.metrics = {
+			queueSize,
+			oldestAge,
+			delivered,
+			failed,
+			dropped,
+			latency,
+			subscriberHealth
+		};
 	}
 	/**
-	* Try to consume a token (allow an event)
-	* Returns true if allowed, false if rate limit exceeded
+	* Record a dropped event with reason and emit debug breadcrumb
 	*/
-	tryConsume(count = 1) {
-		this.refill();
-		if (this.tokens >= count) {
-			this.tokens -= count;
-			return true;
-		}
-		return false;
-	}
+	recordDropped(reason, event, subscriberName) {
+		const attrs = { reason };
+		if (subscriberName) attrs.subscriber = subscriberName;
+		this.metrics?.dropped.add(1, attrs);
+		const logLevel = reason === "payload_invalid" ? "error" : "warn";
+		const logger = getLogger();
+		if (logLevel === "error") logger.error({
+			eventName: event?.name,
+			subscriber: subscriberName,
+			reason,
+			correlationId: event?._correlationId,
+			traceId: event?._traceId
+		}, `[autotel] Event dropped: ${reason}`);
+		else logger.warn({
+			eventName: event?.name,
+			subscriber: subscriberName,
+			reason,
+			correlationId: event?._correlationId,
+			traceId: event?._traceId
+		}, `[autotel] Event dropped: ${reason}`);
+	}
 	/**
-	* Wait until a token is available (async rate limiting)
-	* Returns a promise that resolves when the event can be processed
+	* Record permanent delivery failure (after all retries exhausted)
+	* Increments failed counter and logs error
 	*/
-	async waitForToken(count = 1) {
-		this.refill();
-		if (this.tokens >= count) {
-			this.tokens -= count;
-			return;
-		}
-		const tokensNeeded = count - this.tokens;
-		const waitMs = Math.ceil(tokensNeeded / this.refillRate);
-		await new Promise((resolve) => setTimeout(resolve, waitMs));
-		return this.waitForToken(count);
+	recordFailed(event, subscriberName, error) {
+		this.metrics?.failed.add(1, { subscriber: subscriberName });
+		this.subscriberHealthy.set(subscriberName, false);
+		getLogger().error({
+			eventName: event.name,
+			subscriber: subscriberName,
+			correlationId: event._correlationId,
+			traceId: event._traceId,
+			err: error
+		}, `[autotel] Event delivery failed after all retries`);
 	}
 	/**
-	* Refill tokens based on elapsed time
+	* Mark subscriber as unhealthy on transient failure (without incrementing failed counter)
+	* Used during retry attempts - only recordFailed should increment the counter
 	*/
-	refill() {
-		const now = Date.now();
-		const tokensToAdd = (now - this.lastRefill) * this.refillRate;
-		this.tokens = Math.min(this.maxTokens, this.tokens + tokensToAdd);
-		this.lastRefill = now;
+	markSubscriberUnhealthy(subscriberName) {
+		this.subscriberHealthy.set(subscriberName, false);
 	}
 	/**
-	* Get current available tokens (for testing/debugging)
+	* Record successful delivery
 	*/
-	getAvailableTokens() {
-		this.refill();
-		return Math.floor(this.tokens);
+	recordDelivered(event, subscriberName, startTime) {
+		const latencyMs = Date.now() - startTime;
+		this.metrics?.delivered.add(1, { subscriber: subscriberName });
+		this.metrics?.latency.record(latencyMs, { subscriber: subscriberName });
+		this.subscriberHealthy.set(subscriberName, true);
 	}
 	/**
-	* Reset the rate limiter (for testing)
+	* Enqueue an event for sending
+	*
+	* Backpressure policy:
+	* - Drops oldest event and logs warning if queue is full (same behavior in all environments)
 	*/
-	reset() {
-		this.tokens = this.maxTokens;
-		this.lastRefill = Date.now();
-	}
-};
-
-//#endregion
-//#region src/trace-context.ts
-const spansWithExplicitStatus = /* @__PURE__ */ new WeakSet();
-/** Whether a TraceContext consumer explicitly chose this span's status. */
-function hasExplicitSpanStatus(span) {
-	return spansWithExplicitStatus.has(span);
-}
-/**
-* AsyncLocalStorage for storing the active context with baggage
-* This allows setters to update the context and have it persist
-*/
-const contextStorage = new nodeAsyncHooks.AsyncLocalStorage();
-/**
-* Get the context storage instance (for initialization in functional.ts)
-*/
-function getContextStorage() {
-	return contextStorage;
-}
-/**
-* Get the active OTel context with the latest stored baggage overlaid.
-* Span identity always comes from the active OTel scope.
-*/
-function getActiveContextWithBaggage() {
-	const activeContext = context.active();
-	const stored = contextStorage.getStore()?.value;
-	if (!stored) return activeContext;
-	const storedBaggage = propagation.getBaggage(stored);
-	return storedBaggage ? propagation.setBaggage(activeContext, storedBaggage) : activeContext;
-}
-/**
-* Set a value in AsyncLocalStorage, preferring enterWith() when available
-* (Node.js) and falling back to run() for environments that only support
-* run() (e.g. Cloudflare Workers).
-*
-* On runtimes without enterWith() we mutate the existing run() scope when one
-* exists. This is what allows baggage/correlation updates to remain visible
-* for the rest of the traced callback in Workers.
-*/
-function enterOrRun(storage, value) {
-	const existingStore = storage.getStore();
-	if (existingStore) {
-		existingStore.value = value;
-		return;
+	enqueue(event) {
+		if (this.isShuttingDown) {
+			this.recordDropped("shutdown", event);
+			return;
+		}
+		if (this.queue.length >= this.config.maxSize) {
+			const droppedEvent = this.queue.shift();
+			this.recordDropped("rate_limit", droppedEvent);
+			getLogger().warn({ droppedEvent: droppedEvent?.name }, `[autotel] Events queue full (${this.config.maxSize} events). Dropping oldest event. Events are being produced faster than they can be sent. Check your subscribers or reduce tracking frequency.`);
+		}
+		const enrichedEvent = {
+			...event,
+			_correlationId: event._correlationId || getOrCreateCorrelationId()
+		};
+		this.queue.push(enrichedEvent);
+		this.scheduleBatchFlush();
 	}
-	const boxedValue = { value };
-	try {
-		storage.enterWith(boxedValue);
-	} catch {
-		storage.run(boxedValue, () => {});
+	/**
+	* Schedule a batch flush if not already scheduled
+	*/
+	scheduleBatchFlush() {
+		if (this.flushTimer || this.flushPromise) return;
+		this.flushTimer = setTimeout(() => {
+			this.flushTimer = null;
+			this.flushBatch();
+		}, this.config.flushInterval);
 	}
-}
-function updateActiveContext(newContext) {
-	enterOrRun(contextStorage, newContext);
-	const manager = context._getContextManager?.();
-	if (!manager) return;
-	const asyncLocal = manager._asyncLocalStorage ?? void 0;
-	if (asyncLocal?.enterWith) {
-		asyncLocal.enterWith(newContext);
-		return;
+	/**
+	* Flush a batch of events
+	* Uses promise-based concurrency control to prevent race conditions
+	*/
+	async flushBatch() {
+		if (this.queue.length === 0) return;
+		if (this.flushPromise) {
+			await this.flushPromise;
+			return;
+		}
+		this.flushPromise = this.doFlushBatch();
+		try {
+			await this.flushPromise;
+		} finally {
+			this.flushPromise = null;
+			if (this.queue.length > 0) this.scheduleBatchFlush();
+		}
 	}
-	if (isFunction(manager.with)) manager.with(newContext, () => {});
-}
-/**
-* Create a TraceContext from an OpenTelemetry Span
-*
-* This utility extracts trace context information from a span
-* and provides span manipulation methods and baggage operations in a consistent format.
-*
-* Note: Baggage methods always operate on the currently active context,
-* which may differ from the context when createTraceContext was called.
-*/
-function createTraceContext(span) {
-	const spanContext = span.spanContext();
-	if (!contextStorage.getStore()?.value) {
-		const activeContext = context.active();
-		enterOrRun(contextStorage, activeContext);
+	/**
+	* Internal flush implementation
+	*/
+	async doFlushBatch() {
+		const batch = this.queue.splice(0, this.config.batchSize);
+		await this.sendWithRetry(batch, this.config.maxRetries);
 	}
-	const traceCtx = {
-		traceId: spanContext.traceId,
-		spanId: spanContext.spanId,
-		correlationId: spanContext.traceId.slice(0, 16),
-		setAttribute: span.setAttribute.bind(span),
-		setAttributes: span.setAttributes.bind(span),
-		setStatus: (status) => {
-			spansWithExplicitStatus.add(span);
-			span.setStatus(status);
-		},
-		recordException: span.recordException.bind(span),
-		addEvent: span.addEvent.bind(span),
-		addLink: span.addLink.bind(span),
-		addLinks: span.addLinks.bind(span),
-		updateName: span.updateName.bind(span),
-		isRecording: span.isRecording.bind(span),
-		recordError: (cause) => {
-			const err = cause instanceof Error ? cause : new Error(String(cause));
-			recordStructuredError(traceCtx, err);
-		},
-		track: (event, data) => {
-			track(event, data);
-		},
-		getBaggage(key) {
-			const activeCtx = context.active();
-			let baggage = propagation.getBaggage(activeCtx);
-			if (!baggage) {
-				const storedContext = contextStorage.getStore()?.value;
-				if (storedContext) baggage = propagation.getBaggage(storedContext);
-			}
-			return baggage?.getEntry(key)?.value;
-		},
-		setBaggage(key, value) {
-			const currentContext = getActiveContextWithBaggage();
-			const updated = (propagation.getBaggage(currentContext) ?? propagation.createBaggage()).setEntry(key, { value });
-			updateActiveContext(propagation.setBaggage(currentContext, updated));
-			return value;
-		},
-		deleteBaggage(key) {
-			const currentContext = getActiveContextWithBaggage();
-			const baggage = propagation.getBaggage(currentContext);
-			if (baggage) {
-				const updated = baggage.removeEntry(key);
-				updateActiveContext(propagation.setBaggage(currentContext, updated));
+	/**
+	* Send events with exponential backoff retry
+	* Tracks per-event, per-subscriber failures so failed counter reflects actual failed deliveries.
+	* On retry, only failed (event, subscriber) pairs are re-sent to avoid double-counting delivered.
+	*/
+	async sendWithRetry(events, retriesLeft, subscribersByEventIndex) {
+		const failedDeliveries = await this.sendToSubscribers(events, subscribersByEventIndex);
+		if (failedDeliveries.length > 0) if (retriesLeft > 0) {
+			const failedEventIndicesOrdered = [...new Set(failedDeliveries.map((f) => f.eventIndex))].toSorted((a, b) => a - b);
+			const eventsToRetry = failedEventIndicesOrdered.map((i) => events[i]);
+			const failedSubscribersByRetryIndex = /* @__PURE__ */ new Map();
+			for (const [j, origIndex] of failedEventIndicesOrdered.entries()) {
+				const set = /* @__PURE__ */ new Set();
+				for (const { eventIndex, subscriberName } of failedDeliveries) if (eventIndex === origIndex) set.add(subscriberName);
+				failedSubscribersByRetryIndex.set(j, set);
+			}
+			const delay = Math.pow(2, this.config.maxRetries - retriesLeft) * 1e3;
+			await new Promise((resolve) => setTimeout(resolve, delay));
+			return this.sendWithRetry(eventsToRetry, retriesLeft - 1, failedSubscribersByRetryIndex);
+		} else {
+			for (const { eventIndex, subscriberName, error } of failedDeliveries) {
+				const event = events[eventIndex];
+				if (event) this.recordFailed(event, subscriberName, error);
+			}
+			const failedSubscriberNames = [...new Set(failedDeliveries.map((f) => f.subscriberName))];
+			getLogger().error({
+				failedSubscribers: failedSubscriberNames,
+				retriesAttempted: this.config.maxRetries
+			}, "[autotel] Failed to send events after retries");
+		}
+	}
+	/**
+	* Send events to configured subscribers with rate limiting and metrics.
+	* When subscribersByEventIndex is provided (retry path), only those subscribers are tried per event.
+	* Returns per-event, per-subscriber failures (empty if all succeeded).
+	*/
+	async sendToSubscribers(events, subscribersByEventIndex) {
+		const failedDeliveries = [];
+		const sendOne = async (event, eventIndex) => {
+			const subscriberNames = subscribersByEventIndex?.get(eventIndex);
+			const failures = await this.sendEventToSubscribers(event, subscriberNames ?? void 0);
+			for (const failure of failures) failedDeliveries.push({
+				eventIndex,
+				subscriberName: failure.subscriberName,
+				error: failure.error
+			});
+		};
+		if (!this.rateLimiter) {
+			for (const [i, event] of events.entries()) if (event) await sendOne(event, i);
+			return failedDeliveries;
+		}
+		for (const [i, event] of events.entries()) {
+			await this.rateLimiter.waitForToken();
+			if (event) await sendOne(event, i);
+		}
+		return failedDeliveries;
+	}
+	/**
+	* Send a single event to subscribers.
+	* - When subscriberNames is undefined (initial attempt): send to all subscribers.
+	* - When subscriberNames is provided (retry): send only to those subscribers (never re-send to healthy ones).
+	* Returns list of subscribers that failed (empty if all succeeded).
+	*/
+	async sendEventToSubscribers(event, subscriberNames) {
+		const startTime = event.timestamp;
+		const failures = [];
+		const subscribersToTry = subscriberNames === void 0 ? this.subscribers : this.subscribers.filter((s) => subscriberNames.has(getSubscriberName(s)));
+		const results = await Promise.allSettled(subscribersToTry.map(async (subscriber) => {
+			const subscriberName = getSubscriberName(subscriber);
+			try {
+				await subscriber.trackEvent(event.name, event.attributes, {
+					autotel: event.autotel,
+					schema: event.schema
+				});
+				this.recordDelivered(event, subscriberName, startTime);
+				return {
+					subscriberName,
+					success: true
+				};
+			} catch (error) {
+				this.markSubscriberUnhealthy(subscriberName);
+				return {
+					subscriberName,
+					success: false,
+					error: error instanceof Error ? error : void 0
+				};
+			}
+		}));
+		for (const result of results) if (result.status === "fulfilled" && !result.value.success) failures.push({
+			subscriberName: result.value.subscriberName,
+			error: result.value.error
+		});
+		return failures;
+	}
+	/**
+	* Flush all remaining events. Queue remains usable after flush (e.g. for
+	* auto-flush at root span end). Use shutdown() when tearing down the queue.
+	*/
+	async flush() {
+		if (this.flushTimer) {
+			clearTimeout(this.flushTimer);
+			this.flushTimer = null;
+		}
+		if (this.flushPromise) await this.flushPromise;
+		while (this.queue.length > 0) await this.doFlushBatch();
+	}
+	/**
+	* Flush remaining events and permanently disable the queue (reject new events).
+	* Use for process/SDK shutdown; use flush() for periodic or span-end drain.
+	*/
+	async shutdown() {
+		this.isShuttingDown = true;
+		await this.flush();
+		const drains = await Promise.allSettled(this.subscribers.map(async (subscriber) => {
+			if (!subscriber.shutdown) return;
+			shutDownSubscribers.add(subscriber);
+			return subscriber.shutdown();
+		}));
+		for (const [index, drain] of drains.entries()) {
+			if (drain.status !== "rejected") continue;
+			const subscriberName = getSubscriberName(this.subscribers[index]);
+			this.subscriberHealthy.set(subscriberName, false);
+			getLogger().error({
+				subscriber: subscriberName,
+				err: drain.reason
+			}, "[autotel] Subscriber shutdown failed, buffered events may be lost");
+		}
+	}
+	/**
+	* Cleanup observable metric callbacks to prevent memory leaks
+	* Call this when destroying the EventQueue instance
+	*/
+	cleanup() {
+		for (const cleanupFn of this.observableCleanups) try {
+			cleanupFn();
+		} catch {}
+		this.observableCleanups = [];
+	}
+	/**
+	* Get queue size (for testing/debugging)
+	*/
+	size() {
+		return this.queue.length;
+	}
+	/**
+	* Get subscriber health status (for testing/debugging)
+	*/
+	getSubscriberHealth() {
+		return new Map(this.subscriberHealthy);
+	}
+	/**
+	* Check if a specific subscriber is healthy
+	*/
+	isSubscriberHealthy(subscriberName) {
+		return this.subscriberHealthy.get(subscriberName.toLowerCase()) ?? true;
+	}
+	/**
+	* Manually mark a subscriber as healthy or unhealthy
+	* (used for circuit breaker integration)
+	*/
+	setSubscriberHealth(subscriberName, healthy) {
+		this.subscriberHealthy.set(subscriberName.toLowerCase(), healthy);
+	}
+};
+
+//#endregion
+//#region src/validation.ts
+const DEFAULT_CONFIG$1 = {
+	maxEventNameLength: 100,
+	maxAttributeKeyLength: 100,
+	maxAttributeValueLength: 1e3,
+	maxAttributeCount: 50,
+	maxNestingDepth: 3,
+	sensitivePatterns: [
+		/password/i,
+		/secret/i,
+		/token/i,
+		/api[_-]?key/i,
+		/access[_-]?key/i,
+		/private[_-]?key/i,
+		/auth/i,
+		/credential/i,
+		/ssn/i,
+		/credit[_-]?card/i
+	]
+};
+var ValidationError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "ValidationError";
+	}
+};
+/**
+* Validate and sanitize event name
+* Throws ValidationError if invalid
+*/
+function validateEventName(eventName, config = DEFAULT_CONFIG$1) {
+	if (asString(eventName) === void 0) throw new ValidationError(`Event name must be a string, got ${describeValue(eventName)}`);
+	const trimmed = eventName.trim();
+	if (trimmed.length === 0) throw new ValidationError("Event name cannot be empty");
+	if (trimmed.length > config.maxEventNameLength) throw new ValidationError(`Event name too long (${trimmed.length} chars). Max: ${config.maxEventNameLength}`);
+	if (!/^[a-zA-Z0-9._-]+$/.test(trimmed)) throw new ValidationError(`Event name contains invalid characters: "${trimmed}". Use only letters, numbers, dots, underscores, and hyphens.`);
+	return trimmed;
+}
+/**
+* Validate and sanitize attributes
+* Returns sanitized attributes (sensitive data redacted)
+*/
+function validateAttributes(attributes, config = DEFAULT_CONFIG$1) {
+	if (attributes === void 0 || attributes === null) return;
+	if (!asRecord(attributes)) throw new ValidationError("Attributes must be an object");
+	const keys = Object.keys(attributes);
+	if (keys.length > config.maxAttributeCount) throw new ValidationError(`Too many attributes (${keys.length}). Max: ${config.maxAttributeCount}`);
+	const sanitized = {};
+	for (const key of keys) {
+		if (key.length > config.maxAttributeKeyLength) throw new ValidationError(`Attribute key too long: "${key.slice(0, 20)}..." (${key.length} chars). Max: ${config.maxAttributeKeyLength}`);
+		const value = attributes[key];
+		if (isSensitiveString(key, value, config)) {
+			sanitized[key] = "[REDACTED]";
+			continue;
+		}
+		sanitized[key] = sanitizeValue(value, config, 1);
+	}
+	return sanitized;
+}
+/**
+* Whether this key/value pair is a credential to redact. Strings only:
+* numeric and boolean values are not credentials, and replacing them with the
+* literal '[REDACTED]' leaks no signal while breaking every consumer that
+* treats them as a number.
+*/
+function isSensitiveString(key, value, config) {
+	return asString(value) !== void 0 && config.sensitivePatterns.some((pattern) => pattern.test(key));
+}
+/**
+* Sanitize attribute value (recursive)
+*/
+function sanitizeValue(value, config, depth) {
+	if (depth > config.maxNestingDepth) return "[MAX_DEPTH_EXCEEDED]";
+	if (value === null || value === void 0) return value;
+	const text = asString(value);
+	if (text !== void 0) return text.length > config.maxAttributeValueLength ? text.slice(0, config.maxAttributeValueLength) + "..." : text;
+	const scalar = asNumber(value) ?? asBoolean(value);
+	if (scalar !== void 0) return scalar;
+	if (Array.isArray(value)) return value.map((item) => sanitizeValue(item, config, depth + 1));
+	const record = asRecord(value);
+	if (record) try {
+		JSON.stringify(record);
+		const sanitized = {};
+		for (const [key, nested] of Object.entries(record)) sanitized[key] = isSensitiveString(key, nested, config) ? "[REDACTED]" : sanitizeValue(nested, config, depth + 1);
+		return sanitized;
+	} catch {
+		return "[CIRCULAR]";
+	}
+	return `[${describeValue(value)}]`;
+}
+/**
+* Validate and sanitize an events event
+* Returns { eventName, attributes } with sanitized values
+*/
+function validateEvent(eventName, attributes, config) {
+	const fullConfig = {
+		...DEFAULT_CONFIG$1,
+		...config
+	};
+	return {
+		eventName: validateEventName(eventName, fullConfig),
+		attributes: validateAttributes(attributes, fullConfig)
+	};
+}
+
+//#endregion
+//#region src/track.ts
+/**
+* Global track() function for business events
+*
+* Simple, no instantiation needed, auto-attaches trace context
+*/
+let eventsQueue = null;
+/**
+* Build autotel event context for trace correlation
+*
+* Works in multiple contexts:
+* 1. Inside a span → use current span's trace_id + span_id
+* 2. Outside span → use correlation_id only
+* 3. With trace URL config → include clickable trace URL
+*/
+function buildAutotelContext(span) {
+	const eventsConfig = getEventsConfig();
+	const config = getConfig();
+	const correlationId = getOrCreateCorrelationId();
+	if (!eventsConfig?.includeTraceContext) return { correlation_id: correlationId };
+	const autotelContext = { correlation_id: correlationId };
+	const spanContext = span?.spanContext();
+	if (spanContext) {
+		autotelContext.trace_id = spanContext.traceId;
+		autotelContext.span_id = spanContext.spanId;
+		autotelContext.trace_flags = spanContext.traceFlags.toString(16).padStart(2, "0");
+		const traceState = spanContext.traceState;
+		if (traceState) try {
+			if (typeof traceState.serialize === "function") {
+				const traceStateStr = traceState.serialize();
+				if (traceStateStr) autotelContext.trace_state = traceStateStr;
+			}
+		} catch {}
+		if (eventsConfig.traceUrl && config) {
+			const traceUrl = eventsConfig.traceUrl({
+				traceId: spanContext.traceId,
+				spanId: spanContext.spanId,
+				correlationId,
+				serviceName: config.service,
+				environment: config.environment
+			});
+			if (traceUrl) autotelContext.trace_url = traceUrl;
+		}
+	} else if (eventsConfig.traceUrl && config) {
+		const traceUrl = eventsConfig.traceUrl({
+			correlationId,
+			serviceName: config.service,
+			environment: config.environment
+		});
+		if (traceUrl) autotelContext.trace_url = traceUrl;
+	}
+	return autotelContext;
+}
+/**
+* Initialize events queue lazily
+*/
+function getOrCreateQueue() {
+	if (!isInitialized()) {
+		warnIfNotInitialized("track()");
+		return null;
+	}
+	if (!eventsQueue) {
+		const config = getConfig();
+		if (!config?.subscribers || config.subscribers.length === 0) return null;
+		eventsQueue = new EventQueue(config.subscribers);
+	}
+	return eventsQueue;
+}
+/**
+* Track a business events event
+*
+* Features:
+* - Auto-attaches traceId and spanId if in active span
+* - Batched sending with retry
+* - Type-safe with optional generic
+* - No-op if init() not called or no subscribers configured
+*
+* @example Basic usage
+* ```typescript
+* track('user.signup', { userId: '123', plan: 'pro' })
+* ```
+*
+* @example With type safety
+* ```typescript
+* interface EventDatas {
+*   'user.signup': { userId: string; plan: string }
+*   'plan.upgraded': { userId: string; revenue: number }
+* }
+*
+* track<EventDatas>('user.signup', { userId: '123', plan: 'pro' })
+* ```
+*
+* @example Trace correlation (automatic)
+* ```typescript
+* @Instrumented()
+* class UserService {
+*   async createUser(data: CreateUserData) {
+*     // This track call automatically includes traceId + spanId
+*     track('user.signup', { userId: data.id })
+*   }
+* }
+* ```
+*/
+function track(event, data, options) {
+	const queue = getOrCreateQueue();
+	if (!queue) return;
+	const validated = validateEvent(event, data, getValidationConfig() || void 0);
+	const span = trace.getActiveSpan();
+	const enrichedData = span ? {
+		...validated.attributes,
+		traceId: span.spanContext().traceId,
+		spanId: span.spanContext().spanId
+	} : validated.attributes;
+	const autotelContext = buildAutotelContext(span);
+	queue.enqueue({
+		name: validated.eventName,
+		attributes: enrichedData,
+		timestamp: Date.now(),
+		autotel: autotelContext,
+		schema: options?.schema
+	});
+}
+/**
+* Get events queue (for flush/shutdown)
+* @internal
+*/
+function getEventQueue() {
+	return eventsQueue;
+}
+/**
+* Reset events queue (for shutdown/cleanup)
+* @internal
+*/
+function resetEventQueue() {
+	eventsQueue = null;
+}
+
+//#endregion
+//#region src/trace-context.ts
+const spansWithExplicitStatus = /* @__PURE__ */ new WeakSet();
+/** Whether a TraceContext consumer explicitly chose this span's status. */
+function hasExplicitSpanStatus(span) {
+	return spansWithExplicitStatus.has(span);
+}
+/**
+* AsyncLocalStorage for storing the active context with baggage
+* This allows setters to update the context and have it persist
+*/
+const contextStorage = new nodeAsyncHooks.AsyncLocalStorage();
+/**
+* Get the context storage instance (for initialization in functional.ts)
+*/
+function getContextStorage() {
+	return contextStorage;
+}
+/**
+* Get the active OTel context with the latest stored baggage overlaid.
+* Span identity always comes from the active OTel scope.
+*/
+function getActiveContextWithBaggage() {
+	const activeContext = context.active();
+	const stored = contextStorage.getStore()?.value;
+	if (!stored) return activeContext;
+	const storedBaggage = propagation.getBaggage(stored);
+	return storedBaggage ? propagation.setBaggage(activeContext, storedBaggage) : activeContext;
+}
+/**
+* Set a value in AsyncLocalStorage, preferring enterWith() when available
+* (Node.js) and falling back to run() for environments that only support
+* run() (e.g. Cloudflare Workers).
+*
+* On runtimes without enterWith() we mutate the existing run() scope when one
+* exists. This is what allows baggage/correlation updates to remain visible
+* for the rest of the traced callback in Workers.
+*/
+function enterOrRun(storage, value) {
+	const existingStore = storage.getStore();
+	if (existingStore) {
+		existingStore.value = value;
+		return;
+	}
+	const boxedValue = { value };
+	try {
+		storage.enterWith(boxedValue);
+	} catch {
+		storage.run(boxedValue, () => {});
+	}
+}
+function updateActiveContext(newContext) {
+	enterOrRun(contextStorage, newContext);
+	const manager = context._getContextManager?.();
+	if (!manager) return;
+	const asyncLocal = manager._asyncLocalStorage ?? void 0;
+	if (asyncLocal?.enterWith) {
+		asyncLocal.enterWith(newContext);
+		return;
+	}
+	if (isFunction(manager.with)) manager.with(newContext, () => {});
+}
+/**
+* Create a TraceContext from an OpenTelemetry Span
+*
+* This utility extracts trace context information from a span
+* and provides span manipulation methods and baggage operations in a consistent format.
+*
+* Note: Baggage methods always operate on the currently active context,
+* which may differ from the context when createTraceContext was called.
+*/
+function createTraceContext(span) {
+	const spanContext = span.spanContext();
+	if (!contextStorage.getStore()?.value) {
+		const activeContext = context.active();
+		enterOrRun(contextStorage, activeContext);
+	}
+	const traceCtx = {
+		traceId: spanContext.traceId,
+		spanId: spanContext.spanId,
+		correlationId: spanContext.traceId.slice(0, 16),
+		setAttribute: span.setAttribute.bind(span),
+		setAttributes: span.setAttributes.bind(span),
+		setStatus: (status) => {
+			spansWithExplicitStatus.add(span);
+			span.setStatus(status);
+		},
+		recordException: span.recordException.bind(span),
+		addEvent: span.addEvent.bind(span),
+		addLink: span.addLink.bind(span),
+		addLinks: span.addLinks.bind(span),
+		updateName: span.updateName.bind(span),
+		isRecording: span.isRecording.bind(span),
+		recordError: (cause) => {
+			const err = cause instanceof Error ? cause : new Error(String(cause));
+			recordStructuredError(traceCtx, err);
+		},
+		track: (event, data) => {
+			track(event, data);
+		},
+		getBaggage(key) {
+			const activeCtx = context.active();
+			let baggage = propagation.getBaggage(activeCtx);
+			if (!baggage) {
+				const storedContext = contextStorage.getStore()?.value;
+				if (storedContext) baggage = propagation.getBaggage(storedContext);
+			}
+			return baggage?.getEntry(key)?.value;
+		},
+		setBaggage(key, value) {
+			const currentContext = getActiveContextWithBaggage();
+			const updated = (propagation.getBaggage(currentContext) ?? propagation.createBaggage()).setEntry(key, { value });
+			updateActiveContext(propagation.setBaggage(currentContext, updated));
+			return value;
+		},
+		deleteBaggage(key) {
+			const currentContext = getActiveContextWithBaggage();
+			const baggage = propagation.getBaggage(currentContext);
+			if (baggage) {
+				const updated = baggage.removeEntry(key);
+				updateActiveContext(propagation.setBaggage(currentContext, updated));
 			}
 		},
 		getAllBaggage() {
@@ -818,820 +1162,1345 @@ function defineBaggageSchema(namespace) {
 }
 
 //#endregion
-//#region src/correlation-id.ts
-/**
-* Correlation ID utilities for event-driven observability
-*
-* Provides a stable join key across events, logs, and spans even when traces fragment.
-* Format: 16 hex chars (64 bits), crypto-random, URL-safe.
-*
-* Lifecycle:
-* 1. Generated at boundary root (HTTP server span, message process span, cron job span)
-* 2. Reused within context (nested work shares it via AsyncLocalStorage)
-* 3. Propagated via baggage (optional, default OFF to avoid header bloat)
-*
-* @example Basic usage
-* ```typescript
-* import { generateCorrelationId, getCorrelationId } from 'autotel/correlation-id';
-*
-* // Generate a new correlation ID
-* const id = generateCorrelationId();
-* // Returns: 'a1b2c3d4e5f67890'
-*
-* // Get current correlation ID from context
-* const currentId = getCorrelationId();
-* ```
-*/
-/**
-* AsyncLocalStorage for storing correlation ID
-* This allows correlation IDs to persist across async boundaries
-*/
-const correlationStorage = new nodeAsyncHooks.AsyncLocalStorage();
-/**
-* Baggage key for correlation ID propagation
-*/
-const CORRELATION_ID_BAGGAGE_KEY = "autotel.correlation_id";
-/**
-* Generate a new correlation ID
-*
-* Format: 16 hex chars (64 bits), crypto-random, URL-safe
-*
-* @returns A new correlation ID
-*
-* @example
-* ```typescript
-* const id = generateCorrelationId();
-* // Returns: 'a1b2c3d4e5f67890'
-* ```
-*/
-function generateCorrelationId() {
-	const bytes = /* @__PURE__ */ new Uint8Array(8);
-	crypto.getRandomValues(bytes);
-	return [...bytes].map((b) => b.toString(16).padStart(2, "0")).join("");
-}
+//#region src/sampling.ts
 /**
-* Get the current correlation ID from context
-*
-* Resolution order:
-* 1. AsyncLocalStorage (from explicit setCorrelationId or runWithCorrelationId)
-* 2. Baggage (if propagated from upstream)
-* 3. Active span's trace ID (first 16 chars as fallback)
-* 4. undefined (if not in any context)
-*
-* @returns Current correlation ID or undefined
-*
-* @example
-* ```typescript
-* const id = getCorrelationId();
-* if (id) {
-*   console.log('Correlation ID:', id);
-* }
-* ```
+* Tail sampling attribute keys (autotel-internal, not OTel semconv)
 */
-function getCorrelationId() {
-	const storedId = correlationStorage.getStore()?.value;
-	if (storedId) return storedId;
-	const activeContext = context.active();
-	const baggageEntry = propagation.getBaggage(activeContext)?.getEntry(CORRELATION_ID_BAGGAGE_KEY);
-	if (baggageEntry?.value) return baggageEntry.value;
-	const span = trace.getActiveSpan();
-	if (span) return span.spanContext().traceId.slice(0, 16);
-}
+const AUTOTEL_SAMPLING_TAIL_KEEP = "autotel.sampling.tail.keep";
+const AUTOTEL_SAMPLING_TAIL_EVALUATED = "autotel.sampling.tail.evaluated";
 /**
-* Get or create a correlation ID
-*
-* If a correlation ID exists in the current context, returns it.
-* Otherwise, generates a new one.
-*
-* @returns Existing or new correlation ID
-*
-* @example
-* ```typescript
-* const id = getOrCreateCorrelationId();
-* // Always returns a valid correlation ID
-* ```
+* How many events each kept event stands for, expressed as "1 in N".
+*
+* A query that counts sampled spans undercounts the population. Multiplying
+* each kept event by this rate restores the estimate. Autotel records the
+* attribute only when N exceeds 1, so fully captured spans stay clean.
 */
-function getOrCreateCorrelationId() {
-	return getCorrelationId() ?? generateCorrelationId();
-}
+const AUTOTEL_SAMPLING_RATE = "autotel.sampling.rate";
 /**
-* Run a function with a specific correlation ID in context
+* Spans an explicit `forceKeep()` claimed.
 *
-* The correlation ID will be available via getCorrelationId() throughout
-* the execution of the function and any async operations it spawns.
+* The tracing wrapper writes the sampler's tail verdict once the body has
+* run, which is after any `forceKeep()` inside it. Without this the verdict
+* overwrites the override and the span the caller insisted on is dropped.
+*/
+/**
+* Baggage key that turns on full-fidelity capture for a request.
 *
-* @param correlationId - Correlation ID to use
-* @param fn - Function to execute
-* @returns The return value of the function
+* Baggage arrives on the request and propagates, so a gateway, a proxy, a
+* feature flag or a curl can turn this on for one user and it follows them
+* across every service. Nobody deploys anything to debug a live problem.
+*/
+const AUTOTEL_DEBUG_BAGGAGE_KEY = "autotel.debug";
+const forceKeptSpans = /* @__PURE__ */ new WeakSet();
+function markForceKept(span) {
+	forceKeptSpans.add(span);
+}
+function isForceKept(span) {
+	return forceKeptSpans.has(span);
+}
+/**
+* Convert a keep probability into the "1 in N" rate reported on spans.
 *
-* @example
-* ```typescript
-* await runWithCorrelationId('abc123', async () => {
-*   // getCorrelationId() returns 'abc123' here
-*   await processRequest();
-* });
-* ```
+* Keeping 10% of traces means each survivor stands for 10, so the two numbers
+* are reciprocals and easy to publish the wrong way round.
 */
-function runWithCorrelationId(correlationId, fn) {
-	return correlationStorage.run({ value: correlationId }, fn);
+function toSampleRate(probability) {
+	return probability > 0 ? 1 / probability : 0;
 }
 /**
-* Set correlation ID in the current context (mutates context)
+* Map a string to a stable, evenly spread position in the unit interval.
 *
-* Note: This updates the AsyncLocalStorage context. For proper scoping
-* across async boundaries, prefer runWithCorrelationId() instead.
+* Two processes that hash the same key reach the same number, which is what
+* lets independent services agree on one trace's sampling decision.
 *
-* @param correlationId - Correlation ID to set
+* The spread matters as much as the stability. Real sampling keys share long
+* prefixes: `user_1000`, `user_1001`, `checkout-trace-0001`. A plain
+* multiply-and-add hash lets that shared prefix dominate the high bits, so a
+* whole key family lands in one narrow band and a rate of 0.1 keeps all of
+* them or none of them. FNV-1a followed by the murmur3 finalizer mixes the
+* low bits back through the word, so keys that differ in one character land
+* far apart.
+*/
+function hashUnitInterval(value) {
+	let hash = 2166136261;
+	for (let i = 0; i < value.length; i++) {
+		hash ^= value.codePointAt(i) ?? 0;
+		hash = Math.imul(hash, 16777619);
+	}
+	hash ^= hash >>> 16;
+	hash = Math.imul(hash, 2246822507);
+	hash ^= hash >>> 13;
+	hash = Math.imul(hash, 3266489909);
+	hash ^= hash >>> 16;
+	return (hash >>> 0) / 4294967296;
+}
+/**
+* Simple random sampler
 *
 * @example
 * ```typescript
-* setCorrelationId('abc123');
-* // Now getCorrelationId() returns 'abc123'
+* new RandomSampler(0.1) // Sample 10% of requests
 * ```
 */
-function setCorrelationId(correlationId) {
-	enterOrRun(correlationStorage, correlationId);
-}
+var RandomSampler = class {
+	rate;
+	constructor(rate) {
+		this.rate = rate;
+		if (rate < 0 || rate > 1) throw new Error("Sample rate must be between 0 and 1");
+	}
+	shouldSample(_context) {
+		return Math.random() < this.rate;
+	}
+	sampleRate() {
+		return toSampleRate(this.rate);
+	}
+};
 /**
-* Set correlation ID in baggage for propagation
+* Always sample (100% tracing)
+*/
+var AlwaysSampler = class {
+	shouldSample(_context) {
+		return true;
+	}
+};
+/**
+* Never sample (0% tracing)
+*/
+var NeverSampler = class {
+	shouldSample(_context) {
+		return false;
+	}
+};
+/**
+* Adaptive sampler that always traces errors and slow requests
 *
-* This adds the correlation ID to the W3C baggage header, allowing it
-* to be propagated to downstream services.
+* This is the recommended sampler for production use.
+* It ensures you never miss critical issues while keeping costs down.
 *
-* Note: Only use this when you explicitly want cross-service propagation.
-* Default is OFF to avoid header bloat.
+* Strategy:
+* - Always trace errors (critical for debugging)
+* - Always trace slow requests (performance issues)
+* - Use baseline sample rate for successful fast requests
 *
-* @param correlationId - Correlation ID to propagate
-* @returns New context with baggage set
+* **IMPORTANT - Tail Sampling Requirement:**
+* This sampler uses tail sampling (makes decisions AFTER execution).
+* You MUST use TailSamplingSpanProcessor for it to work correctly:
+*
+* - If using initInstrumentation(): TailSamplingSpanProcessor is auto-configured
+* - If using custom TracerProvider: You MUST manually register TailSamplingSpanProcessor
+*
+* Without TailSamplingSpanProcessor, ALL spans are exported (defeating the cost savings).
+*
+* @see TailSamplingSpanProcessor
+* @see README.md "Tail Sampling with Custom Providers" section
 *
 * @example
 * ```typescript
-* const newContext = setCorrelationIdInBaggage('abc123');
-* context.with(newContext, () => {
-*   // Baggage will be propagated in outgoing requests
-* });
+* new AdaptiveSampler({
+*   baselineSampleRate: 0.1,    // 10% of normal requests
+*   slowThresholdMs: 1000,       // Requests > 1s are "slow"
+*   alwaysSampleErrors: true,    // Always trace errors
+*   alwaysSampleSlow: true       // Always trace slow requests
+* })
 * ```
 */
-function setCorrelationIdInBaggage(correlationId) {
-	const activeContext = context.active();
-	let baggage = propagation.getBaggage(activeContext) ?? propagation.createBaggage();
-	baggage = baggage.setEntry(CORRELATION_ID_BAGGAGE_KEY, { value: correlationId });
-	return propagation.setBaggage(activeContext, baggage);
-}
-/**
-* Get the correlation storage instance (for internal use in init/shutdown)
-*/
-function getCorrelationStorage() {
-	return correlationStorage;
-}
-
-//#endregion
-//#region src/event-queue.ts
-const DEFAULT_CONFIG$2 = {
-	maxSize: 5e4,
-	batchSize: 100,
-	flushInterval: 1e4,
-	maxRetries: 3,
-	rateLimit: {
-		maxEventsPerSecond: 100,
-		burstCapacity: 200
+var AdaptiveSampler = class {
+	baselineSampleRate;
+	slowThresholdMs;
+	alwaysSampleErrors;
+	alwaysSampleSlow;
+	linksBased;
+	linksRate;
+	logger;
+	samplingDecisions = /* @__PURE__ */ new WeakMap();
+	operationResults = /* @__PURE__ */ new WeakMap();
+	constructor(options = {}) {
+		this.baselineSampleRate = options.baselineSampleRate ?? .1;
+		this.slowThresholdMs = options.slowThresholdMs ?? 1e3;
+		this.alwaysSampleErrors = options.alwaysSampleErrors ?? true;
+		this.alwaysSampleSlow = options.alwaysSampleSlow ?? true;
+		this.linksBased = options.linksBased ?? false;
+		this.linksRate = options.linksRate ?? 1;
+		this.logger = options.logger;
+		if (this.baselineSampleRate < 0 || this.baselineSampleRate > 1) throw new Error("Baseline sample rate must be between 0 and 1");
+		if (this.linksRate < 0 || this.linksRate > 1) throw new Error("Links rate must be between 0 and 1");
+	}
+	needsTailSampling() {
+		return true;
+	}
+	shouldSample(context) {
+		const baselineDecision = Math.random() < this.baselineSampleRate;
+		this.samplingDecisions.set(context.args, baselineDecision);
+		return true;
+	}
+	/**
+	* Check if any links point to sampled spans.
+	*
+	* A span is considered linked to a sampled span if any of its links
+	* have trace_flags with the sampled bit set (0x01).
+	*
+	* @param links - Array of span links to check
+	* @returns true if any linked span is sampled, false otherwise
+	*/
+	hasSampledLink(links) {
+		if (!links || links.length === 0) return false;
+		return links.some((link) => link.context && (link.context.traceFlags & TraceFlags.SAMPLED) !== 0);
+	}
+	/**
+	* Re-evaluate sampling decision after operation completes
+	*
+	* This allows us to always capture errors and slow requests,
+	* even if they weren't initially sampled.
+	*
+	* @param context - Sampling context
+	* @param result - Operation result
+	* @returns true if this operation should be kept (not discarded)
+	*/
+	shouldKeepTrace(context, result) {
+		const baselineDecision = this.samplingDecisions.get(context.args) ?? false;
+		if (this.alwaysSampleErrors && !result.success) {
+			if (!baselineDecision) this.logger?.debug({
+				operation: context.operationName,
+				error: result.error?.message
+			}, "Adaptive sampling: Keeping error trace");
+			return true;
+		}
+		if (this.alwaysSampleSlow && result.duration >= this.slowThresholdMs) {
+			if (!baselineDecision) this.logger?.debug({
+				operation: context.operationName,
+				duration: result.duration
+			}, "Adaptive sampling: Keeping slow trace");
+			return true;
+		}
+		if (this.linksBased && context.links && this.hasSampledLink(context.links)) {
+			const keepLinked = Math.random() < this.linksRate;
+			if (keepLinked && !baselineDecision) this.logger?.debug({
+				operation: context.operationName,
+				linkCount: context.links.length
+			}, "Adaptive sampling: Keeping trace due to sampled link");
+			return keepLinked;
+		}
+		return baselineDecision;
 	}
 };
 /**
-* Get subscriber name for metrics (stable, low-cardinality)
+* User-based sampler for consistent tracing
 *
-* Priority:
-* 1. Explicit config: subscriber.name
-* 2. Class static property (if available)
-* 3. Fallback: lowercase class name without "Subscriber" suffix
-*/
-function getSubscriberName(subscriber) {
-	if (subscriber.name) return subscriber.name.toLowerCase();
-	return (subscriber.constructor?.name || "unknown").replace(/Subscriber$/i, "").toLowerCase();
-}
-/**
-* Subscribers whose `shutdown()` has run. Terminal for the client they wrap, so
-* a queue rebuilt from the same config must not reuse them.
-*/
-const shutDownSubscribers = /* @__PURE__ */ new WeakSet();
-/**
-* Events queue with batching and backpressure
+* Always samples requests from specific user IDs.
+* Useful for debugging specific user issues or monitoring VIP users.
 *
-* Features:
-* - Batches events for efficient sending
-* - Bounded queue with drop-oldest policy (prod) or blocking (dev)
-* - Exponential backoff retry
-* - Rate limiting to prevent overwhelming subscribers
-* - Graceful flush on shutdown
+* @example
+* ```typescript
+* new UserIdSampler({
+*   baselineSampleRate: 0.01,      // 1% of normal users
+*   alwaysSampleUsers: ['vip_123'], // Always trace VIP users
+*   extractUserId: (args) => args[0]?.userId // Extract user ID from first arg
+* })
+* ```
 */
-var EventQueue = class {
-	queue = [];
-	flushTimer = null;
-	config;
-	subscribers;
-	rateLimiter;
-	flushPromise = null;
-	isShuttingDown = false;
-	metrics = null;
-	observableCleanups = [];
-	subscriberHealthy = /* @__PURE__ */ new Map();
-	constructor(subscribers, config) {
-		const live = subscribers.filter((s) => !shutDownSubscribers.has(s));
-		if (live.length < subscribers.length) getLogger().warn({ subscribers: subscribers.filter((s) => shutDownSubscribers.has(s)).map((s) => getSubscriberName(s)) }, "[autotel] Subscriber already shut down, events will not be delivered; pass new subscriber instances to init()");
-		this.subscribers = live;
-		this.config = {
-			...DEFAULT_CONFIG$2,
-			...config
-		};
-		this.rateLimiter = this.config.rateLimit ? new TokenBucketRateLimiter(this.config.rateLimit) : null;
-		for (const subscriber of this.subscribers) {
-			const name = getSubscriberName(subscriber);
-			this.subscriberHealthy.set(name, true);
+var UserIdSampler = class {
+	baselineSampleRate;
+	alwaysSampleUsers;
+	extractUserId;
+	logger;
+	constructor(options) {
+		this.baselineSampleRate = options.baselineSampleRate ?? .1;
+		this.alwaysSampleUsers = new Set(options.alwaysSampleUsers || []);
+		this.extractUserId = options.extractUserId;
+		this.logger = options.logger;
+	}
+	shouldSample(context) {
+		const userId = this.extractUserId(context.args);
+		if (userId && this.alwaysSampleUsers.has(userId)) {
+			this.logger?.debug({
+				operation: context.operationName,
+				userId
+			}, "Sampling user request");
+			return true;
 		}
-		this.initMetrics();
+		if (userId) return this.hashString(userId) < this.baselineSampleRate;
+		return Math.random() < this.baselineSampleRate;
 	}
 	/**
-	* Initialize OTel metrics for queue observability
+	* Add user IDs to always-sample list
 	*/
-	initMetrics() {
-		const meter = getConfig$1().meter;
-		const queueSize = meter.createObservableGauge("autotel.event_delivery.queue.size", {
-			description: "Current number of events in the delivery queue",
-			unit: "count"
-		});
-		const queueSizeCallback = (observableResult) => {
-			observableResult.observe(this.queue.length);
-		};
-		queueSize.addCallback(queueSizeCallback);
-		this.observableCleanups.push(() => queueSize.removeCallback(queueSizeCallback));
-		const oldestAge = meter.createObservableGauge("autotel.event_delivery.queue.oldest_age_ms", {
-			description: "Age of the oldest event in the queue in milliseconds",
-			unit: "ms"
-		});
-		const oldestAgeCallback = (observableResult) => {
-			if (this.queue.length > 0) {
-				const oldest = this.queue[0];
-				const ageMs = Date.now() - oldest.timestamp;
-				observableResult.observe(ageMs);
-			} else observableResult.observe(0);
-		};
-		oldestAge.addCallback(oldestAgeCallback);
-		this.observableCleanups.push(() => oldestAge.removeCallback(oldestAgeCallback));
-		const delivered = meter.createCounter("autotel.event_delivery.queue.delivered", {
-			description: "Number of events successfully delivered to subscribers",
-			unit: "count"
-		});
-		const failed = meter.createCounter("autotel.event_delivery.queue.failed", {
-			description: "Number of events that failed delivery after all retry attempts",
-			unit: "count"
-		});
-		const dropped = meter.createCounter("autotel.event_delivery.queue.dropped", {
-			description: "Number of events dropped from the queue",
-			unit: "count"
-		});
-		const latency = meter.createHistogram("autotel.event_delivery.queue.latency_ms", {
-			description: "Event delivery latency from enqueue to successful send",
-			unit: "ms"
-		});
-		const subscriberHealth = meter.createObservableGauge("autotel.event_delivery.subscriber.health", {
-			description: "Subscriber health status (1=healthy, 0=unhealthy)",
-			unit: "1"
-		});
-		const subscriberHealthCallback = (observableResult) => {
-			for (const [subscriberName, isHealthy] of this.subscriberHealthy) observableResult.observe(isHealthy ? 1 : 0, { subscriber: subscriberName });
-		};
-		subscriberHealth.addCallback(subscriberHealthCallback);
-		this.observableCleanups.push(() => subscriberHealth.removeCallback(subscriberHealthCallback));
-		this.metrics = {
-			queueSize,
-			oldestAge,
-			delivered,
-			failed,
-			dropped,
-			latency,
-			subscriberHealth
-		};
+	addAlwaysSampleUsers(...userIds) {
+		for (const userId of userIds) this.alwaysSampleUsers.add(userId);
 	}
 	/**
-	* Record a dropped event with reason and emit debug breadcrumb
+	* Remove user IDs from always-sample list
 	*/
-	recordDropped(reason, event, subscriberName) {
-		const attrs = { reason };
-		if (subscriberName) attrs.subscriber = subscriberName;
-		this.metrics?.dropped.add(1, attrs);
-		const logLevel = reason === "payload_invalid" ? "error" : "warn";
-		const logger = getLogger();
-		if (logLevel === "error") logger.error({
-			eventName: event?.name,
-			subscriber: subscriberName,
-			reason,
-			correlationId: event?._correlationId,
-			traceId: event?._traceId
-		}, `[autotel] Event dropped: ${reason}`);
-		else logger.warn({
-			eventName: event?.name,
-			subscriber: subscriberName,
-			reason,
-			correlationId: event?._correlationId,
-			traceId: event?._traceId
-		}, `[autotel] Event dropped: ${reason}`);
+	removeAlwaysSampleUsers(...userIds) {
+		for (const userId of userIds) this.alwaysSampleUsers.delete(userId);
+	}
+	/**
+	* Simple hash function for consistent user sampling
+	*/
+	hashString(str) {
+		return hashUnitInterval(str);
+	}
+};
+/**
+* Consistent sampler: every service reaches the same verdict for one trace.
+*
+* `RandomSampler` rolls the dice per process, so an upstream service can keep
+* a trace that its downstream drops, leaving a waterfall with holes in it.
+* Hashing a key that travels with the request removes the disagreement. Pass
+* the trace id, or any identifier every hop already shares.
+*
+* @example
+* ```typescript
+* new DeterministicSampler({
+*   sampleRate: 0.1,
+*   key: (context) => trace.getActiveSpan()?.spanContext().traceId,
+* })
+* ```
+*/
+var DeterministicSampler = class {
+	rate;
+	key;
+	constructor(options) {
+		if (options.sampleRate < 0 || options.sampleRate > 1) throw new Error("Sample rate must be between 0 and 1");
+		this.rate = options.sampleRate;
+		this.key = options.key;
+	}
+	shouldSample(context) {
+		const key = this.key(context);
+		if (key === void 0) return Math.random() < this.rate;
+		return hashUnitInterval(key) < this.rate;
+	}
+	sampleRate() {
+		return toSampleRate(this.rate);
+	}
+};
+/** Bucket for keys seen after the tracked map fills up. */
+const OVERFLOW_KEY = "__overflow__";
+/**
+* Per-key target-rate sampler for workloads with uneven traffic.
+*
+* A single rate serves a skewed workload badly: 1% floods storage with the
+* busiest endpoint and still loses the rare tenant whose failures you need.
+* This sampler counts traffic per key over a rolling window, then sets each
+* key its own rate so every key contributes roughly `targetPerKey` events.
+* Quiet keys survive intact; loud keys get thinned.
+*
+* The first window keeps everything, because no traffic history exists yet.
+* Rates take effect from the second window onward.
+*
+* @example
+* ```typescript
+* new KeyTargetRateSampler({
+*   key: (context) => context.operationName,
+*   targetPerKey: 10,     // ~10 events per key per window
+*   windowMs: 30_000,
+* })
+* ```
+*/
+var KeyTargetRateSampler = class {
+	key;
+	targetPerKey;
+	windowMs;
+	maxKeys;
+	counts = /* @__PURE__ */ new Map();
+	rates = /* @__PURE__ */ new Map();
+	windowStart = Date.now();
+	constructor(options) {
+		this.key = options.key;
+		this.targetPerKey = options.targetPerKey ?? 10;
+		this.windowMs = options.windowMs ?? 3e4;
+		this.maxKeys = options.maxKeys ?? 1e3;
+		if (this.targetPerKey <= 0) throw new Error("Target per key must be greater than 0");
+		if (this.windowMs <= 0) throw new Error("Window must be greater than 0");
+	}
+	/** Turn the window's observed counts into the next window's rates. */
+	roll(now) {
+		if (now - this.windowStart < this.windowMs) return;
+		const rates = /* @__PURE__ */ new Map();
+		for (const [key, count] of this.counts) rates.set(key, Math.max(1, count / this.targetPerKey));
+		this.rates = rates;
+		this.counts = /* @__PURE__ */ new Map();
+		this.windowStart = now;
 	}
 	/**
-	* Record permanent delivery failure (after all retries exhausted)
-	* Increments failed counter and logs error
+	* Resolve the key, collapsing into one bucket once the map is full.
+	*
+	* An unbounded key function would otherwise grow the map without limit,
+	* which turns a sampler meant to cut cost into a memory leak.
 	*/
-	recordFailed(event, subscriberName, error) {
-		this.metrics?.failed.add(1, { subscriber: subscriberName });
-		this.subscriberHealthy.set(subscriberName, false);
-		getLogger().error({
-			eventName: event.name,
-			subscriber: subscriberName,
-			correlationId: event._correlationId,
-			traceId: event._traceId,
-			err: error
-		}, `[autotel] Event delivery failed after all retries`);
+	resolveKey(context) {
+		const key = this.key(context) ?? OVERFLOW_KEY;
+		if (this.counts.has(key) || this.counts.size < this.maxKeys) return key;
+		return OVERFLOW_KEY;
+	}
+	shouldSample(context) {
+		this.roll(Date.now());
+		const key = this.resolveKey(context);
+		this.counts.set(key, (this.counts.get(key) ?? 0) + 1);
+		const rate = this.rates.get(key) ?? 1;
+		return rate <= 1 || Math.random() < 1 / rate;
+	}
+	sampleRate(context) {
+		return this.rates.get(this.resolveKey(context)) ?? 1;
+	}
+};
+/**
+* Composite sampler that combines multiple samplers
+*
+* Samples if ANY of the child samplers returns true.
+*
+* @example
+* ```typescript
+* new CompositeSampler([
+*   new UserIdSampler({ extractUserId: (args) => args[0]?.userId }),
+*   new AdaptiveSampler({ baselineSampleRate: 0.1 })
+* ])
+* ```
+*/
+var CompositeSampler = class {
+	samplers;
+	constructor(samplers) {
+		this.samplers = samplers;
+		if (samplers.length === 0) throw new Error("CompositeSampler requires at least one child sampler");
+	}
+	shouldSample(context) {
+		return this.samplers.some((sampler) => sampler.shouldSample(context));
+	}
+};
+/**
+* Feature flag sampler
+*
+* Always samples requests with specific feature flags enabled.
+* Perfect for correlating A/B test experiments with metrics.
+*
+* @example
+* ```typescript
+* new FeatureFlagSampler({
+*   baselineSampleRate: 0.01,
+*   alwaysSampleFlags: ['new_checkout', 'experimental_ui'],
+*   extractFlags: (args, metadata) => metadata?.featureFlags
+* })
+* ```
+*/
+var FeatureFlagSampler = class {
+	baselineSampleRate;
+	alwaysSampleFlags;
+	extractFlags;
+	logger;
+	constructor(options) {
+		this.baselineSampleRate = options.baselineSampleRate ?? .1;
+		this.alwaysSampleFlags = new Set(options.alwaysSampleFlags || []);
+		this.extractFlags = options.extractFlags;
+		this.logger = options.logger;
+	}
+	shouldSample(context) {
+		const flags = this.extractFlags(context.args, context.metadata);
+		if (flags && flags.some((flag) => this.alwaysSampleFlags.has(flag))) {
+			this.logger?.debug({
+				operation: context.operationName,
+				flags
+			}, "Sampling feature flag request");
+			return true;
+		}
+		return Math.random() < this.baselineSampleRate;
 	}
 	/**
-	* Mark subscriber as unhealthy on transient failure (without incrementing failed counter)
-	* Used during retry attempts - only recordFailed should increment the counter
+	* Add feature flags to always-sample list
 	*/
-	markSubscriberUnhealthy(subscriberName) {
-		this.subscriberHealthy.set(subscriberName, false);
+	addAlwaysSampleFlags(...flags) {
+		for (const flag of flags) this.alwaysSampleFlags.add(flag);
 	}
 	/**
-	* Record successful delivery
+	* Remove feature flags from always-sample list
 	*/
-	recordDelivered(event, subscriberName, startTime) {
-		const latencyMs = Date.now() - startTime;
-		this.metrics?.delivered.add(1, { subscriber: subscriberName });
-		this.metrics?.latency.record(latencyMs, { subscriber: subscriberName });
-		this.subscriberHealthy.set(subscriberName, true);
+	removeAlwaysSampleFlags(...flags) {
+		for (const flag of flags) this.alwaysSampleFlags.delete(flag);
 	}
+};
+/**
+* Sampling preset factories.
+*
+* For most users, the string shorthand on `init()` is simpler:
+* ```typescript
+* init({ service: 'my-app', sampling: 'production' })
+* ```
+*
+* Use factories when you need to customize:
+* ```typescript
+* init({ service: 'my-app', sampler: samplingPresets.production({ baselineSampleRate: 0.05 }) })
+* ```
+*/
+const samplingPresets = {
+	/** Capture everything — best for local development and debugging */
+	development: () => new AlwaysSampler(),
+	/** Only bad outcomes — zero baseline, errors always kept */
+	errorsOnly: () => new AdaptiveSampler({
+		baselineSampleRate: 0,
+		alwaysSampleErrors: true
+	}),
 	/**
-	* Enqueue an event for sending
-	*
-	* Backpressure policy:
-	* - Drops oldest event and logs warning if queue is full (same behavior in all environments)
+	* Balanced production defaults — 10% baseline + errors + slow traces.
+	* Pass overrides to tune (uses the same option names as AdaptiveSampler).
 	*/
-	enqueue(event) {
-		if (this.isShuttingDown) {
-			this.recordDropped("shutdown", event);
-			return;
+	production: (overrides) => new AdaptiveSampler({
+		baselineSampleRate: .1,
+		alwaysSampleErrors: true,
+		alwaysSampleSlow: true,
+		slowThresholdMs: 1e3,
+		...overrides
+	}),
+	/** Disable sampling entirely */
+	off: () => new NeverSampler()
+};
+/**
+* Resolve a preset string to a Sampler instance.
+* Used internally by `init()` when `sampling` string is provided.
+*
+* @throws Error if preset is not recognized
+*/
+function resolveSamplingPreset(preset) {
+	switch (preset) {
+		case "development": return samplingPresets.development();
+		case "errors-only": return samplingPresets.errorsOnly();
+		case "production": return samplingPresets.production();
+		case "off": return samplingPresets.off();
+		default: throw new Error(`Unknown sampling preset: "${preset}". Valid presets: development, errors-only, production, off`);
+	}
+}
+/**
+* Create a Link from W3C trace context headers (e.g., from a message queue).
+*
+* This is useful for message consumers that need to link to the producer span.
+* The headers should contain at least a `traceparent` header in W3C format.
+*
+* @param headers - Dictionary containing traceparent/tracestate headers
+* @param attributes - Optional attributes for the link
+* @returns Link object if context could be extracted, null otherwise
+*
+* @example
+* ```typescript
+* // In a Kafka consumer
+* const headers = { traceparent: '00-abc123...-def456...-01' };
+* const link = createLinkFromHeaders(headers);
+* if (link) {
+*   // Use with tracer.startActiveSpan options or ctx.addLink()
+*   tracer.startActiveSpan('process.message', { links: [link] }, span => { ... });
+* }
+* ```
+*/
+function createLinkFromHeaders(headers, attributes) {
+	const traceparent = headers.traceparent || headers["traceparent"];
+	if (!traceparent) return null;
+	const spanContext = parseTraceparent(traceparent);
+	if (!spanContext || !isValidSpanContext(spanContext)) return null;
+	return {
+		context: spanContext,
+		attributes: attributes ?? {}
+	};
+}
+/**
+* Extract Links from a batch of messages for fan-in scenarios.
+*
+* Useful for batch processing where multiple producer spans should be linked.
+* This enables tracing causality in event-driven architectures where a single
+* consumer processes messages from multiple producers.
+*
+* @param messages - List of message objects
+* @param headersKey - Key in each message containing trace headers (default: 'headers')
+* @returns List of Link objects for all valid trace contexts
+*
+* @example
+* ```typescript
+* // Processing a batch of SQS/Kafka messages
+* const messages = [
+*   { body: '...', headers: { traceparent: '...' } },
+*   { body: '...', headers: { traceparent: '...' } },
+* ];
+* const links = extractLinksFromBatch(messages);
+*
+* tracer.startActiveSpan('process.batch', { links }, span => {
+*   for (const msg of messages) {
+*     processMessage(msg);
+*   }
+* });
+* ```
+*/
+function extractLinksFromBatch(messages, headersKey = "headers") {
+	const links = [];
+	for (const msg of messages) {
+		const msgHeaders = asStringRecord(msg[headersKey]);
+		if (msgHeaders) {
+			const link = createLinkFromHeaders(msgHeaders, { "messaging.batch.message_index": links.length });
+			if (link) links.push(link);
 		}
-		if (this.queue.length >= this.config.maxSize) {
-			const droppedEvent = this.queue.shift();
-			this.recordDropped("rate_limit", droppedEvent);
-			getLogger().warn({ droppedEvent: droppedEvent?.name }, `[autotel] Events queue full (${this.config.maxSize} events). Dropping oldest event. Events are being produced faster than they can be sent. Check your subscribers or reduce tracking frequency.`);
+	}
+	return links;
+}
+/**
+* Parse W3C traceparent header into SpanContext
+* Format: version-traceId-spanId-traceFlags (e.g., 00-abc123...-def456...-01)
+*
+* @see https://www.w3.org/TR/trace-context/#traceparent-header
+*/
+function parseTraceparent(traceparent) {
+	const match = traceparent.match(/^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/i);
+	if (!match || match.length < 5) return null;
+	const version = match[1];
+	const traceId = match[2];
+	const spanId = match[3];
+	const flags = match[4];
+	if (!version || !traceId || !spanId || !flags) return null;
+	if (version === "ff") return null;
+	return {
+		traceId,
+		spanId,
+		traceFlags: Number.parseInt(flags, 16),
+		isRemote: true
+	};
+}
+/**
+* Check if a SpanContext is valid (has non-zero trace and span IDs)
+*/
+function isValidSpanContext(spanContext) {
+	if (!spanContext) return false;
+	return spanContext.traceId !== "00000000000000000000000000000000" && spanContext.spanId !== "0000000000000000";
+}
+/** True when the request in flight asked for full-fidelity capture. */
+function debugCaptureRequested() {
+	const entry = propagation.getBaggage(getActiveContextWithBaggage())?.getEntry(AUTOTEL_DEBUG_BAGGAGE_KEY);
+	return entry !== void 0 && entry.value !== "" && entry.value !== "0";
+}
+
+//#endregion
+//#region src/init-logger.ts
+const LOG_LEVELS = {
+	debug: 0,
+	info: 1,
+	warn: 2,
+	error: 3
+};
+/** Silent logger used until and unless the application opts into diagnostics. */
+const silentLogger = {
+	info: () => {},
+	warn: () => {},
+	error: () => {},
+	debug: () => {}
+};
+/** Apply the resolved silence and minimum-level settings to a logger. */
+function wrapLogger(base, silent, minLevel) {
+	if (silent) return silentLogger;
+	const threshold = LOG_LEVELS[minLevel];
+	const wrap = (fn, level) => {
+		if (LOG_LEVELS[level] < threshold) return (() => {});
+		return ((...args) => fn(...args));
+	};
+	return {
+		debug: wrap(base.debug, "debug"),
+		info: wrap(base.info, "info"),
+		warn: wrap(base.warn, "warn"),
+		error: wrap(base.error, "error")
+	};
+}
+
+//#endregion
+//#region src/posthog-logs.ts
+var RedactingLogRecordProcessor = class {
+	wrapped;
+	redact;
+	constructor(wrapped, redact) {
+		this.wrapped = wrapped;
+		this.redact = redact;
+	}
+	onEmit(logRecord, context) {
+		const body = asString(logRecord.body);
+		if (body) logRecord.body = this.redact(body);
+		if (logRecord.attributes) for (const [key, value] of Object.entries(logRecord.attributes)) {
+			const text = asString(value);
+			if (text !== void 0) logRecord.attributes[key] = this.redact(text);
+			else if (Array.isArray(value)) logRecord.attributes[key] = value.map((item) => {
+				const entry = asString(item);
+				return entry === void 0 ? item : this.redact(entry);
+			});
 		}
-		const enrichedEvent = {
-			...event,
-			_correlationId: event._correlationId || getOrCreateCorrelationId()
-		};
-		this.queue.push(enrichedEvent);
-		this.scheduleBatchFlush();
+		this.wrapped.onEmit(logRecord, context);
+	}
+	shutdown() {
+		return this.wrapped.shutdown();
+	}
+	forceFlush() {
+		return this.wrapped.forceFlush();
+	}
+};
+/**
+* Build log record processors for PostHog OTLP logs integration.
+*
+* Resolution order:
+* 1. config.url if provided
+* 2. POSTHOG_LOGS_URL env var
+* 3. Empty array (disabled)
+*/
+function buildPostHogLogProcessors(config, stringRedactor) {
+	const url = config?.url || process.env.POSTHOG_LOGS_URL;
+	if (!url) return [];
+	const sdkLogs = safeRequire("@opentelemetry/sdk-logs");
+	const exporterModule = safeRequire("@opentelemetry/exporter-logs-otlp-http");
+	if (!sdkLogs || !exporterModule) return [];
+	const exporter = new exporterModule.OTLPLogExporter({ url });
+	let processor = new sdkLogs.BatchLogRecordProcessor({ exporter });
+	if (stringRedactor) processor = new RedactingLogRecordProcessor(processor, stringRedactor);
+	return [processor];
+}
+
+//#endregion
+//#region src/tail-sampling-processor.ts
+var TailSamplingSpanProcessor = class {
+	wrappedProcessor;
+	constructor(wrappedProcessor) {
+		this.wrappedProcessor = wrappedProcessor;
+	}
+	onStart(span, parentContext) {
+		this.wrappedProcessor.onStart(span, parentContext);
+	}
+	onEnd(span) {
+		const tailEvaluated = span.attributes[AUTOTEL_SAMPLING_TAIL_EVALUATED];
+		const shouldKeep = span.attributes[AUTOTEL_SAMPLING_TAIL_KEEP];
+		if (tailEvaluated === true && shouldKeep === false) return;
+		this.wrappedProcessor.onEnd(span);
+	}
+	forceFlush() {
+		return this.wrappedProcessor.forceFlush();
+	}
+	shutdown() {
+		return this.wrappedProcessor.shutdown();
+	}
+};
+
+//#endregion
+//#region src/baggage-span-processor.ts
+/**
+* Span processor that automatically copies baggage entries to span attributes
+*
+* This makes baggage visible in trace UIs (Jaeger, Grafana, DataDog, etc.)
+* without manually calling ctx.setAttribute() for each baggage entry.
+*
+* @example Enable in init()
+* ```typescript
+* init({
+*   service: 'my-app',
+*   baggage: true // Uses default 'baggage.' prefix
+* });
+*
+* // Now baggage automatically appears as span attributes
+* await withBaggage({
+*   baggage: { 'tenant.id': 't1', 'user.id': 'u1' },
+*   fn: async () => {
+*     // Span has baggage.tenant.id and baggage.user.id attributes!
+*   }
+* });
+* ```
+*
+* @example Custom prefix
+* ```typescript
+* init({
+*   service: 'my-app',
+*   baggage: 'ctx' // Uses 'ctx.' prefix
+* });
+* // Creates attributes: ctx.tenant.id, ctx.user.id
+* ```
+*/
+var BaggageSpanProcessor = class {
+	prefix;
+	constructor(options = {}) {
+		this.prefix = options.prefix ?? "baggage.";
 	}
-	/**
-	* Schedule a batch flush if not already scheduled
-	*/
-	scheduleBatchFlush() {
-		if (this.flushTimer || this.flushPromise) return;
-		this.flushTimer = setTimeout(() => {
-			this.flushTimer = null;
-			this.flushBatch();
-		}, this.config.flushInterval);
+	onStart(span, parentContext) {
+		let baggage = propagation.getBaggage(parentContext);
+		if (!baggage) baggage = propagation.getBaggage(context.active());
+		if (!baggage) try {
+			const { getActiveContextWithBaggage } = requireModule("./trace-context");
+			const storedContext = getActiveContextWithBaggage();
+			baggage = propagation.getBaggage(storedContext);
+		} catch {}
+		if (!baggage) return;
+		for (const [key, entry] of baggage.getAllEntries()) span.setAttribute(`${this.prefix}${key}`, entry.value);
 	}
-	/**
-	* Flush a batch of events
-	* Uses promise-based concurrency control to prevent race conditions
-	*/
-	async flushBatch() {
-		if (this.queue.length === 0) return;
-		if (this.flushPromise) {
-			await this.flushPromise;
-			return;
-		}
-		this.flushPromise = this.doFlushBatch();
-		try {
-			await this.flushPromise;
-		} finally {
-			this.flushPromise = null;
-			if (this.queue.length > 0) this.scheduleBatchFlush();
+	onEnd(_span) {}
+	async shutdown() {}
+	async forceFlush() {}
+};
+
+//#endregion
+//#region src/redact-values.ts
+/** Standalone string redaction for use outside the span processor pipeline. */
+function createStringRedactor(config) {
+	const resolved = typeof config === "string" ? REDACTOR_PRESETS[config] : config;
+	const valuePatterns = resolved.valuePatterns ?? [];
+	const defaultReplacement = resolved.replacement ?? "[REDACTED]";
+	return (value) => {
+		let result = value;
+		for (const { pattern, replacement, mask } of valuePatterns) {
+			pattern.lastIndex = 0;
+			result = mask ? result.replaceAll(pattern, (match) => mask(match)) : result.replaceAll(pattern, replacement ?? defaultReplacement);
 		}
+		return result;
+	};
+}
+
+//#endregion
+//#region src/env-config.ts
+/**
+* Validate URL format
+*/
+function isValidUrl(urlString) {
+	try {
+		const url = new URL(urlString);
+		return url.protocol === "http:" || url.protocol === "https:";
+	} catch {
+		return false;
 	}
-	/**
-	* Internal flush implementation
-	*/
-	async doFlushBatch() {
-		const batch = this.queue.splice(0, this.config.batchSize);
-		await this.sendWithRetry(batch, this.config.maxRetries);
-	}
-	/**
-	* Send events with exponential backoff retry
-	* Tracks per-event, per-subscriber failures so failed counter reflects actual failed deliveries.
-	* On retry, only failed (event, subscriber) pairs are re-sent to avoid double-counting delivered.
-	*/
-	async sendWithRetry(events, retriesLeft, subscribersByEventIndex) {
-		const failedDeliveries = await this.sendToSubscribers(events, subscribersByEventIndex);
-		if (failedDeliveries.length > 0) if (retriesLeft > 0) {
-			const failedEventIndicesOrdered = [...new Set(failedDeliveries.map((f) => f.eventIndex))].toSorted((a, b) => a - b);
-			const eventsToRetry = failedEventIndicesOrdered.map((i) => events[i]);
-			const failedSubscribersByRetryIndex = /* @__PURE__ */ new Map();
-			for (const [j, origIndex] of failedEventIndicesOrdered.entries()) {
-				const set = /* @__PURE__ */ new Set();
-				for (const { eventIndex, subscriberName } of failedDeliveries) if (eventIndex === origIndex) set.add(subscriberName);
-				failedSubscribersByRetryIndex.set(j, set);
-			}
-			const delay = Math.pow(2, this.config.maxRetries - retriesLeft) * 1e3;
-			await new Promise((resolve) => setTimeout(resolve, delay));
-			return this.sendWithRetry(eventsToRetry, retriesLeft - 1, failedSubscribersByRetryIndex);
-		} else {
-			for (const { eventIndex, subscriberName, error } of failedDeliveries) {
-				const event = events[eventIndex];
-				if (event) this.recordFailed(event, subscriberName, error);
-			}
-			const failedSubscriberNames = [...new Set(failedDeliveries.map((f) => f.subscriberName))];
-			getLogger().error({
-				failedSubscribers: failedSubscriberNames,
-				retriesAttempted: this.config.maxRetries
-			}, "[autotel] Failed to send events after retries");
-		}
+}
+/**
+* Resolve OpenTelemetry environment variables from process.env
+*/
+function resolveOtelEnv() {
+	const env = {};
+	if (process.env.OTEL_SERVICE_NAME) {
+		const value = process.env.OTEL_SERVICE_NAME.trim();
+		if (value) env.OTEL_SERVICE_NAME = value;
 	}
-	/**
-	* Send events to configured subscribers with rate limiting and metrics.
-	* When subscribersByEventIndex is provided (retry path), only those subscribers are tried per event.
-	* Returns per-event, per-subscriber failures (empty if all succeeded).
-	*/
-	async sendToSubscribers(events, subscribersByEventIndex) {
-		const failedDeliveries = [];
-		const sendOne = async (event, eventIndex) => {
-			const subscriberNames = subscribersByEventIndex?.get(eventIndex);
-			const failures = await this.sendEventToSubscribers(event, subscriberNames ?? void 0);
-			for (const failure of failures) failedDeliveries.push({
-				eventIndex,
-				subscriberName: failure.subscriberName,
-				error: failure.error
-			});
-		};
-		if (!this.rateLimiter) {
-			for (const [i, event] of events.entries()) if (event) await sendOne(event, i);
-			return failedDeliveries;
-		}
-		for (const [i, event] of events.entries()) {
-			await this.rateLimiter.waitForToken();
-			if (event) await sendOne(event, i);
-		}
-		return failedDeliveries;
+	if (process.env.OTEL_EXPORTER_OTLP_ENDPOINT) {
+		const value = process.env.OTEL_EXPORTER_OTLP_ENDPOINT.trim();
+		if (value && isValidUrl(value)) env.OTEL_EXPORTER_OTLP_ENDPOINT = value;
 	}
-	/**
-	* Send a single event to subscribers.
-	* - When subscriberNames is undefined (initial attempt): send to all subscribers.
-	* - When subscriberNames is provided (retry): send only to those subscribers (never re-send to healthy ones).
-	* Returns list of subscribers that failed (empty if all succeeded).
-	*/
-	async sendEventToSubscribers(event, subscriberNames) {
-		const startTime = event.timestamp;
-		const failures = [];
-		const subscribersToTry = subscriberNames === void 0 ? this.subscribers : this.subscribers.filter((s) => subscriberNames.has(getSubscriberName(s)));
-		const results = await Promise.allSettled(subscribersToTry.map(async (subscriber) => {
-			const subscriberName = getSubscriberName(subscriber);
-			try {
-				await subscriber.trackEvent(event.name, event.attributes, {
-					autotel: event.autotel,
-					schema: event.schema
-				});
-				this.recordDelivered(event, subscriberName, startTime);
-				return {
-					subscriberName,
-					success: true
-				};
-			} catch (error) {
-				this.markSubscriberUnhealthy(subscriberName);
-				return {
-					subscriberName,
-					success: false,
-					error: error instanceof Error ? error : void 0
-				};
-			}
-		}));
-		for (const result of results) if (result.status === "fulfilled" && !result.value.success) failures.push({
-			subscriberName: result.value.subscriberName,
-			error: result.value.error
-		});
-		return failures;
+	if (process.env.OTEL_EXPORTER_OTLP_HEADERS) {
+		const value = process.env.OTEL_EXPORTER_OTLP_HEADERS.trim();
+		if (value) env.OTEL_EXPORTER_OTLP_HEADERS = value;
 	}
-	/**
-	* Flush all remaining events. Queue remains usable after flush (e.g. for
-	* auto-flush at root span end). Use shutdown() when tearing down the queue.
-	*/
-	async flush() {
-		if (this.flushTimer) {
-			clearTimeout(this.flushTimer);
-			this.flushTimer = null;
-		}
-		if (this.flushPromise) await this.flushPromise;
-		while (this.queue.length > 0) await this.doFlushBatch();
+	if (process.env.OTEL_RESOURCE_ATTRIBUTES) {
+		const value = process.env.OTEL_RESOURCE_ATTRIBUTES.trim();
+		if (value) env.OTEL_RESOURCE_ATTRIBUTES = value;
 	}
-	/**
-	* Flush remaining events and permanently disable the queue (reject new events).
-	* Use for process/SDK shutdown; use flush() for periodic or span-end drain.
-	*/
-	async shutdown() {
-		this.isShuttingDown = true;
-		await this.flush();
-		const drains = await Promise.allSettled(this.subscribers.map(async (subscriber) => {
-			if (!subscriber.shutdown) return;
-			shutDownSubscribers.add(subscriber);
-			return subscriber.shutdown();
-		}));
-		for (const [index, drain] of drains.entries()) {
-			if (drain.status !== "rejected") continue;
-			const subscriberName = getSubscriberName(this.subscribers[index]);
-			this.subscriberHealthy.set(subscriberName, false);
-			getLogger().error({
-				subscriber: subscriberName,
-				err: drain.reason
-			}, "[autotel] Subscriber shutdown failed, buffered events may be lost");
-		}
+	if (process.env.OTEL_EXPORTER_OTLP_PROTOCOL) {
+		const value = process.env.OTEL_EXPORTER_OTLP_PROTOCOL.trim().toLowerCase();
+		if (value === "http" || value === "http/json") env.OTEL_EXPORTER_OTLP_PROTOCOL = "http";
+		else if (value === "http/protobuf" || value === "grpc") env.OTEL_EXPORTER_OTLP_PROTOCOL = value;
 	}
-	/**
-	* Cleanup observable metric callbacks to prevent memory leaks
-	* Call this when destroying the EventQueue instance
-	*/
-	cleanup() {
-		for (const cleanupFn of this.observableCleanups) try {
-			cleanupFn();
-		} catch {}
-		this.observableCleanups = [];
+	if (process.env.OTEL_TRACES_SAMPLER) {
+		const value = process.env.OTEL_TRACES_SAMPLER.trim();
+		if (value) env.OTEL_TRACES_SAMPLER = value;
 	}
-	/**
-	* Get queue size (for testing/debugging)
-	*/
-	size() {
-		return this.queue.length;
+	if (process.env.OTEL_TRACES_SAMPLER_ARG) {
+		const value = process.env.OTEL_TRACES_SAMPLER_ARG.trim();
+		if (value) env.OTEL_TRACES_SAMPLER_ARG = value;
 	}
-	/**
-	* Get subscriber health status (for testing/debugging)
-	*/
-	getSubscriberHealth() {
-		return new Map(this.subscriberHealthy);
+	return env;
+}
+function parseRatioSamplerArg(samplerName, samplerArg) {
+	if (samplerArg === void 0) return 1;
+	const ratio = Number(samplerArg);
+	if (!Number.isFinite(ratio) || ratio < 0 || ratio > 1) {
+		console.error(`[autotel] Invalid OTEL_TRACES_SAMPLER_ARG="${samplerArg}" for ${samplerName}. Expected a number in [0..1]. Falling back to 1.0.`);
+		return 1;
 	}
-	/**
-	* Check if a specific subscriber is healthy
-	*/
-	isSubscriberHealthy(subscriberName) {
-		return this.subscriberHealthy.get(subscriberName.toLowerCase()) ?? true;
+	return ratio;
+}
+function warnOnUnusedSamplerArg(samplerName, samplerArg) {
+	if (samplerArg !== void 0) console.error(`[autotel] OTEL_TRACES_SAMPLER_ARG is not used by OTEL_TRACES_SAMPLER="${samplerName}". Ignoring value "${samplerArg}".`);
+}
+function createSamplerFromEnv(env) {
+	const samplerName = env.OTEL_TRACES_SAMPLER;
+	if (!samplerName) return;
+	switch (samplerName) {
+		case "always_on":
+			warnOnUnusedSamplerArg(samplerName, env.OTEL_TRACES_SAMPLER_ARG);
+			return new AlwaysOnSampler();
+		case "always_off":
+			warnOnUnusedSamplerArg(samplerName, env.OTEL_TRACES_SAMPLER_ARG);
+			return new AlwaysOffSampler();
+		case "traceidratio": return new TraceIdRatioBasedSampler(parseRatioSamplerArg(samplerName, env.OTEL_TRACES_SAMPLER_ARG));
+		case "parentbased_always_on":
+			warnOnUnusedSamplerArg(samplerName, env.OTEL_TRACES_SAMPLER_ARG);
+			return new ParentBasedSampler({ root: new AlwaysOnSampler() });
+		case "parentbased_always_off":
+			warnOnUnusedSamplerArg(samplerName, env.OTEL_TRACES_SAMPLER_ARG);
+			return new ParentBasedSampler({ root: new AlwaysOffSampler() });
+		case "parentbased_traceidratio": return new ParentBasedSampler({ root: new TraceIdRatioBasedSampler(parseRatioSamplerArg(samplerName, env.OTEL_TRACES_SAMPLER_ARG)) });
+		case "jaeger_remote":
+		case "parentbased_jaeger_remote":
+		case "xray":
+			console.error(`[autotel] OTEL_TRACES_SAMPLER="${samplerName}" is not supported yet by autotel. Falling back to the next sampler source.`);
+			return;
+		default:
+			console.error(`[autotel] Unknown OTEL_TRACES_SAMPLER="${samplerName}". Falling back to the next sampler source.`);
+			return;
 	}
-	/**
-	* Manually mark a subscriber as healthy or unhealthy
-	* (used for circuit breaker integration)
-	*/
-	setSubscriberHealth(subscriberName, healthy) {
-		this.subscriberHealthy.set(subscriberName.toLowerCase(), healthy);
+}
+/**
+* Parse OTEL_RESOURCE_ATTRIBUTES from comma-separated key=value pairs
+* Example: "service.version=1.0.0,deployment.environment=production"
+*/
+function parseResourceAttributes(input) {
+	if (!input || input.trim() === "") return {};
+	const attributes = {};
+	const pairs = input.split(",");
+	for (const pair of pairs) {
+		const trimmedPair = pair.trim();
+		if (!trimmedPair) continue;
+		const equalIndex = trimmedPair.indexOf("=");
+		if (equalIndex === -1) continue;
+		const key = trimmedPair.slice(0, equalIndex).trim();
+		const value = trimmedPair.slice(equalIndex + 1).trim();
+		if (key && value) attributes[key] = value;
 	}
-};
-
-//#endregion
-//#region src/validation.ts
-const DEFAULT_CONFIG$1 = {
-	maxEventNameLength: 100,
-	maxAttributeKeyLength: 100,
-	maxAttributeValueLength: 1e3,
-	maxAttributeCount: 50,
-	maxNestingDepth: 3,
-	sensitivePatterns: [
-		/password/i,
-		/secret/i,
-		/token/i,
-		/api[_-]?key/i,
-		/access[_-]?key/i,
-		/private[_-]?key/i,
-		/auth/i,
-		/credential/i,
-		/ssn/i,
-		/credit[_-]?card/i
-	]
-};
-var ValidationError = class extends Error {
-	constructor(message) {
-		super(message);
-		this.name = "ValidationError";
+	return attributes;
+}
+/**
+* Parse OTEL_EXPORTER_OTLP_HEADERS from comma-separated key=value pairs
+* Example: "api-key=secret123,x-custom-header=value"
+*/
+function parseOtlpHeaders(input) {
+	if (!input || input.trim() === "") return {};
+	const headers = {};
+	const pairs = input.split(",");
+	for (const pair of pairs) {
+		const trimmedPair = pair.trim();
+		if (!trimmedPair) continue;
+		const equalIndex = trimmedPair.indexOf("=");
+		if (equalIndex === -1) continue;
+		const key = trimmedPair.slice(0, equalIndex).trim();
+		const value = trimmedPair.slice(equalIndex + 1).trim();
+		if (key && value) headers[key] = value;
 	}
-};
+	return headers;
+}
 /**
-* Validate and sanitize event name
-* Throws ValidationError if invalid
+* Convert resolved environment variables to config
 */
-function validateEventName(eventName, config = DEFAULT_CONFIG$1) {
-	if (asString(eventName) === void 0) throw new ValidationError(`Event name must be a string, got ${describeValue(eventName)}`);
-	const trimmed = eventName.trim();
-	if (trimmed.length === 0) throw new ValidationError("Event name cannot be empty");
-	if (trimmed.length > config.maxEventNameLength) throw new ValidationError(`Event name too long (${trimmed.length} chars). Max: ${config.maxEventNameLength}`);
-	if (!/^[a-zA-Z0-9._-]+$/.test(trimmed)) throw new ValidationError(`Event name contains invalid characters: "${trimmed}". Use only letters, numbers, dots, underscores, and hyphens.`);
-	return trimmed;
+function envToConfig(env) {
+	const config = {};
+	if (env.OTEL_SERVICE_NAME) config.service = env.OTEL_SERVICE_NAME;
+	if (env.OTEL_EXPORTER_OTLP_ENDPOINT) config.endpoint = env.OTEL_EXPORTER_OTLP_ENDPOINT;
+	if (env.OTEL_EXPORTER_OTLP_PROTOCOL) config.protocol = env.OTEL_EXPORTER_OTLP_PROTOCOL;
+	if (env.OTEL_EXPORTER_OTLP_HEADERS) config.headers = parseOtlpHeaders(env.OTEL_EXPORTER_OTLP_HEADERS);
+	const resourceAttrs = parseResourceAttributes(env.OTEL_RESOURCE_ATTRIBUTES);
+	if (Object.keys(resourceAttrs).length > 0) config.resourceAttributes = resourceAttrs;
+	const sampler = createSamplerFromEnv(env);
+	if (sampler) config.otelSampler = sampler;
+	return config;
 }
 /**
-* Validate and sanitize attributes
-* Returns sanitized attributes (sensitive data redacted)
+* Main function to resolve config from environment variables
 */
-function validateAttributes(attributes, config = DEFAULT_CONFIG$1) {
-	if (attributes === void 0 || attributes === null) return;
-	if (!asRecord(attributes)) throw new ValidationError("Attributes must be an object");
-	const keys = Object.keys(attributes);
-	if (keys.length > config.maxAttributeCount) throw new ValidationError(`Too many attributes (${keys.length}). Max: ${config.maxAttributeCount}`);
-	const sanitized = {};
-	for (const key of keys) {
-		if (key.length > config.maxAttributeKeyLength) throw new ValidationError(`Attribute key too long: "${key.slice(0, 20)}..." (${key.length} chars). Max: ${config.maxAttributeKeyLength}`);
-		const value = attributes[key];
-		if (isSensitiveString(key, value, config)) {
-			sanitized[key] = "[REDACTED]";
-			continue;
-		}
-		sanitized[key] = sanitizeValue(value, config, 1);
+function resolveConfigFromEnv() {
+	return envToConfig(resolveOtelEnv());
+}
+
+//#endregion
+//#region src/yaml-config.ts
+/**
+* YAML configuration loader for autotel
+*
+* Supports:
+* - Auto-discovery of autotel.yaml in cwd
+* - AUTOTEL_CONFIG_FILE env var override
+* - Environment variable substitution: ${env:VAR} and ${env:VAR:-default}
+*
+* @example Auto-discovery
+* ```yaml
+* # autotel.yaml in project root
+* service:
+*   name: my-service
+* exporter:
+*   endpoint: ${env:OTEL_EXPORTER_OTLP_ENDPOINT:-http://localhost:4318}
+* ```
+*
+* @example Explicit path
+* ```bash
+* AUTOTEL_CONFIG_FILE=./config/otel.yaml tsx --import autotel/auto src/index.ts
+* ```
+*/
+/**
+* Lazy-load yaml parser (optional peer dependency)
+* Only loads when a YAML config file is actually found
+*/
+function loadYamlParser() {
+	try {
+		return requireModule("yaml").parse;
+	} catch {
+		throw new Error("YAML parser not found. Install with: pnpm add yaml");
 	}
-	return sanitized;
 }
 /**
-* Whether this key/value pair is a credential to redact. Strings only:
-* numeric and boolean values are not credentials, and replacing them with the
-* literal '[REDACTED]' leaks no signal while breaking every consumer that
-* treats them as a number.
+* Environment variable substitution regex
+* Matches ${env:VAR_NAME} and ${env:VAR_NAME:-default}
 */
-function isSensitiveString(key, value, config) {
-	return asString(value) !== void 0 && config.sensitivePatterns.some((pattern) => pattern.test(key));
+const ENV_VAR_PATTERN = /\$\{env:([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}/g;
+/**
+* Substitute ${env:VAR} and ${env:VAR:-default} in a string
+*
+* @param value - String potentially containing env var references
+* @returns String with env vars substituted
+*
+* @example
+* substituteEnvVars('${env:NODE_ENV:-development}')
+* // Returns 'production' if NODE_ENV=production, else 'development'
+*/
+function substituteEnvVars(value) {
+	return value.replaceAll(ENV_VAR_PATTERN, (_match, varName, defaultValue) => {
+		const envValue = process.env[varName];
+		if (envValue !== void 0) return envValue;
+		if (defaultValue !== void 0) return defaultValue;
+		console.warn(`[autotel] Environment variable ${varName} not set and no default provided`);
+		return "";
+	});
 }
 /**
-* Sanitize attribute value (recursive)
+* Recursively substitute env vars in an object
+*
+* @param obj - Object to process
+* @returns Object with all string values having env vars substituted
 */
-function sanitizeValue(value, config, depth) {
-	if (depth > config.maxNestingDepth) return "[MAX_DEPTH_EXCEEDED]";
-	if (value === null || value === void 0) return value;
-	const text = asString(value);
-	if (text !== void 0) return text.length > config.maxAttributeValueLength ? text.slice(0, config.maxAttributeValueLength) + "..." : text;
-	const scalar = asNumber(value) ?? asBoolean(value);
-	if (scalar !== void 0) return scalar;
-	if (Array.isArray(value)) return value.map((item) => sanitizeValue(item, config, depth + 1));
-	const record = asRecord(value);
-	if (record) try {
-		JSON.stringify(record);
-		const sanitized = {};
-		for (const [key, nested] of Object.entries(record)) sanitized[key] = isSensitiveString(key, nested, config) ? "[REDACTED]" : sanitizeValue(nested, config, depth + 1);
-		return sanitized;
-	} catch {
-		return "[CIRCULAR]";
+function substituteEnvVarsDeep(value) {
+	if (Array.isArray(value)) return value.map(substituteEnvVarsDeep);
+	const mapping = asYamlMapping(value);
+	if (mapping) {
+		const result = {};
+		for (const [key, entry] of Object.entries(mapping)) result[key] = substituteEnvVarsDeep(entry);
+		return result;
 	}
-	return `[${describeValue(value)}]`;
+	const text = asString(value);
+	return text === void 0 ? value : substituteEnvVars(text);
+}
+/** The mapping a YAML value is, when it is one. */
+function asYamlMapping(value) {
+	return asRecord(value) === void 0 ? void 0 : value;
 }
 /**
-* Validate and sanitize an events event
-* Returns { eventName, attributes } with sanitized values
+* A YAML document read into the config shape, with `${env:...}` placeholders
+* resolved.
+*
+* This is the boundary: the file is text until here. Every field of
+* YamlConfig is optional, so any document satisfies it, and
+* `yamlToAutotelConfig` picks out only the fields it understands.
 */
-function validateEvent(eventName, attributes, config) {
-	const fullConfig = {
-		...DEFAULT_CONFIG$1,
-		...config
-	};
-	return {
-		eventName: validateEventName(eventName, fullConfig),
-		attributes: validateAttributes(attributes, fullConfig)
-	};
+function parseYamlConfig(content) {
+	return asYamlMapping(substituteEnvVarsDeep(loadYamlParser()(content))) ?? {};
 }
-
-//#endregion
-//#region src/track.ts
 /**
-* Global track() function for business events
+* Find YAML config file path
 *
-* Simple, no instantiation needed, auto-attaches trace context
+* Priority:
+* 1. AUTOTEL_CONFIG_FILE env var (explicit path)
+* 2. autotel.yaml in cwd (convention)
+* 3. autotel.yml in cwd (alternative extension)
+*
+* @returns File path if found, null otherwise
 */
-let eventsQueue = null;
+function findConfigFile() {
+	const envPath = process.env.AUTOTEL_CONFIG_FILE;
+	if (envPath) {
+		const resolved = path.resolve(envPath);
+		if (nodeFs.existsSync(resolved)) return resolved;
+		console.warn(`[autotel] Config file not found: ${envPath}`);
+		return null;
+	}
+	const conventionPath = path.resolve(process.cwd(), "autotel.yaml");
+	if (nodeFs.existsSync(conventionPath)) return conventionPath;
+	const altPath = path.resolve(process.cwd(), "autotel.yml");
+	if (nodeFs.existsSync(altPath)) return altPath;
+	return null;
+}
 /**
-* Build autotel event context for trace correlation
+* Convert YAML config structure to AutotelConfig
 *
-* Works in multiple contexts:
-* 1. Inside a span → use current span's trace_id + span_id
-* 2. Outside span → use correlation_id only
-* 3. With trace URL config → include clickable trace URL
+* @param yaml - Parsed and env-substituted YAML config
+* @returns Partial AutotelConfig ready for merging
 */
-function buildAutotelContext(span) {
-	const eventsConfig = getEventsConfig();
-	const config = getConfig();
-	const correlationId = getOrCreateCorrelationId();
-	if (!eventsConfig?.includeTraceContext) return { correlation_id: correlationId };
-	const autotelContext = { correlation_id: correlationId };
-	const spanContext = span?.spanContext();
-	if (spanContext) {
-		autotelContext.trace_id = spanContext.traceId;
-		autotelContext.span_id = spanContext.spanId;
-		autotelContext.trace_flags = spanContext.traceFlags.toString(16).padStart(2, "0");
-		const traceState = spanContext.traceState;
-		if (traceState) try {
-			if (typeof traceState.serialize === "function") {
-				const traceStateStr = traceState.serialize();
-				if (traceStateStr) autotelContext.trace_state = traceStateStr;
-			}
-		} catch {}
-		if (eventsConfig.traceUrl && config) {
-			const traceUrl = eventsConfig.traceUrl({
-				traceId: spanContext.traceId,
-				spanId: spanContext.spanId,
-				correlationId,
-				serviceName: config.service,
-				environment: config.environment
+function yamlToAutotelConfig(yaml) {
+	const config = {};
+	if (yaml.service?.name) config.service = yaml.service.name;
+	if (yaml.service?.version) config.version = yaml.service.version;
+	if (yaml.service?.environment) config.environment = yaml.service.environment;
+	if (yaml.exporter?.endpoint) config.endpoint = yaml.exporter.endpoint;
+	if (yaml.exporter?.protocol) config.protocol = yaml.exporter.protocol;
+	if (yaml.exporter?.headers) config.headers = yaml.exporter.headers;
+	if (yaml.exporter?.destinations) config.destinations = yaml.exporter.destinations;
+	if (yaml.resource) config.resourceAttributes = yaml.resource;
+	if (yaml.autoInstrumentations) config.autoInstrumentations = yaml.autoInstrumentations;
+	if (yaml.policies) config.policies = yaml.policies;
+	if (yaml.debug !== void 0) config.debug = yaml.debug;
+	if (yaml.sampling?.preset) {
+		warnOnIgnoredPresetOverrides(yaml.sampling);
+		config.sampling = yaml.sampling.preset;
+	} else {
+		const sampler = createSamplerFromYaml(yaml.sampling);
+		if (sampler) config.sampler = sampler;
+	}
+	return config;
+}
+function createSamplerFromYaml(sampling) {
+	if (!sampling) return void 0;
+	if (sampling.preset) return void 0;
+	const type = sampling.type ?? "adaptive";
+	try {
+		switch (type) {
+			case "adaptive": return new AdaptiveSampler({
+				baselineSampleRate: sampling.baseline_rate,
+				alwaysSampleErrors: sampling.always_sample_errors,
+				alwaysSampleSlow: sampling.always_sample_slow,
+				slowThresholdMs: sampling.slow_threshold_ms
 			});
-			if (traceUrl) autotelContext.trace_url = traceUrl;
+			case "always_on": return new AlwaysSampler();
+			case "always_off": return new NeverSampler();
+			case "ratio":
+				if (sampling.ratio === void 0) {
+					console.warn("[autotel] sampling.ratio missing in YAML sampling config. Falling back to adaptive sampler.");
+					return new AdaptiveSampler();
+				}
+				return new RandomSampler(sampling.ratio);
+			default:
+				console.warn(`[autotel] Unknown sampling type "${type}" in YAML config. Falling back to defaults.`);
+				return;
 		}
-	} else if (eventsConfig.traceUrl && config) {
-		const traceUrl = eventsConfig.traceUrl({
-			correlationId,
-			serviceName: config.service,
-			environment: config.environment
-		});
-		if (traceUrl) autotelContext.trace_url = traceUrl;
+	} catch (error) {
+		console.warn(`[autotel] Failed to configure sampling from YAML: ${error instanceof Error ? error.message : String(error)}`);
+		return;
 	}
-	return autotelContext;
+}
+function warnOnIgnoredPresetOverrides(sampling) {
+	const ignoredFields = [
+		"type",
+		"ratio",
+		"baseline_rate",
+		"always_sample_errors",
+		"always_sample_slow",
+		"slow_threshold_ms"
+	].filter((field) => sampling[field] !== void 0);
+	if (ignoredFields.length === 0) return;
+	console.warn(`[autotel] sampling.preset="${sampling.preset}" ignores these YAML fields: ${ignoredFields.join(", ")}. Use the programmatic API with sampler or samplingPresets.*(...) for tuned presets.`);
 }
 /**
-* Initialize events queue lazily
+* Load and parse YAML config file (auto-discovery)
+*
+* Automatically finds and loads autotel.yaml or uses AUTOTEL_CONFIG_FILE.
+* Returns null if no config file found (not an error - YAML config is optional).
+*
+* @returns Partial AutotelConfig or null if no config file found
+*
+* @example
+* const yamlConfig = loadYamlConfig();
+* if (yamlConfig) {
+*   init({ ...yamlConfig, debug: true });
+* }
 */
-function getOrCreateQueue() {
-	if (!isInitialized()) {
-		warnIfNotInitialized("track()");
+function loadYamlConfig() {
+	const filePath = findConfigFile();
+	if (!filePath) return null;
+	try {
+		return yamlToAutotelConfig(parseYamlConfig(nodeFs.readFileSync(filePath, "utf8")));
+	} catch (error) {
+		console.error(`[autotel] Failed to load YAML config from ${filePath}:`, error);
 		return null;
 	}
-	if (!eventsQueue) {
-		const config = getConfig();
-		if (!config?.subscribers || config.subscribers.length === 0) return null;
-		eventsQueue = new EventQueue(config.subscribers);
-	}
-	return eventsQueue;
 }
 /**
-* Track a business events event
+* Load YAML config from a specific file path
 *
-* Features:
-* - Auto-attaches traceId and spanId if in active span
-* - Batched sending with retry
-* - Type-safe with optional generic
-* - No-op if init() not called or no subscribers configured
+* Unlike loadYamlConfig(), this throws if the file cannot be read.
 *
-* @example Basic usage
-* ```typescript
-* track('user.signup', { userId: '123', plan: 'pro' })
-* ```
+* @param filePath - Path to YAML config file
+* @returns Partial AutotelConfig
+* @throws Error if file cannot be read or parsed
 *
-* @example With type safety
-* ```typescript
-* interface EventDatas {
-*   'user.signup': { userId: string; plan: string }
-*   'plan.upgraded': { userId: string; revenue: number }
-* }
+* @example
+* import { loadYamlConfigFromFile } from 'autotel/yaml';
+* import { init } from 'autotel';
 *
-* track<EventDatas>('user.signup', { userId: '123', plan: 'pro' })
-* ```
+* const config = loadYamlConfigFromFile('./config/otel.yaml');
+* init({ ...config, debug: true });
+*/
+function loadYamlConfigFromFile(filePath) {
+	const resolved = path.resolve(filePath);
+	return yamlToAutotelConfig(parseYamlConfig(nodeFs.readFileSync(resolved, "utf8")));
+}
+/**
+* Check if a YAML config file exists (without loading it)
 *
-* @example Trace correlation (automatic)
-* ```typescript
-* @Instrumented()
-* class UserService {
-*   async createUser(data: CreateUserData) {
-*     // This track call automatically includes traceId + spanId
-*     track('user.signup', { userId: data.id })
-*   }
-* }
-* ```
+* @returns true if a config file would be found by loadYamlConfig()
 */
-function track(event, data, options) {
-	const queue = getOrCreateQueue();
-	if (!queue) return;
-	const validated = validateEvent(event, data, getValidationConfig() || void 0);
-	const span = trace.getActiveSpan();
-	const enrichedData = span ? {
-		...validated.attributes,
-		traceId: span.spanContext().traceId,
-		spanId: span.spanContext().spanId
-	} : validated.attributes;
-	const autotelContext = buildAutotelContext(span);
-	queue.enqueue({
-		name: validated.eventName,
-		attributes: enrichedData,
-		timestamp: Date.now(),
-		autotel: autotelContext,
-		schema: options?.schema
+function hasYamlConfig() {
+	return findConfigFile() !== null;
+}
+
+//#endregion
+//#region src/devtools.ts
+const defaultHost = "127.0.0.1";
+const defaultPort = 4318;
+function resolveDevtoolsConfig(config) {
+	if (!config) return {
+		enabled: false,
+		endpoint: void 0,
+		embedded: false,
+		host: defaultHost,
+		port: defaultPort,
+		verbose: false
+	};
+	if (config === true) return {
+		enabled: true,
+		endpoint: `http://${defaultHost}:${defaultPort}`,
+		embedded: false,
+		host: defaultHost,
+		port: defaultPort,
+		verbose: false
+	};
+	const enabled = config.enabled ?? true;
+	const host = config.host ?? defaultHost;
+	const port = config.port ?? defaultPort;
+	const endpoint = config.endpoint ?? `http://${host}:${port}`;
+	return {
+		enabled,
+		endpoint: enabled ? endpoint : void 0,
+		embedded: enabled && (config.embedded ?? false),
+		host,
+		port,
+		verbose: config.verbose ?? false
+	};
+}
+
+//#endregion
+//#region src/process-handlers.ts
+let removeOwnedHandlers = [];
+/**
+* Tracked separately from `removeOwnedHandlers` because the exit flush outlives
+* a call to `installProcessHandlers`, which clears that list before installing
+* its own signal listeners.
+*/
+let removeExitFlush;
+/**
+* Shared across every path that can end the process: signals, fatal errors and
+* a clean exit. They can overlap — a container stopping a job that has just
+* finished its work sends SIGTERM while the exit flush is still draining — and
+* a second shutdown would tear down queues the first is still using.
+*/
+let shutdownInFlight;
+/**
+* The clean-exit flush, while it runs. Doubles as the latch that keeps a
+* re-emitted `beforeExit` from flushing twice, and as the thing a shutdown
+* waits on rather than tearing down queues mid-drain.
+*/
+let exitFlushInFlight;
+const DEFAULT_SHUTDOWN_TIMEOUT_MS = 2e3;
+function runShutdownOnce(shutdown, timeoutMs) {
+	if (shutdownInFlight) return shutdownInFlight;
+	let timeoutHandle;
+	const shutdownAttempt = Promise.resolve(exitFlushInFlight).then(shutdown).catch(() => void 0);
+	const timeout = new Promise((resolve) => {
+		timeoutHandle = setTimeout(resolve, timeoutMs);
+		timeoutHandle.unref();
+	});
+	shutdownInFlight = Promise.race([shutdownAttempt, timeout]).then(() => {
+		if (timeoutHandle) clearTimeout(timeoutHandle);
 	});
+	return shutdownInFlight;
+}
+const DEFAULT_SIGNALS = ["SIGTERM", "SIGINT"];
+function signalExitCode(signal) {
+	return 128 + constants.signals[signal];
 }
 /**
-* Get events queue (for flush/shutdown)
-* @internal
+* Surface a fatal error before shutting down.
+*
+* Registering an `uncaughtException` / `unhandledRejection` listener overrides
+* Node's default of printing the stack to stderr, so without this a crash under
+* `fatalErrors` would exit silently. Autotel's own logger is silent by default,
+* so we print to stderr directly to guarantee the crash stays visible.
 */
-function getEventQueue() {
-	return eventsQueue;
+function reportFatalError(error, event) {
+	const err = error instanceof Error ? error : new Error(String(error));
+	console.error(`[autotel] ${event}, flushing telemetry then exiting`, err);
+}
+function installProcessHandlers(config, shutdown) {
+	uninstallProcessHandlers();
+	const timeoutMs = config.shutdownTimeoutMs ?? DEFAULT_SHUTDOWN_TIMEOUT_MS;
+	let exitScheduled = false;
+	let resolvedExitCode = 0;
+	let fatalLatched = false;
+	const shutdownAndExit = (exitCode, fatal) => {
+		if (fatal) {
+			if (!fatalLatched) {
+				resolvedExitCode = exitCode;
+				fatalLatched = true;
+			}
+		} else if (!exitScheduled && !fatalLatched) resolvedExitCode = exitCode;
+		if (exitScheduled) return;
+		exitScheduled = true;
+		runShutdownOnce(shutdown, timeoutMs).then(() => {
+			process.exit(resolvedExitCode);
+		});
+	};
+	for (const signal of config.signals ?? DEFAULT_SIGNALS) {
+		const listener = () => {
+			shutdownAndExit(signalExitCode(signal), false);
+		};
+		process.on(signal, listener);
+		removeOwnedHandlers.push(() => {
+			process.removeListener(signal, listener);
+		});
+	}
+	if (config.fatalErrors ?? true) {
+		const uncaughtExceptionListener = (error) => {
+			reportFatalError(error, "uncaughtException");
+			shutdownAndExit(1, true);
+		};
+		const unhandledRejectionListener = (reason) => {
+			reportFatalError(reason, "unhandledRejection");
+			shutdownAndExit(1, true);
+		};
+		process.on("uncaughtException", uncaughtExceptionListener);
+		process.on("unhandledRejection", unhandledRejectionListener);
+		removeOwnedHandlers.push(() => {
+			process.removeListener("uncaughtException", uncaughtExceptionListener);
+		}, () => {
+			process.removeListener("unhandledRejection", unhandledRejectionListener);
+		});
+	}
 }
 /**
-* Reset events queue (for shutdown/cleanup)
-* @internal
+* Flush telemetry when the process runs to completion.
+*
+* The signal and fatal-error handlers above cover a process that is stopped or
+* that crashes. Neither fires when a script simply finishes: the event loop
+* drains and Node exits, taking whatever the batch span processor was still
+* holding with it. `beforeExit` is the only hook for that case, and it is the
+* one that matters for CLIs, cron jobs, CI steps and serverless handlers.
+*
+* A flush, never a shutdown: `beforeExit` fires on *any* event-loop drain, not
+* only the final one, so tearing the SDK down here would silently kill
+* telemetry in a process that goes on to do more work.
 */
-function resetEventQueue() {
-	eventsQueue = null;
+function installExitFlush(flushTelemetry, timeoutMs = DEFAULT_SHUTDOWN_TIMEOUT_MS) {
+	removeExitFlush?.();
+	exitFlushInFlight = void 0;
+	const listener = (code) => {
+		if (exitFlushInFlight || shutdownInFlight) return;
+		const deadline = setTimeout(() => {
+			process.exit(process.exitCode ?? code);
+		}, timeoutMs);
+		exitFlushInFlight = flushTelemetry().catch(() => void 0).finally(() => {
+			clearTimeout(deadline);
+		});
+	};
+	process.on("beforeExit", listener);
+	removeExitFlush = () => {
+		process.removeListener("beforeExit", listener);
+		removeExitFlush = void 0;
+	};
+}
+function uninstallProcessHandlers() {
+	for (const removeHandler of removeOwnedHandlers) removeHandler();
+	removeOwnedHandlers = [];
+	removeExitFlush?.();
+	shutdownInFlight = void 0;
+	exitFlushInFlight = void 0;
 }
 
 //#endregion
@@ -2470,6 +3339,15 @@ function errorCode(cause) {
 	return asString(readProperty(cause, "code"));
 }
 /**
+* A bare "Flush timeout" left you with a stack trace into bundled internals and
+* nothing to act on. Name how long we waited and where we were sending, since
+* the usual cause is that nothing is listening at that endpoint.
+*/
+function flushTimeoutMessage(timeout) {
+	const endpoint = getConfig()?.endpoint;
+	return `Flush timeout after ${timeout}ms${endpoint === void 0 ? "" : ` sending to ${endpoint}`}. No collector acknowledged the export; check that one is running and reachable.`;
+}
+/**
 * True when the error (or every error it wraps) is an unreachable-endpoint
 * failure. Traverses `AggregateError.errors` and the `cause` chain, since the
 * SDK often wraps the underlying network error.
@@ -2526,7 +3404,7 @@ async function flush(options) {
 		await Promise.race([doFlush().finally(() => {
 			if (timeoutHandle) clearTimeout(timeoutHandle);
 		}), new Promise((_, reject) => {
-			timeoutHandle = setTimeout(() => reject(/* @__PURE__ */ new Error("Flush timeout")), timeout);
+			timeoutHandle = setTimeout(() => reject(new Error(flushTimeoutMessage(timeout))), timeout);
 			timeoutHandle.unref();
 		})]);
 	} catch (error) {
@@ -3350,4 +4228,4 @@ function getSdk() {
 }
 
 //#endregion
-export { createStringRedactor as A, setCorrelationId as C, getActiveContextWithBaggage as D, defineBaggageSchema as E, getContextStorage as O, runWithCorrelationId as S, createTraceContext as T, CORRELATION_ID_BAGGAGE_KEY as _, isInitialized as a, getCorrelationStorage as b, flush as c, getEvents as d, resetEvents as f, track as g, getEventQueue as h, init as i, BaggageSpanProcessor as j, hasExplicitSpanStatus as k, shutdown as l, runInOperationContext as m, getLogger as n, isLoggerLocked as o, getOperationContext as p, getSdk as r, lockLogger as s, getConfig as t, Event as u, generateCorrelationId as v, setCorrelationIdInBaggage as w, getOrCreateCorrelationId as x, getCorrelationId as y };
+export { getOrCreateCorrelationId as $, KeyTargetRateSampler as A, resolveSamplingPreset as B, AUTOTEL_SAMPLING_TAIL_EVALUATED as C, CompositeSampler as D, AlwaysSampler as E, debugCaptureRequested as F, getContextStorage as G, createTraceContext as H, extractLinksFromBatch as I, track as J, hasExplicitSpanStatus as K, hashUnitInterval as L, RandomSampler as M, UserIdSampler as N, DeterministicSampler as O, createLinkFromHeaders as P, getCorrelationStorage as Q, isForceKept as R, AUTOTEL_SAMPLING_RATE as S, AdaptiveSampler as T, defineBaggageSchema as U, samplingPresets as V, getActiveContextWithBaggage as W, generateCorrelationId as X, CORRELATION_ID_BAGGAGE_KEY as Y, getCorrelationId as Z, loadYamlConfigFromFile as _, isInitialized as a, TailSamplingSpanProcessor as b, flush as c, getEvents as d, runWithCorrelationId as et, resetEvents as f, loadYamlConfig as g, hasYamlConfig as h, init as i, NeverSampler as j, FeatureFlagSampler as k, shutdown as l, runInOperationContext as m, getLogger as n, setCorrelationIdInBaggage as nt, isLoggerLocked as o, getOperationContext as p, getEventQueue as q, getSdk as r, lockLogger as s, getConfig as t, setCorrelationId as tt, Event as u, createStringRedactor as v, AUTOTEL_SAMPLING_TAIL_KEEP as w, AUTOTEL_DEBUG_BAGGAGE_KEY as x, BaggageSpanProcessor as y, markForceKept as z };