autotel 4.3.0 → 5.0.0

package/dist/slo.js

@@ -0,0 +1,223 @@
+import { getConfig } from "./config.js";
+import { trace } from "@opentelemetry/api";
+
+//#region src/slo.ts
+/**
+* Service level objective tracking and burn-rate evaluation.
+*
+* The tracker keeps a bounded rolling window in memory, records low-cardinality
+* OpenTelemetry metrics, and returns snapshots that callers can feed into alert
+* evaluation. Production systems can persist the emitted metrics in their
+* telemetry backend while tests use the same calculations in process.
+*/
+function validateDefinition(definition) {
+	if (!definition.name.trim()) throw new Error("SLO name must not be empty");
+	if (!Number.isFinite(definition.target) || definition.target <= 0 || definition.target >= 1) throw new Error("SLO target must be greater than 0 and less than 1");
+	if (!Number.isFinite(definition.windowMs) || definition.windowMs <= 0) throw new Error("SLO windowMs must be greater than 0");
+}
+function validateThreshold(name, threshold) {
+	if (!Number.isFinite(threshold) || threshold <= 0) throw new Error(`${name} must be greater than 0`);
+}
+function validateForecastOptions(options) {
+	if (!Number.isFinite(options.baselineMs) || options.baselineMs <= 0) throw new Error("baselineMs must be greater than 0");
+	if (!Number.isFinite(options.lookaheadMs) || options.lookaheadMs <= 0) throw new Error("lookaheadMs must be greater than 0");
+	if (options.lookaheadMs > options.baselineMs * 4) throw new Error("lookaheadMs must not exceed 4 times baselineMs");
+	if (options.expectedEventsInLookahead !== void 0 && (!Number.isFinite(options.expectedEventsInLookahead) || options.expectedEventsInLookahead < 0)) throw new Error("expectedEventsInLookahead must not be negative");
+}
+/**
+* Track good and bad events for one rolling-window service level objective.
+*/
+function createSloTracker(definition, options = {}) {
+	validateDefinition(definition);
+	const stableDefinition = Object.freeze({ ...definition });
+	const now = options.now ?? Date.now;
+	const observations = [];
+	let firstLiveIndex = 0;
+	let outcomeCounter;
+	let burnRateHistogram;
+	if (options.recordMetrics !== false) {
+		const meter = getConfig().meter;
+		outcomeCounter = meter.createCounter("autotel.slo.outcomes", {
+			description: "Good and bad events recorded against a service level objective",
+			unit: "1"
+		});
+		burnRateHistogram = meter.createHistogram("autotel.slo.burn_rate", {
+			description: "Error-budget burn rate for a service level objective",
+			unit: "1"
+		});
+	}
+	const prune = (at) => {
+		const cutoff = at - stableDefinition.windowMs;
+		while (firstLiveIndex < observations.length && observations[firstLiveIndex].timestamp < cutoff) firstLiveIndex += 1;
+		if (firstLiveIndex > 1024 && firstLiveIndex * 2 >= observations.length) {
+			observations.splice(0, firstLiveIndex);
+			firstLiveIndex = 0;
+		}
+	};
+	const calculate = (at) => {
+		prune(at);
+		let good = 0;
+		for (let index = firstLiveIndex; index < observations.length; index += 1) if (observations[index].outcome === "good") good += 1;
+		const total = observations.length - firstLiveIndex;
+		const bad = total - good;
+		const sli = total === 0 ? void 0 : good / total;
+		const errorBudgetFraction = 1 - stableDefinition.target;
+		const burnRate = (total === 0 ? 0 : bad / total) / errorBudgetFraction;
+		const budgetConsumed = burnRate;
+		return {
+			...stableDefinition,
+			observedAt: at,
+			total,
+			good,
+			bad,
+			sli,
+			errorBudgetFraction,
+			budgetConsumed,
+			budgetRemaining: 1 - budgetConsumed,
+			burnRate,
+			meetsTarget: sli === void 0 || sli >= stableDefinition.target
+		};
+	};
+	return {
+		definition: stableDefinition,
+		record(outcome, attributes = {}) {
+			if (outcome !== "good" && outcome !== "bad") throw new Error("SLO outcome must be \"good\" or \"bad\"");
+			const timestamp = now();
+			observations.push({
+				outcome,
+				timestamp
+			});
+			const current = calculate(timestamp);
+			const metricAttributes = {
+				...attributes,
+				"slo.name": stableDefinition.name,
+				"slo.outcome": outcome
+			};
+			outcomeCounter?.add(1, metricAttributes);
+			burnRateHistogram?.record(current.burnRate, { "slo.name": stableDefinition.name });
+			trace.getActiveSpan()?.setAttributes({
+				"slo.name": stableDefinition.name,
+				"slo.target": stableDefinition.target,
+				"slo.outcome": outcome,
+				"slo.burn_rate": current.burnRate
+			});
+			return current;
+		},
+		snapshot(at = now()) {
+			return calculate(at);
+		},
+		forecast(forecastOptions) {
+			validateForecastOptions(forecastOptions);
+			if (forecastOptions.baselineMs > stableDefinition.windowMs) throw new Error("baselineMs must not exceed the SLO windowMs");
+			const observedAt = now();
+			prune(observedAt);
+			const baselineCutoff = observedAt - forecastOptions.baselineMs;
+			const retainedCutoff = observedAt + forecastOptions.lookaheadMs - stableDefinition.windowMs;
+			let baselineTotal = 0;
+			let baselineBad = 0;
+			let retainedTotal = 0;
+			let retainedBad = 0;
+			for (let index = firstLiveIndex; index < observations.length; index += 1) {
+				const observation = observations[index];
+				if (observation.timestamp >= baselineCutoff) {
+					baselineTotal += 1;
+					if (observation.outcome === "bad") baselineBad += 1;
+				}
+				if (observation.timestamp >= retainedCutoff) {
+					retainedTotal += 1;
+					if (observation.outcome === "bad") retainedBad += 1;
+				}
+			}
+			if (baselineTotal === 0) return {
+				name: stableDefinition.name,
+				target: stableDefinition.target,
+				observedAt,
+				baselineMs: forecastOptions.baselineMs,
+				lookaheadMs: forecastOptions.lookaheadMs,
+				baselineTotal: 0,
+				baselineBad: 0,
+				baselineFailureRate: 0,
+				retainedTotal,
+				retainedBad,
+				projectedTotal: retainedTotal,
+				projectedBad: retainedBad,
+				projectedSli: retainedTotal === 0 ? void 0 : (retainedTotal - retainedBad) / retainedTotal,
+				alerting: false,
+				reason: "no-baseline-traffic"
+			};
+			const baselineFailureRate = baselineBad / baselineTotal;
+			const expectedEventsInLookahead = forecastOptions.expectedEventsInLookahead ?? baselineTotal * forecastOptions.lookaheadMs / forecastOptions.baselineMs;
+			const projectedFailures = baselineFailureRate * expectedEventsInLookahead;
+			const projectedTotal = retainedTotal + expectedEventsInLookahead;
+			const projectedBad = retainedBad + projectedFailures;
+			const projectedSli = projectedTotal === 0 ? void 0 : (projectedTotal - projectedBad) / projectedTotal;
+			const allowedFailureRate = 1 - stableDefinition.target;
+			const remainingFailures = allowedFailureRate * retainedTotal - retainedBad;
+			const netFailureRate = baselineFailureRate - allowedFailureRate;
+			const eventRate = expectedEventsInLookahead / forecastOptions.lookaheadMs;
+			const timeToExhaustionMs = remainingFailures <= 0 ? 0 : netFailureRate > 0 && eventRate > 0 ? remainingFailures / (netFailureRate * eventRate) : void 0;
+			const alerting = projectedSli !== void 0 && projectedSli < stableDefinition.target;
+			return {
+				name: stableDefinition.name,
+				target: stableDefinition.target,
+				observedAt,
+				baselineMs: forecastOptions.baselineMs,
+				lookaheadMs: forecastOptions.lookaheadMs,
+				baselineTotal,
+				baselineBad,
+				baselineFailureRate,
+				retainedTotal,
+				retainedBad,
+				projectedTotal,
+				projectedBad,
+				projectedSli,
+				timeToExhaustionMs,
+				alerting,
+				reason: alerting ? "projected-budget-exhaustion" : "within-budget"
+			};
+		},
+		reset() {
+			observations.length = 0;
+			firstLiveIndex = 0;
+		}
+	};
+}
+/**
+* Evaluate a dual-window burn-rate alert.
+*
+* Both windows must exceed their threshold. The short window catches a sharp
+* regression while the long window rejects brief spikes.
+*/
+function evaluateBurnRateAlert(options) {
+	validateThreshold("shortThreshold", options.shortThreshold);
+	validateThreshold("longThreshold", options.longThreshold);
+	if (options.shortWindow.name !== options.longWindow.name || options.shortWindow.target !== options.longWindow.target) throw new Error("Burn-rate windows must describe the same SLO name and target");
+	if (options.shortWindow.total === 0 || options.longWindow.total === 0) return {
+		alerting: false,
+		reason: "no-traffic",
+		shortBurnRate: options.shortWindow.burnRate,
+		longBurnRate: options.longWindow.burnRate
+	};
+	if (options.shortWindow.burnRate < options.shortThreshold) return {
+		alerting: false,
+		reason: "short-window-below-threshold",
+		shortBurnRate: options.shortWindow.burnRate,
+		longBurnRate: options.longWindow.burnRate
+	};
+	if (options.longWindow.burnRate < options.longThreshold) return {
+		alerting: false,
+		reason: "long-window-below-threshold",
+		shortBurnRate: options.shortWindow.burnRate,
+		longBurnRate: options.longWindow.burnRate
+	};
+	return {
+		alerting: true,
+		reason: "burn-rate-thresholds-exceeded",
+		shortBurnRate: options.shortWindow.burnRate,
+		longBurnRate: options.longWindow.burnRate
+	};
+}
+
+//#endregion
+export { createSloTracker, evaluateBurnRateAlert };
+//# sourceMappingURL=slo.js.map

package/dist/slo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"slo.js","names":["otelTrace"],"sources":["../src/slo.ts"],"sourcesContent":["/**\n * Service level objective tracking and burn-rate evaluation.\n *\n * The tracker keeps a bounded rolling window in memory, records low-cardinality\n * OpenTelemetry metrics, and returns snapshots that callers can feed into alert\n * evaluation. Production systems can persist the emitted metrics in their\n * telemetry backend while tests use the same calculations in process.\n */\n\nimport {\n  trace as otelTrace,\n  type Attributes,\n  type Counter,\n  type Histogram,\n} from '@opentelemetry/api';\nimport { getConfig } from './config';\n\nexport type SloOutcome = 'good' | 'bad';\n\nexport interface SloDefinition {\n  /** Stable identifier used in metric attributes and alerts. */\n  name: string;\n  /** Required success ratio, expressed as a value between 0 and 1. */\n  target: number;\n  /** Rolling observation window in milliseconds. */\n  windowMs: number;\n}\n\nexport interface SloTrackerOptions {\n  /** Clock override for deterministic tests. */\n  now?: () => number;\n  /** Disable metric recording when calculations run outside an initialized SDK. */\n  recordMetrics?: boolean;\n}\n\nexport interface SloSnapshot extends SloDefinition {\n  observedAt: number;\n  total: number;\n  good: number;\n  bad: number;\n  /** Observed good-event ratio. Undefined until the tracker sees an event. */\n  sli?: number;\n  /** Fraction of events the objective permits to fail. */\n  errorBudgetFraction: number;\n  /** Fraction of the available error budget consumed in this window. */\n  budgetConsumed: number;\n  /** Remaining budget fraction. Negative values show overspend. */\n  budgetRemaining: number;\n  /** Observed failure ratio divided by the permitted failure ratio. */\n  burnRate: number;\n  meetsTarget: boolean;\n}\n\nexport interface SloTracker {\n  readonly definition: Readonly<SloDefinition>;\n  record(outcome: SloOutcome, attributes?: Attributes): SloSnapshot;\n  snapshot(at?: number): SloSnapshot;\n  forecast(options: SloForecastOptions): SloForecast;\n  reset(): void;\n}\n\nexport interface SloForecastOptions {\n  /** Recent observation period used to estimate the future failure rate. */\n  baselineMs: number;\n  /** Future period covered by the forecast. Must not exceed 4x the baseline. */\n  lookaheadMs: number;\n  /**\n   * Expected eligible events during the lookahead. Defaults to the event rate\n   * observed during the baseline.\n   */\n  expectedEventsInLookahead?: number;\n}\n\nexport interface SloForecast {\n  name: string;\n  target: number;\n  observedAt: number;\n  baselineMs: number;\n  lookaheadMs: number;\n  baselineTotal: number;\n  baselineBad: number;\n  baselineFailureRate: number;\n  retainedTotal: number;\n  retainedBad: number;\n  projectedTotal: number;\n  projectedBad: number;\n  projectedSli?: number;\n  /** Milliseconds until the retained and projected error budget is exhausted. */\n  timeToExhaustionMs?: number;\n  alerting: boolean;\n  reason:\n    'no-baseline-traffic' | 'within-budget' | 'projected-budget-exhaustion';\n}\n\nexport interface BurnRateAlertOptions {\n  shortWindow: SloSnapshot;\n  longWindow: SloSnapshot;\n  shortThreshold: number;\n  longThreshold: number;\n}\n\nexport interface BurnRateAlertDecision {\n  alerting: boolean;\n  reason:\n    | 'burn-rate-thresholds-exceeded'\n    | 'short-window-below-threshold'\n    | 'long-window-below-threshold'\n    | 'no-traffic';\n  shortBurnRate: number;\n  longBurnRate: number;\n}\n\ninterface Observation {\n  outcome: SloOutcome;\n  timestamp: number;\n}\n\nfunction validateDefinition(definition: SloDefinition): void {\n  if (!definition.name.trim()) {\n    throw new Error('SLO name must not be empty');\n  }\n  if (\n    !Number.isFinite(definition.target) ||\n    definition.target <= 0 ||\n    definition.target >= 1\n  ) {\n    throw new Error('SLO target must be greater than 0 and less than 1');\n  }\n  if (!Number.isFinite(definition.windowMs) || definition.windowMs <= 0) {\n    throw new Error('SLO windowMs must be greater than 0');\n  }\n}\n\nfunction validateThreshold(name: string, threshold: number): void {\n  if (!Number.isFinite(threshold) || threshold <= 0) {\n    throw new Error(`${name} must be greater than 0`);\n  }\n}\n\nfunction validateForecastOptions(options: SloForecastOptions): void {\n  if (!Number.isFinite(options.baselineMs) || options.baselineMs <= 0) {\n    throw new Error('baselineMs must be greater than 0');\n  }\n  if (!Number.isFinite(options.lookaheadMs) || options.lookaheadMs <= 0) {\n    throw new Error('lookaheadMs must be greater than 0');\n  }\n  if (options.lookaheadMs > options.baselineMs * 4) {\n    throw new Error('lookaheadMs must not exceed 4 times baselineMs');\n  }\n  if (\n    options.expectedEventsInLookahead !== undefined &&\n    (!Number.isFinite(options.expectedEventsInLookahead) ||\n      options.expectedEventsInLookahead < 0)\n  ) {\n    throw new Error('expectedEventsInLookahead must not be negative');\n  }\n}\n\n/**\n * Track good and bad events for one rolling-window service level objective.\n */\nexport function createSloTracker(\n  definition: SloDefinition,\n  options: SloTrackerOptions = {},\n): SloTracker {\n  validateDefinition(definition);\n\n  const stableDefinition = Object.freeze({ ...definition });\n  const now = options.now ?? Date.now;\n  const observations: Observation[] = [];\n  let firstLiveIndex = 0;\n\n  let outcomeCounter: Counter | undefined;\n  let burnRateHistogram: Histogram | undefined;\n\n  if (options.recordMetrics !== false) {\n    const meter = getConfig().meter;\n    outcomeCounter = meter.createCounter('autotel.slo.outcomes', {\n      description:\n        'Good and bad events recorded against a service level objective',\n      unit: '1',\n    });\n    burnRateHistogram = meter.createHistogram('autotel.slo.burn_rate', {\n      description: 'Error-budget burn rate for a service level objective',\n      unit: '1',\n    });\n  }\n\n  const prune = (at: number): void => {\n    const cutoff = at - stableDefinition.windowMs;\n    while (\n      firstLiveIndex < observations.length &&\n      observations[firstLiveIndex]!.timestamp < cutoff\n    ) {\n      firstLiveIndex += 1;\n    }\n\n    if (firstLiveIndex > 1024 && firstLiveIndex * 2 >= observations.length) {\n      observations.splice(0, firstLiveIndex);\n      firstLiveIndex = 0;\n    }\n  };\n\n  const calculate = (at: number): SloSnapshot => {\n    prune(at);\n\n    let good = 0;\n    for (let index = firstLiveIndex; index < observations.length; index += 1) {\n      if (observations[index]!.outcome === 'good') good += 1;\n    }\n\n    const total = observations.length - firstLiveIndex;\n    const bad = total - good;\n    const sli = total === 0 ? undefined : good / total;\n    const errorBudgetFraction = 1 - stableDefinition.target;\n    const observedBadFraction = total === 0 ? 0 : bad / total;\n    const burnRate = observedBadFraction / errorBudgetFraction;\n    const budgetConsumed = burnRate;\n\n    return {\n      ...stableDefinition,\n      observedAt: at,\n      total,\n      good,\n      bad,\n      sli,\n      errorBudgetFraction,\n      budgetConsumed,\n      budgetRemaining: 1 - budgetConsumed,\n      burnRate,\n      meetsTarget: sli === undefined || sli >= stableDefinition.target,\n    };\n  };\n\n  return {\n    definition: stableDefinition,\n\n    record(outcome: SloOutcome, attributes: Attributes = {}): SloSnapshot {\n      if (outcome !== 'good' && outcome !== 'bad') {\n        throw new Error('SLO outcome must be \"good\" or \"bad\"');\n      }\n\n      const timestamp = now();\n      observations.push({ outcome, timestamp });\n      const current = calculate(timestamp);\n      const metricAttributes: Attributes = {\n        ...attributes,\n        'slo.name': stableDefinition.name,\n        'slo.outcome': outcome,\n      };\n\n      outcomeCounter?.add(1, metricAttributes);\n      burnRateHistogram?.record(current.burnRate, {\n        'slo.name': stableDefinition.name,\n      });\n\n      const activeSpan = otelTrace.getActiveSpan();\n      activeSpan?.setAttributes({\n        'slo.name': stableDefinition.name,\n        'slo.target': stableDefinition.target,\n        'slo.outcome': outcome,\n        'slo.burn_rate': current.burnRate,\n      });\n\n      return current;\n    },\n\n    snapshot(at = now()): SloSnapshot {\n      return calculate(at);\n    },\n\n    forecast(forecastOptions: SloForecastOptions): SloForecast {\n      validateForecastOptions(forecastOptions);\n      if (forecastOptions.baselineMs > stableDefinition.windowMs) {\n        throw new Error('baselineMs must not exceed the SLO windowMs');\n      }\n      const observedAt = now();\n      prune(observedAt);\n\n      const baselineCutoff = observedAt - forecastOptions.baselineMs;\n      const retainedCutoff =\n        observedAt + forecastOptions.lookaheadMs - stableDefinition.windowMs;\n      let baselineTotal = 0;\n      let baselineBad = 0;\n      let retainedTotal = 0;\n      let retainedBad = 0;\n\n      for (\n        let index = firstLiveIndex;\n        index < observations.length;\n        index += 1\n      ) {\n        const observation = observations[index]!;\n        if (observation.timestamp >= baselineCutoff) {\n          baselineTotal += 1;\n          if (observation.outcome === 'bad') baselineBad += 1;\n        }\n        if (observation.timestamp >= retainedCutoff) {\n          retainedTotal += 1;\n          if (observation.outcome === 'bad') retainedBad += 1;\n        }\n      }\n\n      if (baselineTotal === 0) {\n        return {\n          name: stableDefinition.name,\n          target: stableDefinition.target,\n          observedAt,\n          baselineMs: forecastOptions.baselineMs,\n          lookaheadMs: forecastOptions.lookaheadMs,\n          baselineTotal: 0,\n          baselineBad: 0,\n          baselineFailureRate: 0,\n          retainedTotal,\n          retainedBad,\n          projectedTotal: retainedTotal,\n          projectedBad: retainedBad,\n          projectedSli:\n            retainedTotal === 0\n              ? undefined\n              : (retainedTotal - retainedBad) / retainedTotal,\n          alerting: false,\n          reason: 'no-baseline-traffic',\n        };\n      }\n\n      const baselineFailureRate = baselineBad / baselineTotal;\n      const expectedEventsInLookahead =\n        forecastOptions.expectedEventsInLookahead ??\n        (baselineTotal * forecastOptions.lookaheadMs) /\n          forecastOptions.baselineMs;\n      const projectedFailures = baselineFailureRate * expectedEventsInLookahead;\n      const projectedTotal = retainedTotal + expectedEventsInLookahead;\n      const projectedBad = retainedBad + projectedFailures;\n      const projectedSli =\n        projectedTotal === 0\n          ? undefined\n          : (projectedTotal - projectedBad) / projectedTotal;\n      const allowedFailureRate = 1 - stableDefinition.target;\n      const remainingFailures =\n        allowedFailureRate * retainedTotal - retainedBad;\n      const netFailureRate = baselineFailureRate - allowedFailureRate;\n      const eventRate = expectedEventsInLookahead / forecastOptions.lookaheadMs;\n      const timeToExhaustionMs =\n        remainingFailures <= 0\n          ? 0\n          : netFailureRate > 0 && eventRate > 0\n            ? remainingFailures / (netFailureRate * eventRate)\n            : undefined;\n      const alerting =\n        projectedSli !== undefined && projectedSli < stableDefinition.target;\n\n      return {\n        name: stableDefinition.name,\n        target: stableDefinition.target,\n        observedAt,\n        baselineMs: forecastOptions.baselineMs,\n        lookaheadMs: forecastOptions.lookaheadMs,\n        baselineTotal,\n        baselineBad,\n        baselineFailureRate,\n        retainedTotal,\n        retainedBad,\n        projectedTotal,\n        projectedBad,\n        projectedSli,\n        timeToExhaustionMs,\n        alerting,\n        reason: alerting ? 'projected-budget-exhaustion' : 'within-budget',\n      };\n    },\n\n    reset(): void {\n      observations.length = 0;\n      firstLiveIndex = 0;\n    },\n  };\n}\n\n/**\n * Evaluate a dual-window burn-rate alert.\n *\n * Both windows must exceed their threshold. The short window catches a sharp\n * regression while the long window rejects brief spikes.\n */\nexport function evaluateBurnRateAlert(\n  options: BurnRateAlertOptions,\n): BurnRateAlertDecision {\n  validateThreshold('shortThreshold', options.shortThreshold);\n  validateThreshold('longThreshold', options.longThreshold);\n\n  if (\n    options.shortWindow.name !== options.longWindow.name ||\n    options.shortWindow.target !== options.longWindow.target\n  ) {\n    throw new Error(\n      'Burn-rate windows must describe the same SLO name and target',\n    );\n  }\n\n  if (options.shortWindow.total === 0 || options.longWindow.total === 0) {\n    return {\n      alerting: false,\n      reason: 'no-traffic',\n      shortBurnRate: options.shortWindow.burnRate,\n      longBurnRate: options.longWindow.burnRate,\n    };\n  }\n\n  if (options.shortWindow.burnRate < options.shortThreshold) {\n    return {\n      alerting: false,\n      reason: 'short-window-below-threshold',\n      shortBurnRate: options.shortWindow.burnRate,\n      longBurnRate: options.longWindow.burnRate,\n    };\n  }\n\n  if (options.longWindow.burnRate < options.longThreshold) {\n    return {\n      alerting: false,\n      reason: 'long-window-below-threshold',\n      shortBurnRate: options.shortWindow.burnRate,\n      longBurnRate: options.longWindow.burnRate,\n    };\n  }\n\n  return {\n    alerting: true,\n    reason: 'burn-rate-thresholds-exceeded',\n    shortBurnRate: options.shortWindow.burnRate,\n    longBurnRate: options.longWindow.burnRate,\n  };\n}\n"],"mappings":"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"}

package/dist/{span-name-normalizer-8ZOGJuwv.d.ts → span-name-normalizer-CN1-8C76.d.cts}

@@ -1,6 +1,5 @@
 import { ReadableSpan, Span, SpanProcessor } from "@opentelemetry/sdk-trace-base";
 import { Context } from "@opentelemetry/api";
-
 //#region src/span-name-normalizer.d.ts
 /**
  * Function to normalize a span name
@@ -67,4 +66,4 @@ declare class SpanNameNormalizingProcessor implements SpanProcessor {
 }
 //#endregion
 export { SpanNameNormalizerPreset as a, SpanNameNormalizerFn as i, NORMALIZER_PRESETS as n, SpanNameNormalizingProcessor as o, SpanNameNormalizerConfig as r, SpanNameNormalizingProcessorOptions as s, NORMALIZER_PATTERNS as t };
-//# sourceMappingURL=span-name-normalizer-8ZOGJuwv.d.ts.map
+//# sourceMappingURL=span-name-normalizer-CN1-8C76.d.cts.map

package/dist/span-name-normalizer-CN1-8C76.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"span-name-normalizer-CN1-8C76.d.cts","names":[],"sources":["../src/span-name-normalizer.ts"],"mappings":";;;;;;;;KAsCY,wBAAwB;;;;KAKxB;;;;KAKA,2BACV,uBAAuB;UAER;;;;EAIf,YAAY;;;;;cAMR;;;;;;;;;;;;;cA6BA,oBAAoB,OACxB,0BACA;;;;;;;;;;;;cAsEW,wCAAwC;mBAClC;mBACA;EAGf,YAAA,kBAAkB,eAClB,SAAS;;;;EASX,QAAQ,MAAM,MAAM,eAAe;;;;EAkBnC,MAAM,MAAM;EAIZ,cAAc;EAId,YAAY"}

package/dist/{span-name-normalizer-8ZOGJuwv.d.cts → span-name-normalizer-CN1-8C76.d.ts}

@@ -1,6 +1,5 @@
 import { ReadableSpan, Span, SpanProcessor } from "@opentelemetry/sdk-trace-base";
 import { Context } from "@opentelemetry/api";
-
 //#region src/span-name-normalizer.d.ts
 /**
  * Function to normalize a span name
@@ -67,4 +66,4 @@ declare class SpanNameNormalizingProcessor implements SpanProcessor {
 }
 //#endregion
 export { SpanNameNormalizerPreset as a, SpanNameNormalizerFn as i, NORMALIZER_PRESETS as n, SpanNameNormalizingProcessor as o, SpanNameNormalizerConfig as r, SpanNameNormalizingProcessorOptions as s, NORMALIZER_PATTERNS as t };
-//# sourceMappingURL=span-name-normalizer-8ZOGJuwv.d.cts.map
+//# sourceMappingURL=span-name-normalizer-CN1-8C76.d.ts.map

package/dist/span-name-normalizer-CN1-8C76.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"span-name-normalizer-CN1-8C76.d.ts","names":[],"sources":["../src/span-name-normalizer.ts"],"mappings":";;;;;;;;KAsCY,wBAAwB;;;;KAKxB;;;;KAKA,2BACV,uBAAuB;UAER;;;;EAIf,YAAY;;;;;cAMR;;;;;;;;;;;;;cA6BA,oBAAoB,OACxB,0BACA;;;;;;;;;;;;cAsEW,wCAAwC;mBAClC;mBACA;EAGf,YAAA,kBAAkB,eAClB,SAAS;;;;EASX,QAAQ,MAAM,MAAM,eAAe;;;;EAkBnC,MAAM,MAAM;EAIZ,cAAc;EAId,YAAY"}

package/dist/span-name-normalizer.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"span-name-normalizer.cjs","names":[],"sources":["../src/span-name-normalizer.ts"],"sourcesContent":["/**\n * Span Name Normalizer\n *\n * Normalizes span names to reduce cardinality from dynamic path segments.\n * This is critical for observability backends that charge by unique span names\n * or have cardinality limits.\n *\n * @example Basic usage with custom function\n * ```typescript\n * init({\n *   service: 'my-app',\n *   spanNameNormalizer: (name) => {\n *     return name.replace(/\\/[0-9]+/g, '/:id');\n *   }\n * })\n * ```\n *\n * @example Using built-in preset\n * ```typescript\n * init({\n *   service: 'my-app',\n *   spanNameNormalizer: 'rest-api'\n * })\n * ```\n */\n\nimport type {\n  SpanProcessor,\n  ReadableSpan,\n} from '@opentelemetry/sdk-trace-base';\nimport type { Context } from '@opentelemetry/api';\nimport type { Span } from '@opentelemetry/sdk-trace-base';\n\n/**\n * Function to normalize a span name\n * @param name - The original span name\n * @returns The normalized span name\n */\nexport type SpanNameNormalizerFn = (name: string) => string;\n\n/**\n * Built-in normalizer preset names\n */\nexport type SpanNameNormalizerPreset = 'rest-api' | 'graphql' | 'minimal';\n\n/**\n * Normalizer config - either a function or a preset name\n */\nexport type SpanNameNormalizerConfig =\n  | SpanNameNormalizerFn\n  | SpanNameNormalizerPreset;\n\nexport interface SpanNameNormalizingProcessorOptions {\n  /**\n   * Normalizer function or preset name\n   */\n  normalizer: SpanNameNormalizerConfig;\n}\n\n/**\n * Built-in normalizer patterns\n */\nconst NORMALIZER_PATTERNS = {\n  // Numeric IDs: /users/123 → /users/:id\n  numericId: /\\/\\d+(?=\\/|$)/g,\n\n  // UUIDs: /users/550e8400-e29b-41d4-a716-446655440000 → /users/:uuid\n  uuid: /\\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}(?=\\/|$)/gi,\n\n  // Short UUIDs (without dashes): /users/550e8400e29b41d4a716446655440000 → /users/:uuid\n  shortUuid: /\\/[0-9a-f]{32}(?=\\/|$)/gi,\n\n  // MongoDB ObjectIds: /docs/507f1f77bcf86cd799439011 → /docs/:objectId\n  objectId: /\\/[0-9a-f]{24}(?=\\/|$)/gi,\n\n  // Hashes (6+ hex chars): /assets/abc123def.js → /assets/:hash.js\n  hash: /\\/[0-9a-f]{6,}(?=\\.[a-z]+$)/gi,\n\n  // ISO dates: /logs/2024-01-15 → /logs/:date\n  isoDate: /\\/\\d{4}-\\d{2}-\\d{2}(?=\\/|$)/g,\n\n  // Timestamps: /events/1705334400 → /events/:timestamp\n  timestamp: /\\/1[0-9]{9}(?=\\/|$)/g,\n\n  // Email-like segments: /users/john@example.com → /users/:email\n  email: /\\/[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}(?=\\/|$)/g,\n} as const;\n\n/**\n * Built-in normalizer presets\n */\nconst NORMALIZER_PRESETS: Record<\n  SpanNameNormalizerPreset,\n  SpanNameNormalizerFn\n> = {\n  /**\n   * REST API preset - normalizes common REST path patterns\n   * Handles: numeric IDs, UUIDs, ObjectIds, dates, timestamps, emails\n   */\n  'rest-api': (name: string): string => {\n    return name\n      .replaceAll(NORMALIZER_PATTERNS.uuid, '/:uuid')\n      .replaceAll(NORMALIZER_PATTERNS.shortUuid, '/:uuid')\n      .replaceAll(NORMALIZER_PATTERNS.objectId, '/:objectId')\n      .replaceAll(NORMALIZER_PATTERNS.isoDate, '/:date')\n      .replaceAll(NORMALIZER_PATTERNS.timestamp, '/:timestamp')\n      .replaceAll(NORMALIZER_PATTERNS.email, '/:email')\n      .replaceAll(NORMALIZER_PATTERNS.numericId, '/:id');\n  },\n\n  /**\n   * GraphQL preset - normalizes GraphQL operation names and paths\n   * Keeps query/mutation names but normalizes embedded IDs\n   */\n  graphql: (name: string): string => {\n    // For GraphQL, normalize both path-style and embedded IDs\n    return name\n      .replaceAll(NORMALIZER_PATTERNS.uuid, '/:uuid')\n      .replaceAll(NORMALIZER_PATTERNS.numericId, '/:id');\n  },\n\n  /**\n   * Minimal preset - only normalizes numeric IDs and UUIDs\n   */\n  minimal: (name: string): string => {\n    return name\n      .replaceAll(NORMALIZER_PATTERNS.uuid, '/:uuid')\n      .replaceAll(NORMALIZER_PATTERNS.numericId, '/:id');\n  },\n};\n\n/**\n * Resolve normalizer config to a function\n */\nfunction resolveNormalizer(\n  config: SpanNameNormalizerConfig,\n): SpanNameNormalizerFn {\n  if (typeof config === 'function') {\n    return config;\n  }\n\n  const preset = NORMALIZER_PRESETS[config];\n  if (!preset) {\n    throw new Error(\n      `Unknown span name normalizer preset: \"${config}\". ` +\n        `Available presets: ${Object.keys(NORMALIZER_PRESETS).join(', ')}`,\n    );\n  }\n\n  return preset;\n}\n\n/**\n * Span processor that normalizes span names to reduce cardinality.\n *\n * Normalization happens in onStart() when we have access to the mutable Span.\n * This allows us to call span.updateName() before the span is finalized.\n *\n * Common use cases:\n * - REST APIs: /users/123/posts/456 → /users/:id/posts/:id\n * - UUIDs: /items/550e8400-e29b-41d4-a716-446655440000 → /items/:uuid\n * - Dates: /logs/2024-01-15 → /logs/:date\n */\nexport class SpanNameNormalizingProcessor implements SpanProcessor {\n  private readonly wrappedProcessor: SpanProcessor;\n  private readonly normalizer: SpanNameNormalizerFn;\n\n  constructor(\n    wrappedProcessor: SpanProcessor,\n    options: SpanNameNormalizingProcessorOptions,\n  ) {\n    this.wrappedProcessor = wrappedProcessor;\n    this.normalizer = resolveNormalizer(options.normalizer);\n  }\n\n  /**\n   * Normalize span name on start (when Span is mutable)\n   */\n  onStart(span: Span, parentContext: Context): void {\n    try {\n      const originalName = span.name;\n      const normalizedName = this.normalizer(originalName);\n\n      if (normalizedName !== originalName) {\n        span.updateName(normalizedName);\n      }\n    } catch {\n      // If normalizer throws, keep original name (fail-open)\n    }\n\n    this.wrappedProcessor.onStart(span, parentContext);\n  }\n\n  /**\n   * Pass through onEnd unchanged\n   */\n  onEnd(span: ReadableSpan): void {\n    this.wrappedProcessor.onEnd(span);\n  }\n\n  forceFlush(): Promise<void> {\n    return this.wrappedProcessor.forceFlush();\n  }\n\n  shutdown(): Promise<void> {\n    return this.wrappedProcessor.shutdown();\n  }\n}\n\n/**\n * Export built-in patterns for advanced users who want to compose their own normalizers\n */\nexport { NORMALIZER_PATTERNS, NORMALIZER_PRESETS };\n"],"mappings":";;;;;;AA8DA,MAAM,sBAAsB;CAE1B,WAAW;CAGX,MAAM;CAGN,WAAW;CAGX,UAAU;CAGV,MAAM;CAGN,SAAS;CAGT,WAAW;CAGX,OAAO;AACT;;;;AAKA,MAAM,qBAGF;;;;;CAKF,aAAa,SAAyB;EACpC,OAAO,KACJ,WAAW,oBAAoB,MAAM,QAAQ,CAAC,CAC9C,WAAW,oBAAoB,WAAW,QAAQ,CAAC,CACnD,WAAW,oBAAoB,UAAU,YAAY,CAAC,CACtD,WAAW,oBAAoB,SAAS,QAAQ,CAAC,CACjD,WAAW,oBAAoB,WAAW,aAAa,CAAC,CACxD,WAAW,oBAAoB,OAAO,SAAS,CAAC,CAChD,WAAW,oBAAoB,WAAW,MAAM;CACrD;;;;;CAMA,UAAU,SAAyB;EAEjC,OAAO,KACJ,WAAW,oBAAoB,MAAM,QAAQ,CAAC,CAC9C,WAAW,oBAAoB,WAAW,MAAM;CACrD;;;;CAKA,UAAU,SAAyB;EACjC,OAAO,KACJ,WAAW,oBAAoB,MAAM,QAAQ,CAAC,CAC9C,WAAW,oBAAoB,WAAW,MAAM;CACrD;AACF;;;;AAKA,SAAS,kBACP,QACsB;CACtB,IAAI,OAAO,WAAW,YACpB,OAAO;CAGT,MAAM,SAAS,mBAAmB;CAClC,IAAI,CAAC,QACH,MAAM,IAAI,MACR,yCAAyC,OAAO,wBACxB,OAAO,KAAK,kBAAkB,CAAC,CAAC,KAAK,IAAI,GACnE;CAGF,OAAO;AACT;;;;;;;;;;;;AAaA,IAAa,+BAAb,MAAmE;CACjE,AAAiB;CACjB,AAAiB;CAEjB,YACE,kBACA,SACA;EACA,KAAK,mBAAmB;EACxB,KAAK,aAAa,kBAAkB,QAAQ,UAAU;CACxD;;;;CAKA,QAAQ,MAAY,eAA8B;EAChD,IAAI;GACF,MAAM,eAAe,KAAK;GAC1B,MAAM,iBAAiB,KAAK,WAAW,YAAY;GAEnD,IAAI,mBAAmB,cACrB,KAAK,WAAW,cAAc;EAElC,QAAQ,CAER;EAEA,KAAK,iBAAiB,QAAQ,MAAM,aAAa;CACnD;;;;CAKA,MAAM,MAA0B;EAC9B,KAAK,iBAAiB,MAAM,IAAI;CAClC;CAEA,aAA4B;EAC1B,OAAO,KAAK,iBAAiB,WAAW;CAC1C;CAEA,WAA0B;EACxB,OAAO,KAAK,iBAAiB,SAAS;CACxC;AACF"}
+{"version":3,"file":"span-name-normalizer.cjs","names":[],"sources":["../src/span-name-normalizer.ts"],"sourcesContent":["/**\n * Span Name Normalizer\n *\n * Normalizes span names to reduce cardinality from dynamic path segments.\n * This is critical for observability backends that charge by unique span names\n * or have cardinality limits.\n *\n * @example Basic usage with custom function\n * ```typescript\n * init({\n *   service: 'my-app',\n *   spanNameNormalizer: (name) => {\n *     return name.replace(/\\/[0-9]+/g, '/:id');\n *   }\n * })\n * ```\n *\n * @example Using built-in preset\n * ```typescript\n * init({\n *   service: 'my-app',\n *   spanNameNormalizer: 'rest-api'\n * })\n * ```\n */\n\nimport type {\n  SpanProcessor,\n  ReadableSpan,\n} from '@opentelemetry/sdk-trace-base';\nimport type { Context } from '@opentelemetry/api';\nimport type { Span } from '@opentelemetry/sdk-trace-base';\n\n/**\n * Function to normalize a span name\n * @param name - The original span name\n * @returns The normalized span name\n */\nexport type SpanNameNormalizerFn = (name: string) => string;\n\n/**\n * Built-in normalizer preset names\n */\nexport type SpanNameNormalizerPreset = 'rest-api' | 'graphql' | 'minimal';\n\n/**\n * Normalizer config - either a function or a preset name\n */\nexport type SpanNameNormalizerConfig =\n  SpanNameNormalizerFn | SpanNameNormalizerPreset;\n\nexport interface SpanNameNormalizingProcessorOptions {\n  /**\n   * Normalizer function or preset name\n   */\n  normalizer: SpanNameNormalizerConfig;\n}\n\n/**\n * Built-in normalizer patterns\n */\nconst NORMALIZER_PATTERNS = {\n  // Numeric IDs: /users/123 → /users/:id\n  numericId: /\\/\\d+(?=\\/|$)/g,\n\n  // UUIDs: /users/550e8400-e29b-41d4-a716-446655440000 → /users/:uuid\n  uuid: /\\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}(?=\\/|$)/gi,\n\n  // Short UUIDs (without dashes): /users/550e8400e29b41d4a716446655440000 → /users/:uuid\n  shortUuid: /\\/[0-9a-f]{32}(?=\\/|$)/gi,\n\n  // MongoDB ObjectIds: /docs/507f1f77bcf86cd799439011 → /docs/:objectId\n  objectId: /\\/[0-9a-f]{24}(?=\\/|$)/gi,\n\n  // Hashes (6+ hex chars): /assets/abc123def.js → /assets/:hash.js\n  hash: /\\/[0-9a-f]{6,}(?=\\.[a-z]+$)/gi,\n\n  // ISO dates: /logs/2024-01-15 → /logs/:date\n  isoDate: /\\/\\d{4}-\\d{2}-\\d{2}(?=\\/|$)/g,\n\n  // Timestamps: /events/1705334400 → /events/:timestamp\n  timestamp: /\\/1[0-9]{9}(?=\\/|$)/g,\n\n  // Email-like segments: /users/john@example.com → /users/:email\n  email: /\\/[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}(?=\\/|$)/g,\n} as const;\n\n/**\n * Built-in normalizer presets\n */\nconst NORMALIZER_PRESETS: Record<\n  SpanNameNormalizerPreset,\n  SpanNameNormalizerFn\n> = {\n  /**\n   * REST API preset - normalizes common REST path patterns\n   * Handles: numeric IDs, UUIDs, ObjectIds, dates, timestamps, emails\n   */\n  'rest-api': (name: string): string => {\n    return name\n      .replaceAll(NORMALIZER_PATTERNS.uuid, '/:uuid')\n      .replaceAll(NORMALIZER_PATTERNS.shortUuid, '/:uuid')\n      .replaceAll(NORMALIZER_PATTERNS.objectId, '/:objectId')\n      .replaceAll(NORMALIZER_PATTERNS.isoDate, '/:date')\n      .replaceAll(NORMALIZER_PATTERNS.timestamp, '/:timestamp')\n      .replaceAll(NORMALIZER_PATTERNS.email, '/:email')\n      .replaceAll(NORMALIZER_PATTERNS.numericId, '/:id');\n  },\n\n  /**\n   * GraphQL preset - normalizes GraphQL operation names and paths\n   * Keeps query/mutation names but normalizes embedded IDs\n   */\n  graphql: (name: string): string => {\n    // For GraphQL, normalize both path-style and embedded IDs\n    return name\n      .replaceAll(NORMALIZER_PATTERNS.uuid, '/:uuid')\n      .replaceAll(NORMALIZER_PATTERNS.numericId, '/:id');\n  },\n\n  /**\n   * Minimal preset - only normalizes numeric IDs and UUIDs\n   */\n  minimal: (name: string): string => {\n    return name\n      .replaceAll(NORMALIZER_PATTERNS.uuid, '/:uuid')\n      .replaceAll(NORMALIZER_PATTERNS.numericId, '/:id');\n  },\n};\n\n/**\n * Resolve normalizer config to a function\n */\nfunction resolveNormalizer(\n  config: SpanNameNormalizerConfig,\n): SpanNameNormalizerFn {\n  if (typeof config === 'function') {\n    return config;\n  }\n\n  const preset = NORMALIZER_PRESETS[config];\n  if (!preset) {\n    throw new Error(\n      `Unknown span name normalizer preset: \"${config}\". ` +\n        `Available presets: ${Object.keys(NORMALIZER_PRESETS).join(', ')}`,\n    );\n  }\n\n  return preset;\n}\n\n/**\n * Span processor that normalizes span names to reduce cardinality.\n *\n * Normalization happens in onStart() when we have access to the mutable Span.\n * This allows us to call span.updateName() before the span is finalized.\n *\n * Common use cases:\n * - REST APIs: /users/123/posts/456 → /users/:id/posts/:id\n * - UUIDs: /items/550e8400-e29b-41d4-a716-446655440000 → /items/:uuid\n * - Dates: /logs/2024-01-15 → /logs/:date\n */\nexport class SpanNameNormalizingProcessor implements SpanProcessor {\n  private readonly wrappedProcessor: SpanProcessor;\n  private readonly normalizer: SpanNameNormalizerFn;\n\n  constructor(\n    wrappedProcessor: SpanProcessor,\n    options: SpanNameNormalizingProcessorOptions,\n  ) {\n    this.wrappedProcessor = wrappedProcessor;\n    this.normalizer = resolveNormalizer(options.normalizer);\n  }\n\n  /**\n   * Normalize span name on start (when Span is mutable)\n   */\n  onStart(span: Span, parentContext: Context): void {\n    try {\n      const originalName = span.name;\n      const normalizedName = this.normalizer(originalName);\n\n      if (normalizedName !== originalName) {\n        span.updateName(normalizedName);\n      }\n    } catch {\n      // If normalizer throws, keep original name (fail-open)\n    }\n\n    this.wrappedProcessor.onStart(span, parentContext);\n  }\n\n  /**\n   * Pass through onEnd unchanged\n   */\n  onEnd(span: ReadableSpan): void {\n    this.wrappedProcessor.onEnd(span);\n  }\n\n  forceFlush(): Promise<void> {\n    return this.wrappedProcessor.forceFlush();\n  }\n\n  shutdown(): Promise<void> {\n    return this.wrappedProcessor.shutdown();\n  }\n}\n\n/**\n * Export built-in patterns for advanced users who want to compose their own normalizers\n */\nexport { NORMALIZER_PATTERNS, NORMALIZER_PRESETS };\n"],"mappings":";;;;;;AA6DA,MAAM,sBAAsB;CAE1B,WAAW;CAGX,MAAM;CAGN,WAAW;CAGX,UAAU;CAGV,MAAM;CAGN,SAAS;CAGT,WAAW;CAGX,OAAO;AACT;;;;AAKA,MAAM,qBAGF;;;;;CAKF,aAAa,SAAyB;EACpC,OAAO,KACJ,WAAW,oBAAoB,MAAM,QAAQ,CAAC,CAC9C,WAAW,oBAAoB,WAAW,QAAQ,CAAC,CACnD,WAAW,oBAAoB,UAAU,YAAY,CAAC,CACtD,WAAW,oBAAoB,SAAS,QAAQ,CAAC,CACjD,WAAW,oBAAoB,WAAW,aAAa,CAAC,CACxD,WAAW,oBAAoB,OAAO,SAAS,CAAC,CAChD,WAAW,oBAAoB,WAAW,MAAM;CACrD;;;;;CAMA,UAAU,SAAyB;EAEjC,OAAO,KACJ,WAAW,oBAAoB,MAAM,QAAQ,CAAC,CAC9C,WAAW,oBAAoB,WAAW,MAAM;CACrD;;;;CAKA,UAAU,SAAyB;EACjC,OAAO,KACJ,WAAW,oBAAoB,MAAM,QAAQ,CAAC,CAC9C,WAAW,oBAAoB,WAAW,MAAM;CACrD;AACF;;;;AAKA,SAAS,kBACP,QACsB;CACtB,IAAI,OAAO,WAAW,YACpB,OAAO;CAGT,MAAM,SAAS,mBAAmB;CAClC,IAAI,CAAC,QACH,MAAM,IAAI,MACR,yCAAyC,OAAO,wBACxB,OAAO,KAAK,kBAAkB,CAAC,CAAC,KAAK,IAAI,GACnE;CAGF,OAAO;AACT;;;;;;;;;;;;AAaA,IAAa,+BAAb,MAAmE;CACjE,AAAiB;CACjB,AAAiB;CAEjB,YACE,kBACA,SACA;EACA,KAAK,mBAAmB;EACxB,KAAK,aAAa,kBAAkB,QAAQ,UAAU;CACxD;;;;CAKA,QAAQ,MAAY,eAA8B;EAChD,IAAI;GACF,MAAM,eAAe,KAAK;GAC1B,MAAM,iBAAiB,KAAK,WAAW,YAAY;GAEnD,IAAI,mBAAmB,cACrB,KAAK,WAAW,cAAc;EAElC,QAAQ,CAER;EAEA,KAAK,iBAAiB,QAAQ,MAAM,aAAa;CACnD;;;;CAKA,MAAM,MAA0B;EAC9B,KAAK,iBAAiB,MAAM,IAAI;CAClC;CAEA,aAA4B;EAC1B,OAAO,KAAK,iBAAiB,WAAW;CAC1C;CAEA,WAA0B;EACxB,OAAO,KAAK,iBAAiB,SAAS;CACxC;AACF"}

package/dist/span-name-normalizer.d.cts

@@ -1,2 +1,2 @@
-import { a as SpanNameNormalizerPreset, i as SpanNameNormalizerFn, n as NORMALIZER_PRESETS, o as SpanNameNormalizingProcessor, r as SpanNameNormalizerConfig, s as SpanNameNormalizingProcessorOptions, t as NORMALIZER_PATTERNS } from "./span-name-normalizer-8ZOGJuwv.cjs";
+import { a as SpanNameNormalizerPreset, i as SpanNameNormalizerFn, n as NORMALIZER_PRESETS, o as SpanNameNormalizingProcessor, r as SpanNameNormalizerConfig, s as SpanNameNormalizingProcessorOptions, t as NORMALIZER_PATTERNS } from "./span-name-normalizer-CN1-8C76.cjs";
 export { NORMALIZER_PATTERNS, NORMALIZER_PRESETS, SpanNameNormalizerConfig, SpanNameNormalizerFn, SpanNameNormalizerPreset, SpanNameNormalizingProcessor, SpanNameNormalizingProcessorOptions };

package/dist/span-name-normalizer.d.ts

@@ -1,2 +1,2 @@
-import { a as SpanNameNormalizerPreset, i as SpanNameNormalizerFn, n as NORMALIZER_PRESETS, o as SpanNameNormalizingProcessor, r as SpanNameNormalizerConfig, s as SpanNameNormalizingProcessorOptions, t as NORMALIZER_PATTERNS } from "./span-name-normalizer-8ZOGJuwv.js";
+import { a as SpanNameNormalizerPreset, i as SpanNameNormalizerFn, n as NORMALIZER_PRESETS, o as SpanNameNormalizingProcessor, r as SpanNameNormalizerConfig, s as SpanNameNormalizingProcessorOptions, t as NORMALIZER_PATTERNS } from "./span-name-normalizer-CN1-8C76.js";
 export { NORMALIZER_PATTERNS, NORMALIZER_PRESETS, SpanNameNormalizerConfig, SpanNameNormalizerFn, SpanNameNormalizerPreset, SpanNameNormalizingProcessor, SpanNameNormalizingProcessorOptions };

package/dist/span-name-normalizer.js.map

@@ -1 +1 @@
-{"version":3,"file":"span-name-normalizer.js","names":[],"sources":["../src/span-name-normalizer.ts"],"sourcesContent":["/**\n * Span Name Normalizer\n *\n * Normalizes span names to reduce cardinality from dynamic path segments.\n * This is critical for observability backends that charge by unique span names\n * or have cardinality limits.\n *\n * @example Basic usage with custom function\n * ```typescript\n * init({\n *   service: 'my-app',\n *   spanNameNormalizer: (name) => {\n *     return name.replace(/\\/[0-9]+/g, '/:id');\n *   }\n * })\n * ```\n *\n * @example Using built-in preset\n * ```typescript\n * init({\n *   service: 'my-app',\n *   spanNameNormalizer: 'rest-api'\n * })\n * ```\n */\n\nimport type {\n  SpanProcessor,\n  ReadableSpan,\n} from '@opentelemetry/sdk-trace-base';\nimport type { Context } from '@opentelemetry/api';\nimport type { Span } from '@opentelemetry/sdk-trace-base';\n\n/**\n * Function to normalize a span name\n * @param name - The original span name\n * @returns The normalized span name\n */\nexport type SpanNameNormalizerFn = (name: string) => string;\n\n/**\n * Built-in normalizer preset names\n */\nexport type SpanNameNormalizerPreset = 'rest-api' | 'graphql' | 'minimal';\n\n/**\n * Normalizer config - either a function or a preset name\n */\nexport type SpanNameNormalizerConfig =\n  | SpanNameNormalizerFn\n  | SpanNameNormalizerPreset;\n\nexport interface SpanNameNormalizingProcessorOptions {\n  /**\n   * Normalizer function or preset name\n   */\n  normalizer: SpanNameNormalizerConfig;\n}\n\n/**\n * Built-in normalizer patterns\n */\nconst NORMALIZER_PATTERNS = {\n  // Numeric IDs: /users/123 → /users/:id\n  numericId: /\\/\\d+(?=\\/|$)/g,\n\n  // UUIDs: /users/550e8400-e29b-41d4-a716-446655440000 → /users/:uuid\n  uuid: /\\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}(?=\\/|$)/gi,\n\n  // Short UUIDs (without dashes): /users/550e8400e29b41d4a716446655440000 → /users/:uuid\n  shortUuid: /\\/[0-9a-f]{32}(?=\\/|$)/gi,\n\n  // MongoDB ObjectIds: /docs/507f1f77bcf86cd799439011 → /docs/:objectId\n  objectId: /\\/[0-9a-f]{24}(?=\\/|$)/gi,\n\n  // Hashes (6+ hex chars): /assets/abc123def.js → /assets/:hash.js\n  hash: /\\/[0-9a-f]{6,}(?=\\.[a-z]+$)/gi,\n\n  // ISO dates: /logs/2024-01-15 → /logs/:date\n  isoDate: /\\/\\d{4}-\\d{2}-\\d{2}(?=\\/|$)/g,\n\n  // Timestamps: /events/1705334400 → /events/:timestamp\n  timestamp: /\\/1[0-9]{9}(?=\\/|$)/g,\n\n  // Email-like segments: /users/john@example.com → /users/:email\n  email: /\\/[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}(?=\\/|$)/g,\n} as const;\n\n/**\n * Built-in normalizer presets\n */\nconst NORMALIZER_PRESETS: Record<\n  SpanNameNormalizerPreset,\n  SpanNameNormalizerFn\n> = {\n  /**\n   * REST API preset - normalizes common REST path patterns\n   * Handles: numeric IDs, UUIDs, ObjectIds, dates, timestamps, emails\n   */\n  'rest-api': (name: string): string => {\n    return name\n      .replaceAll(NORMALIZER_PATTERNS.uuid, '/:uuid')\n      .replaceAll(NORMALIZER_PATTERNS.shortUuid, '/:uuid')\n      .replaceAll(NORMALIZER_PATTERNS.objectId, '/:objectId')\n      .replaceAll(NORMALIZER_PATTERNS.isoDate, '/:date')\n      .replaceAll(NORMALIZER_PATTERNS.timestamp, '/:timestamp')\n      .replaceAll(NORMALIZER_PATTERNS.email, '/:email')\n      .replaceAll(NORMALIZER_PATTERNS.numericId, '/:id');\n  },\n\n  /**\n   * GraphQL preset - normalizes GraphQL operation names and paths\n   * Keeps query/mutation names but normalizes embedded IDs\n   */\n  graphql: (name: string): string => {\n    // For GraphQL, normalize both path-style and embedded IDs\n    return name\n      .replaceAll(NORMALIZER_PATTERNS.uuid, '/:uuid')\n      .replaceAll(NORMALIZER_PATTERNS.numericId, '/:id');\n  },\n\n  /**\n   * Minimal preset - only normalizes numeric IDs and UUIDs\n   */\n  minimal: (name: string): string => {\n    return name\n      .replaceAll(NORMALIZER_PATTERNS.uuid, '/:uuid')\n      .replaceAll(NORMALIZER_PATTERNS.numericId, '/:id');\n  },\n};\n\n/**\n * Resolve normalizer config to a function\n */\nfunction resolveNormalizer(\n  config: SpanNameNormalizerConfig,\n): SpanNameNormalizerFn {\n  if (typeof config === 'function') {\n    return config;\n  }\n\n  const preset = NORMALIZER_PRESETS[config];\n  if (!preset) {\n    throw new Error(\n      `Unknown span name normalizer preset: \"${config}\". ` +\n        `Available presets: ${Object.keys(NORMALIZER_PRESETS).join(', ')}`,\n    );\n  }\n\n  return preset;\n}\n\n/**\n * Span processor that normalizes span names to reduce cardinality.\n *\n * Normalization happens in onStart() when we have access to the mutable Span.\n * This allows us to call span.updateName() before the span is finalized.\n *\n * Common use cases:\n * - REST APIs: /users/123/posts/456 → /users/:id/posts/:id\n * - UUIDs: /items/550e8400-e29b-41d4-a716-446655440000 → /items/:uuid\n * - Dates: /logs/2024-01-15 → /logs/:date\n */\nexport class SpanNameNormalizingProcessor implements SpanProcessor {\n  private readonly wrappedProcessor: SpanProcessor;\n  private readonly normalizer: SpanNameNormalizerFn;\n\n  constructor(\n    wrappedProcessor: SpanProcessor,\n    options: SpanNameNormalizingProcessorOptions,\n  ) {\n    this.wrappedProcessor = wrappedProcessor;\n    this.normalizer = resolveNormalizer(options.normalizer);\n  }\n\n  /**\n   * Normalize span name on start (when Span is mutable)\n   */\n  onStart(span: Span, parentContext: Context): void {\n    try {\n      const originalName = span.name;\n      const normalizedName = this.normalizer(originalName);\n\n      if (normalizedName !== originalName) {\n        span.updateName(normalizedName);\n      }\n    } catch {\n      // If normalizer throws, keep original name (fail-open)\n    }\n\n    this.wrappedProcessor.onStart(span, parentContext);\n  }\n\n  /**\n   * Pass through onEnd unchanged\n   */\n  onEnd(span: ReadableSpan): void {\n    this.wrappedProcessor.onEnd(span);\n  }\n\n  forceFlush(): Promise<void> {\n    return this.wrappedProcessor.forceFlush();\n  }\n\n  shutdown(): Promise<void> {\n    return this.wrappedProcessor.shutdown();\n  }\n}\n\n/**\n * Export built-in patterns for advanced users who want to compose their own normalizers\n */\nexport { NORMALIZER_PATTERNS, NORMALIZER_PRESETS };\n"],"mappings":";;;;AA8DA,MAAM,sBAAsB;CAE1B,WAAW;CAGX,MAAM;CAGN,WAAW;CAGX,UAAU;CAGV,MAAM;CAGN,SAAS;CAGT,WAAW;CAGX,OAAO;AACT;;;;AAKA,MAAM,qBAGF;;;;;CAKF,aAAa,SAAyB;EACpC,OAAO,KACJ,WAAW,oBAAoB,MAAM,QAAQ,CAAC,CAC9C,WAAW,oBAAoB,WAAW,QAAQ,CAAC,CACnD,WAAW,oBAAoB,UAAU,YAAY,CAAC,CACtD,WAAW,oBAAoB,SAAS,QAAQ,CAAC,CACjD,WAAW,oBAAoB,WAAW,aAAa,CAAC,CACxD,WAAW,oBAAoB,OAAO,SAAS,CAAC,CAChD,WAAW,oBAAoB,WAAW,MAAM;CACrD;;;;;CAMA,UAAU,SAAyB;EAEjC,OAAO,KACJ,WAAW,oBAAoB,MAAM,QAAQ,CAAC,CAC9C,WAAW,oBAAoB,WAAW,MAAM;CACrD;;;;CAKA,UAAU,SAAyB;EACjC,OAAO,KACJ,WAAW,oBAAoB,MAAM,QAAQ,CAAC,CAC9C,WAAW,oBAAoB,WAAW,MAAM;CACrD;AACF;;;;AAKA,SAAS,kBACP,QACsB;CACtB,IAAI,OAAO,WAAW,YACpB,OAAO;CAGT,MAAM,SAAS,mBAAmB;CAClC,IAAI,CAAC,QACH,MAAM,IAAI,MACR,yCAAyC,OAAO,wBACxB,OAAO,KAAK,kBAAkB,CAAC,CAAC,KAAK,IAAI,GACnE;CAGF,OAAO;AACT;;;;;;;;;;;;AAaA,IAAa,+BAAb,MAAmE;CACjE,AAAiB;CACjB,AAAiB;CAEjB,YACE,kBACA,SACA;EACA,KAAK,mBAAmB;EACxB,KAAK,aAAa,kBAAkB,QAAQ,UAAU;CACxD;;;;CAKA,QAAQ,MAAY,eAA8B;EAChD,IAAI;GACF,MAAM,eAAe,KAAK;GAC1B,MAAM,iBAAiB,KAAK,WAAW,YAAY;GAEnD,IAAI,mBAAmB,cACrB,KAAK,WAAW,cAAc;EAElC,QAAQ,CAER;EAEA,KAAK,iBAAiB,QAAQ,MAAM,aAAa;CACnD;;;;CAKA,MAAM,MAA0B;EAC9B,KAAK,iBAAiB,MAAM,IAAI;CAClC;CAEA,aAA4B;EAC1B,OAAO,KAAK,iBAAiB,WAAW;CAC1C;CAEA,WAA0B;EACxB,OAAO,KAAK,iBAAiB,SAAS;CACxC;AACF"}
+{"version":3,"file":"span-name-normalizer.js","names":[],"sources":["../src/span-name-normalizer.ts"],"sourcesContent":["/**\n * Span Name Normalizer\n *\n * Normalizes span names to reduce cardinality from dynamic path segments.\n * This is critical for observability backends that charge by unique span names\n * or have cardinality limits.\n *\n * @example Basic usage with custom function\n * ```typescript\n * init({\n *   service: 'my-app',\n *   spanNameNormalizer: (name) => {\n *     return name.replace(/\\/[0-9]+/g, '/:id');\n *   }\n * })\n * ```\n *\n * @example Using built-in preset\n * ```typescript\n * init({\n *   service: 'my-app',\n *   spanNameNormalizer: 'rest-api'\n * })\n * ```\n */\n\nimport type {\n  SpanProcessor,\n  ReadableSpan,\n} from '@opentelemetry/sdk-trace-base';\nimport type { Context } from '@opentelemetry/api';\nimport type { Span } from '@opentelemetry/sdk-trace-base';\n\n/**\n * Function to normalize a span name\n * @param name - The original span name\n * @returns The normalized span name\n */\nexport type SpanNameNormalizerFn = (name: string) => string;\n\n/**\n * Built-in normalizer preset names\n */\nexport type SpanNameNormalizerPreset = 'rest-api' | 'graphql' | 'minimal';\n\n/**\n * Normalizer config - either a function or a preset name\n */\nexport type SpanNameNormalizerConfig =\n  SpanNameNormalizerFn | SpanNameNormalizerPreset;\n\nexport interface SpanNameNormalizingProcessorOptions {\n  /**\n   * Normalizer function or preset name\n   */\n  normalizer: SpanNameNormalizerConfig;\n}\n\n/**\n * Built-in normalizer patterns\n */\nconst NORMALIZER_PATTERNS = {\n  // Numeric IDs: /users/123 → /users/:id\n  numericId: /\\/\\d+(?=\\/|$)/g,\n\n  // UUIDs: /users/550e8400-e29b-41d4-a716-446655440000 → /users/:uuid\n  uuid: /\\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}(?=\\/|$)/gi,\n\n  // Short UUIDs (without dashes): /users/550e8400e29b41d4a716446655440000 → /users/:uuid\n  shortUuid: /\\/[0-9a-f]{32}(?=\\/|$)/gi,\n\n  // MongoDB ObjectIds: /docs/507f1f77bcf86cd799439011 → /docs/:objectId\n  objectId: /\\/[0-9a-f]{24}(?=\\/|$)/gi,\n\n  // Hashes (6+ hex chars): /assets/abc123def.js → /assets/:hash.js\n  hash: /\\/[0-9a-f]{6,}(?=\\.[a-z]+$)/gi,\n\n  // ISO dates: /logs/2024-01-15 → /logs/:date\n  isoDate: /\\/\\d{4}-\\d{2}-\\d{2}(?=\\/|$)/g,\n\n  // Timestamps: /events/1705334400 → /events/:timestamp\n  timestamp: /\\/1[0-9]{9}(?=\\/|$)/g,\n\n  // Email-like segments: /users/john@example.com → /users/:email\n  email: /\\/[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}(?=\\/|$)/g,\n} as const;\n\n/**\n * Built-in normalizer presets\n */\nconst NORMALIZER_PRESETS: Record<\n  SpanNameNormalizerPreset,\n  SpanNameNormalizerFn\n> = {\n  /**\n   * REST API preset - normalizes common REST path patterns\n   * Handles: numeric IDs, UUIDs, ObjectIds, dates, timestamps, emails\n   */\n  'rest-api': (name: string): string => {\n    return name\n      .replaceAll(NORMALIZER_PATTERNS.uuid, '/:uuid')\n      .replaceAll(NORMALIZER_PATTERNS.shortUuid, '/:uuid')\n      .replaceAll(NORMALIZER_PATTERNS.objectId, '/:objectId')\n      .replaceAll(NORMALIZER_PATTERNS.isoDate, '/:date')\n      .replaceAll(NORMALIZER_PATTERNS.timestamp, '/:timestamp')\n      .replaceAll(NORMALIZER_PATTERNS.email, '/:email')\n      .replaceAll(NORMALIZER_PATTERNS.numericId, '/:id');\n  },\n\n  /**\n   * GraphQL preset - normalizes GraphQL operation names and paths\n   * Keeps query/mutation names but normalizes embedded IDs\n   */\n  graphql: (name: string): string => {\n    // For GraphQL, normalize both path-style and embedded IDs\n    return name\n      .replaceAll(NORMALIZER_PATTERNS.uuid, '/:uuid')\n      .replaceAll(NORMALIZER_PATTERNS.numericId, '/:id');\n  },\n\n  /**\n   * Minimal preset - only normalizes numeric IDs and UUIDs\n   */\n  minimal: (name: string): string => {\n    return name\n      .replaceAll(NORMALIZER_PATTERNS.uuid, '/:uuid')\n      .replaceAll(NORMALIZER_PATTERNS.numericId, '/:id');\n  },\n};\n\n/**\n * Resolve normalizer config to a function\n */\nfunction resolveNormalizer(\n  config: SpanNameNormalizerConfig,\n): SpanNameNormalizerFn {\n  if (typeof config === 'function') {\n    return config;\n  }\n\n  const preset = NORMALIZER_PRESETS[config];\n  if (!preset) {\n    throw new Error(\n      `Unknown span name normalizer preset: \"${config}\". ` +\n        `Available presets: ${Object.keys(NORMALIZER_PRESETS).join(', ')}`,\n    );\n  }\n\n  return preset;\n}\n\n/**\n * Span processor that normalizes span names to reduce cardinality.\n *\n * Normalization happens in onStart() when we have access to the mutable Span.\n * This allows us to call span.updateName() before the span is finalized.\n *\n * Common use cases:\n * - REST APIs: /users/123/posts/456 → /users/:id/posts/:id\n * - UUIDs: /items/550e8400-e29b-41d4-a716-446655440000 → /items/:uuid\n * - Dates: /logs/2024-01-15 → /logs/:date\n */\nexport class SpanNameNormalizingProcessor implements SpanProcessor {\n  private readonly wrappedProcessor: SpanProcessor;\n  private readonly normalizer: SpanNameNormalizerFn;\n\n  constructor(\n    wrappedProcessor: SpanProcessor,\n    options: SpanNameNormalizingProcessorOptions,\n  ) {\n    this.wrappedProcessor = wrappedProcessor;\n    this.normalizer = resolveNormalizer(options.normalizer);\n  }\n\n  /**\n   * Normalize span name on start (when Span is mutable)\n   */\n  onStart(span: Span, parentContext: Context): void {\n    try {\n      const originalName = span.name;\n      const normalizedName = this.normalizer(originalName);\n\n      if (normalizedName !== originalName) {\n        span.updateName(normalizedName);\n      }\n    } catch {\n      // If normalizer throws, keep original name (fail-open)\n    }\n\n    this.wrappedProcessor.onStart(span, parentContext);\n  }\n\n  /**\n   * Pass through onEnd unchanged\n   */\n  onEnd(span: ReadableSpan): void {\n    this.wrappedProcessor.onEnd(span);\n  }\n\n  forceFlush(): Promise<void> {\n    return this.wrappedProcessor.forceFlush();\n  }\n\n  shutdown(): Promise<void> {\n    return this.wrappedProcessor.shutdown();\n  }\n}\n\n/**\n * Export built-in patterns for advanced users who want to compose their own normalizers\n */\nexport { NORMALIZER_PATTERNS, NORMALIZER_PRESETS };\n"],"mappings":";;;;AA6DA,MAAM,sBAAsB;CAE1B,WAAW;CAGX,MAAM;CAGN,WAAW;CAGX,UAAU;CAGV,MAAM;CAGN,SAAS;CAGT,WAAW;CAGX,OAAO;AACT;;;;AAKA,MAAM,qBAGF;;;;;CAKF,aAAa,SAAyB;EACpC,OAAO,KACJ,WAAW,oBAAoB,MAAM,QAAQ,CAAC,CAC9C,WAAW,oBAAoB,WAAW,QAAQ,CAAC,CACnD,WAAW,oBAAoB,UAAU,YAAY,CAAC,CACtD,WAAW,oBAAoB,SAAS,QAAQ,CAAC,CACjD,WAAW,oBAAoB,WAAW,aAAa,CAAC,CACxD,WAAW,oBAAoB,OAAO,SAAS,CAAC,CAChD,WAAW,oBAAoB,WAAW,MAAM;CACrD;;;;;CAMA,UAAU,SAAyB;EAEjC,OAAO,KACJ,WAAW,oBAAoB,MAAM,QAAQ,CAAC,CAC9C,WAAW,oBAAoB,WAAW,MAAM;CACrD;;;;CAKA,UAAU,SAAyB;EACjC,OAAO,KACJ,WAAW,oBAAoB,MAAM,QAAQ,CAAC,CAC9C,WAAW,oBAAoB,WAAW,MAAM;CACrD;AACF;;;;AAKA,SAAS,kBACP,QACsB;CACtB,IAAI,OAAO,WAAW,YACpB,OAAO;CAGT,MAAM,SAAS,mBAAmB;CAClC,IAAI,CAAC,QACH,MAAM,IAAI,MACR,yCAAyC,OAAO,wBACxB,OAAO,KAAK,kBAAkB,CAAC,CAAC,KAAK,IAAI,GACnE;CAGF,OAAO;AACT;;;;;;;;;;;;AAaA,IAAa,+BAAb,MAAmE;CACjE,AAAiB;CACjB,AAAiB;CAEjB,YACE,kBACA,SACA;EACA,KAAK,mBAAmB;EACxB,KAAK,aAAa,kBAAkB,QAAQ,UAAU;CACxD;;;;CAKA,QAAQ,MAAY,eAA8B;EAChD,IAAI;GACF,MAAM,eAAe,KAAK;GAC1B,MAAM,iBAAiB,KAAK,WAAW,YAAY;GAEnD,IAAI,mBAAmB,cACrB,KAAK,WAAW,cAAc;EAElC,QAAQ,CAER;EAEA,KAAK,iBAAiB,QAAQ,MAAM,aAAa;CACnD;;;;CAKA,MAAM,MAA0B;EAC9B,KAAK,iBAAiB,MAAM,IAAI;CAClC;CAEA,aAA4B;EAC1B,OAAO,KAAK,iBAAiB,WAAW;CAC1C;CAEA,WAA0B;EACxB,OAAO,KAAK,iBAAiB,SAAS;CACxC;AACF"}

package/dist/tail-sampling-processor.d.cts

@@ -1,6 +1,5 @@
 import { ReadableSpan, Span, SpanProcessor } from "@opentelemetry/sdk-trace-base";
 import { Context } from "@opentelemetry/api";
-
 //#region src/tail-sampling-processor.d.ts
 declare class TailSamplingSpanProcessor implements SpanProcessor {
   private wrappedProcessor;

package/dist/tail-sampling-processor.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"tail-sampling-processor.d.cts","names":[],"sources":["../src/tail-sampling-processor.ts"],"mappings":";;;;cAyBa,yBAAA,YAAqC,aAAA;EAAA,QACxC,gBAAA;cAEI,gBAAA,EAAkB,aAAA;EAI9B,OAAA,CAAQ,IAAA,EAAM,IAAA,EAAM,aAAA,EAAe,OAAA;EAInC,KAAA,CAAM,IAAA,EAAM,YAAA;EAWZ,UAAA,IAAc,OAAA;EAId,QAAA,IAAY,OAAA;AAAA"}
+{"version":3,"file":"tail-sampling-processor.d.cts","names":[],"sources":["../src/tail-sampling-processor.ts"],"mappings":";;;cAyBa,qCAAqC;UACxC;EAEI,YAAA,kBAAkB;EAI9B,QAAQ,MAAM,MAAM,eAAe;EAInC,MAAM,MAAM;EAWZ,cAAc;EAId,YAAY"}

package/dist/tail-sampling-processor.d.ts

@@ -1,6 +1,5 @@
 import { ReadableSpan, Span, SpanProcessor } from "@opentelemetry/sdk-trace-base";
 import { Context } from "@opentelemetry/api";
-
 //#region src/tail-sampling-processor.d.ts
 declare class TailSamplingSpanProcessor implements SpanProcessor {
   private wrappedProcessor;

package/dist/tail-sampling-processor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tail-sampling-processor.d.ts","names":[],"sources":["../src/tail-sampling-processor.ts"],"mappings":";;;;cAyBa,yBAAA,YAAqC,aAAA;EAAA,QACxC,gBAAA;cAEI,gBAAA,EAAkB,aAAA;EAI9B,OAAA,CAAQ,IAAA,EAAM,IAAA,EAAM,aAAA,EAAe,OAAA;EAInC,KAAA,CAAM,IAAA,EAAM,YAAA;EAWZ,UAAA,IAAc,OAAA;EAId,QAAA,IAAY,OAAA;AAAA"}
+{"version":3,"file":"tail-sampling-processor.d.ts","names":[],"sources":["../src/tail-sampling-processor.ts"],"mappings":";;;cAyBa,qCAAqC;UACxC;EAEI,YAAA,kBAAkB;EAI9B,QAAQ,MAAM,MAAM,eAAe;EAInC,MAAM,MAAM;EAWZ,cAAc;EAId,YAAY"}

package/dist/test-span-collector.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"test-span-collector.cjs","names":["SpanStatusCode"],"sources":["../src/test-span-collector.ts"],"sourcesContent":["/**\n * TestSpanCollector — SpanExporter that groups finished spans by traceId\n * and drains per-trace for embedding in test metadata.\n *\n * Wire it to a tracer provider, register that provider with autotel, then\n * create spans through autotel's tracer so finished spans reach the collector.\n *\n * @example\n * ```typescript\n * import { TestSpanCollector } from 'autotel/test-span-collector';\n * import { SimpleSpanProcessor } from 'autotel/processors';\n * import { setAutotelTracerProvider, getAutotelTracer } from 'autotel';\n * import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';\n *\n * const collector = new TestSpanCollector();\n *\n * // OTel SDK v2: pass processors at construction, then register the provider.\n * const provider = new NodeTracerProvider({\n *   spanProcessors: [new SimpleSpanProcessor(collector)],\n * });\n * setAutotelTracerProvider(provider);\n *\n * const tracer = getAutotelTracer('test');\n * const root = tracer.startSpan('operation');\n * // ...work, child spans...\n * root.end();\n *\n * const spans = collector.drainTrace(\n *   root.spanContext().traceId,\n *   root.spanContext().spanId,\n * );\n * // spans contains the root span and its descendants\n * ```\n *\n * For high-level instrumentation written with `span()` / `track()`, prefer\n * `createTraceCollector()` from `autotel/testing`. For a plain low-level\n * exporter, use `InMemorySpanExporter` from `autotel/exporters`.\n */\n\nimport type { SpanExporter, ReadableSpan } from '@opentelemetry/sdk-trace-base';\nimport { SpanStatusCode } from '@opentelemetry/api';\n\n/** @see ExportResultCode from @opentelemetry/core */\nconst ExportResultCode = { SUCCESS: 0, FAILED: 1 } as const;\n\n/** Attribute value types that survive serialization */\ntype SerializableValue =\n  | string\n  | number\n  | boolean\n  | string[]\n  | number[]\n  | boolean[];\n\n/**\n * Portable serialized span for embedding in test metadata.\n * `startTimeMs` is derived from OTel HrTime — epoch-based wall-clock ms in the current SDK.\n *\n * Defined as a `type` (not `interface`) so it is assignable to\n * `Record<string, unknown>` in TypeScript 6+ strict mode.\n */\nexport type SerializedSpan = {\n  spanId: string;\n  parentSpanId?: string;\n  name: string;\n  startTimeMs: number;\n  durationMs: number;\n  status: 'ok' | 'error' | 'unset';\n  statusMessage?: string;\n  attributes?: Record<string, SerializableValue>;\n};\n\nexport class TestSpanCollector implements SpanExporter {\n  private traces = new Map<string, ReadableSpan[]>();\n\n  export(\n    spans: ReadableSpan[],\n    callback: (result: { code: number }) => void,\n  ): void {\n    for (const span of spans) {\n      const traceId = span.spanContext().traceId;\n      let list = this.traces.get(traceId);\n      if (!list) {\n        list = [];\n        this.traces.set(traceId, list);\n      }\n      list.push(span);\n    }\n    callback({ code: ExportResultCode.SUCCESS });\n  }\n\n  /**\n   * Drain and serialize spans that are descendants of `rootSpanId` within `traceId`.\n   * Filters to the subtree rooted at the test span to prevent cross-test mixing.\n   * Removes the entire traceId entry from the collector.\n   */\n  drainTrace(traceId: string, rootSpanId: string): SerializedSpan[] {\n    const spans = this.peekTrace(traceId, rootSpanId);\n    this.traces.delete(traceId);\n    return spans;\n  }\n\n  /**\n   * Serialize the finished spans of `traceId` without removing them — safe to\n   * call repeatedly while a trace is still growing (e.g. a scenario checker\n   * polling until an async flow's completion boundary closes).\n   *\n   * With `rootSpanId`, filters to that span's subtree like {@link drainTrace}.\n   */\n  peekTrace(traceId: string, rootSpanId?: string): SerializedSpan[] {\n    const allSpans = this.traces.get(traceId);\n    if (!allSpans?.length) return [];\n    if (rootSpanId === undefined) return allSpans.map((s) => serializeSpan(s));\n\n    // Build spanId → span index for efficient parent-chain walking\n    const byId = new Map<string, ReadableSpan>();\n    for (const s of allSpans) byId.set(s.spanContext().spanId, s);\n\n    // Filter to spans that are the root or descendants of rootSpanId\n    const included = allSpans.filter((s) => {\n      let id: string | undefined = s.spanContext().spanId;\n      while (id) {\n        if (id === rootSpanId) return true;\n        const parent = byId.get(id);\n        const parentId = parent?.parentSpanContext?.spanId || undefined;\n        if (parentId === id) break; // cycle guard\n        id = parentId;\n      }\n      return false;\n    });\n\n    return included.map((s) => serializeSpan(s));\n  }\n\n  shutdown(): Promise<void> {\n    this.traces.clear();\n    return Promise.resolve();\n  }\n\n  forceFlush(): Promise<void> {\n    return Promise.resolve();\n  }\n}\n\nfunction hrTimeToMs(hr: [number, number]): number {\n  return hr[0] * 1000 + hr[1] / 1_000_000;\n}\n\nfunction isSerializable(v: unknown): v is SerializableValue {\n  if (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean')\n    return true;\n  if (Array.isArray(v) && v.length > 0) {\n    const t = typeof v[0];\n    return (\n      (t === 'string' || t === 'number' || t === 'boolean') &&\n      v.every((e) => typeof e === t)\n    );\n  }\n  return false;\n}\n\nexport function serializeSpan(span: ReadableSpan): SerializedSpan {\n  const attrs: Record<string, SerializableValue> = {};\n  for (const [k, v] of Object.entries(span.attributes)) {\n    if (isSerializable(v)) attrs[k] = v;\n  }\n  return {\n    spanId: span.spanContext().spanId,\n    parentSpanId: span.parentSpanContext?.spanId || undefined,\n    name: span.name,\n    startTimeMs: hrTimeToMs(span.startTime as [number, number]),\n    durationMs: hrTimeToMs(span.duration as [number, number]),\n    status:\n      span.status.code === SpanStatusCode.ERROR\n        ? 'error'\n        : span.status.code === SpanStatusCode.OK\n          ? 'ok'\n          : 'unset',\n    statusMessage: span.status.message || undefined,\n    attributes: Object.keys(attrs).length > 0 ? attrs : undefined,\n  };\n}\n"],"mappings":";;;;;AA2CA,MAAM,mBAAmB;CAAE,SAAS;CAAG,QAAQ;AAAE;AA6BjD,IAAa,oBAAb,MAAuD;CACrD,AAAQ,yBAAS,IAAI,IAA4B;CAEjD,OACE,OACA,UACM;EACN,KAAK,MAAM,QAAQ,OAAO;GACxB,MAAM,UAAU,KAAK,YAAY,CAAC,CAAC;GACnC,IAAI,OAAO,KAAK,OAAO,IAAI,OAAO;GAClC,IAAI,CAAC,MAAM;IACT,OAAO,CAAC;IACR,KAAK,OAAO,IAAI,SAAS,IAAI;GAC/B;GACA,KAAK,KAAK,IAAI;EAChB;EACA,SAAS,EAAE,MAAM,iBAAiB,QAAQ,CAAC;CAC7C;;;;;;CAOA,WAAW,SAAiB,YAAsC;EAChE,MAAM,QAAQ,KAAK,UAAU,SAAS,UAAU;EAChD,KAAK,OAAO,OAAO,OAAO;EAC1B,OAAO;CACT;;;;;;;;CASA,UAAU,SAAiB,YAAuC;EAChE,MAAM,WAAW,KAAK,OAAO,IAAI,OAAO;EACxC,IAAI,CAAC,UAAU,QAAQ,OAAO,CAAC;EAC/B,IAAI,eAAe,QAAW,OAAO,SAAS,KAAK,MAAM,cAAc,CAAC,CAAC;EAGzE,MAAM,uBAAO,IAAI,IAA0B;EAC3C,KAAK,MAAM,KAAK,UAAU,KAAK,IAAI,EAAE,YAAY,CAAC,CAAC,QAAQ,CAAC;EAe5D,OAZiB,SAAS,QAAQ,MAAM;GACtC,IAAI,KAAyB,EAAE,YAAY,CAAC,CAAC;GAC7C,OAAO,IAAI;IACT,IAAI,OAAO,YAAY,OAAO;IAE9B,MAAM,WADS,KAAK,IAAI,EACF,CAAC,EAAE,mBAAmB,UAAU;IACtD,IAAI,aAAa,IAAI;IACrB,KAAK;GACP;GACA,OAAO;EACT,CAEc,CAAC,CAAC,KAAK,MAAM,cAAc,CAAC,CAAC;CAC7C;CAEA,WAA0B;EACxB,KAAK,OAAO,MAAM;EAClB,OAAO,QAAQ,QAAQ;CACzB;CAEA,aAA4B;EAC1B,OAAO,QAAQ,QAAQ;CACzB;AACF;AAEA,SAAS,WAAW,IAA8B;CAChD,OAAO,GAAG,KAAK,MAAO,GAAG,KAAK;AAChC;AAEA,SAAS,eAAe,GAAoC;CAC1D,IAAI,OAAO,MAAM,YAAY,OAAO,MAAM,YAAY,OAAO,MAAM,WACjE,OAAO;CACT,IAAI,MAAM,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG;EACpC,MAAM,IAAI,OAAO,EAAE;EACnB,QACG,MAAM,YAAY,MAAM,YAAY,MAAM,cAC3C,EAAE,OAAO,MAAM,OAAO,MAAM,CAAC;CAEjC;CACA,OAAO;AACT;AAEA,SAAgB,cAAc,MAAoC;CAChE,MAAM,QAA2C,CAAC;CAClD,KAAK,MAAM,CAAC,GAAG,MAAM,OAAO,QAAQ,KAAK,UAAU,GACjD,IAAI,eAAe,CAAC,GAAG,MAAM,KAAK;CAEpC,OAAO;EACL,QAAQ,KAAK,YAAY,CAAC,CAAC;EAC3B,cAAc,KAAK,mBAAmB,UAAU;EAChD,MAAM,KAAK;EACX,aAAa,WAAW,KAAK,SAA6B;EAC1D,YAAY,WAAW,KAAK,QAA4B;EACxD,QACE,KAAK,OAAO,SAASA,kCAAe,QAChC,UACA,KAAK,OAAO,SAASA,kCAAe,KAClC,OACA;EACR,eAAe,KAAK,OAAO,WAAW;EACtC,YAAY,OAAO,KAAK,KAAK,CAAC,CAAC,SAAS,IAAI,QAAQ;CACtD;AACF"}
+{"version":3,"file":"test-span-collector.cjs","names":["SpanStatusCode"],"sources":["../src/test-span-collector.ts"],"sourcesContent":["/**\n * TestSpanCollector — SpanExporter that groups finished spans by traceId\n * and drains per-trace for embedding in test metadata.\n *\n * Wire it to a tracer provider, register that provider with autotel, then\n * create spans through autotel's tracer so finished spans reach the collector.\n *\n * @example\n * ```typescript\n * import { TestSpanCollector } from 'autotel/test-span-collector';\n * import { SimpleSpanProcessor } from 'autotel/processors';\n * import { setAutotelTracerProvider, getAutotelTracer } from 'autotel';\n * import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';\n *\n * const collector = new TestSpanCollector();\n *\n * // OTel SDK v2: pass processors at construction, then register the provider.\n * const provider = new NodeTracerProvider({\n *   spanProcessors: [new SimpleSpanProcessor(collector)],\n * });\n * setAutotelTracerProvider(provider);\n *\n * const tracer = getAutotelTracer('test');\n * const root = tracer.startSpan('operation');\n * // ...work, child spans...\n * root.end();\n *\n * const spans = collector.drainTrace(\n *   root.spanContext().traceId,\n *   root.spanContext().spanId,\n * );\n * // spans contains the root span and its descendants\n * ```\n *\n * For high-level instrumentation written with `span()` / `track()`, prefer\n * `createTraceCollector()` from `autotel/testing`. For a plain low-level\n * exporter, use `InMemorySpanExporter` from `autotel/exporters`.\n */\n\nimport type { SpanExporter, ReadableSpan } from '@opentelemetry/sdk-trace-base';\nimport { SpanStatusCode } from '@opentelemetry/api';\n\n/** @see ExportResultCode from @opentelemetry/core */\nconst ExportResultCode = { SUCCESS: 0, FAILED: 1 } as const;\n\n/** Attribute value types that survive serialization */\ntype SerializableValue =\n  string | number | boolean | string[] | number[] | boolean[];\n\n/**\n * Portable serialized span for embedding in test metadata.\n * `startTimeMs` is derived from OTel HrTime — epoch-based wall-clock ms in the current SDK.\n *\n * Defined as a `type` (not `interface`) so it is assignable to\n * `Record<string, unknown>` in TypeScript 6+ strict mode.\n */\nexport type SerializedSpan = {\n  spanId: string;\n  parentSpanId?: string;\n  name: string;\n  startTimeMs: number;\n  durationMs: number;\n  status: 'ok' | 'error' | 'unset';\n  statusMessage?: string;\n  attributes?: Record<string, SerializableValue>;\n};\n\nexport class TestSpanCollector implements SpanExporter {\n  private traces = new Map<string, ReadableSpan[]>();\n\n  export(\n    spans: ReadableSpan[],\n    callback: (result: { code: number }) => void,\n  ): void {\n    for (const span of spans) {\n      const traceId = span.spanContext().traceId;\n      let list = this.traces.get(traceId);\n      if (!list) {\n        list = [];\n        this.traces.set(traceId, list);\n      }\n      list.push(span);\n    }\n    callback({ code: ExportResultCode.SUCCESS });\n  }\n\n  /**\n   * Drain and serialize spans that are descendants of `rootSpanId` within `traceId`.\n   * Filters to the subtree rooted at the test span to prevent cross-test mixing.\n   * Removes the entire traceId entry from the collector.\n   */\n  drainTrace(traceId: string, rootSpanId: string): SerializedSpan[] {\n    const spans = this.peekTrace(traceId, rootSpanId);\n    this.traces.delete(traceId);\n    return spans;\n  }\n\n  /**\n   * Serialize the finished spans of `traceId` without removing them — safe to\n   * call repeatedly while a trace is still growing (e.g. a scenario checker\n   * polling until an async flow's completion boundary closes).\n   *\n   * With `rootSpanId`, filters to that span's subtree like {@link drainTrace}.\n   */\n  peekTrace(traceId: string, rootSpanId?: string): SerializedSpan[] {\n    const allSpans = this.traces.get(traceId);\n    if (!allSpans?.length) return [];\n    if (rootSpanId === undefined) return allSpans.map((s) => serializeSpan(s));\n\n    // Build spanId → span index for efficient parent-chain walking\n    const byId = new Map<string, ReadableSpan>();\n    for (const s of allSpans) byId.set(s.spanContext().spanId, s);\n\n    // Filter to spans that are the root or descendants of rootSpanId\n    const included = allSpans.filter((s) => {\n      let id: string | undefined = s.spanContext().spanId;\n      while (id) {\n        if (id === rootSpanId) return true;\n        const parent = byId.get(id);\n        const parentId = parent?.parentSpanContext?.spanId || undefined;\n        if (parentId === id) break; // cycle guard\n        id = parentId;\n      }\n      return false;\n    });\n\n    return included.map((s) => serializeSpan(s));\n  }\n\n  shutdown(): Promise<void> {\n    this.traces.clear();\n    return Promise.resolve();\n  }\n\n  forceFlush(): Promise<void> {\n    return Promise.resolve();\n  }\n}\n\nfunction hrTimeToMs(hr: [number, number]): number {\n  return hr[0] * 1000 + hr[1] / 1_000_000;\n}\n\nfunction isSerializable(v: unknown): v is SerializableValue {\n  if (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean')\n    return true;\n  if (Array.isArray(v) && v.length > 0) {\n    const t = typeof v[0];\n    return (\n      (t === 'string' || t === 'number' || t === 'boolean') &&\n      v.every((e) => typeof e === t)\n    );\n  }\n  return false;\n}\n\nexport function serializeSpan(span: ReadableSpan): SerializedSpan {\n  const attrs: Record<string, SerializableValue> = {};\n  for (const [k, v] of Object.entries(span.attributes)) {\n    if (isSerializable(v)) attrs[k] = v;\n  }\n  return {\n    spanId: span.spanContext().spanId,\n    parentSpanId: span.parentSpanContext?.spanId || undefined,\n    name: span.name,\n    startTimeMs: hrTimeToMs(span.startTime as [number, number]),\n    durationMs: hrTimeToMs(span.duration as [number, number]),\n    status:\n      span.status.code === SpanStatusCode.ERROR\n        ? 'error'\n        : span.status.code === SpanStatusCode.OK\n          ? 'ok'\n          : 'unset',\n    statusMessage: span.status.message || undefined,\n    attributes: Object.keys(attrs).length > 0 ? attrs : undefined,\n  };\n}\n"],"mappings":";;;;;AA2CA,MAAM,mBAAmB;CAAE,SAAS;CAAG,QAAQ;AAAE;AAwBjD,IAAa,oBAAb,MAAuD;CACrD,AAAQ,yBAAS,IAAI,IAA4B;CAEjD,OACE,OACA,UACM;EACN,KAAK,MAAM,QAAQ,OAAO;GACxB,MAAM,UAAU,KAAK,YAAY,CAAC,CAAC;GACnC,IAAI,OAAO,KAAK,OAAO,IAAI,OAAO;GAClC,IAAI,CAAC,MAAM;IACT,OAAO,CAAC;IACR,KAAK,OAAO,IAAI,SAAS,IAAI;GAC/B;GACA,KAAK,KAAK,IAAI;EAChB;EACA,SAAS,EAAE,MAAM,iBAAiB,QAAQ,CAAC;CAC7C;;;;;;CAOA,WAAW,SAAiB,YAAsC;EAChE,MAAM,QAAQ,KAAK,UAAU,SAAS,UAAU;EAChD,KAAK,OAAO,OAAO,OAAO;EAC1B,OAAO;CACT;;;;;;;;CASA,UAAU,SAAiB,YAAuC;EAChE,MAAM,WAAW,KAAK,OAAO,IAAI,OAAO;EACxC,IAAI,CAAC,UAAU,QAAQ,OAAO,CAAC;EAC/B,IAAI,eAAe,QAAW,OAAO,SAAS,KAAK,MAAM,cAAc,CAAC,CAAC;EAGzE,MAAM,uBAAO,IAAI,IAA0B;EAC3C,KAAK,MAAM,KAAK,UAAU,KAAK,IAAI,EAAE,YAAY,CAAC,CAAC,QAAQ,CAAC;EAe5D,OAZiB,SAAS,QAAQ,MAAM;GACtC,IAAI,KAAyB,EAAE,YAAY,CAAC,CAAC;GAC7C,OAAO,IAAI;IACT,IAAI,OAAO,YAAY,OAAO;IAE9B,MAAM,WADS,KAAK,IAAI,EACF,CAAC,EAAE,mBAAmB,UAAU;IACtD,IAAI,aAAa,IAAI;IACrB,KAAK;GACP;GACA,OAAO;EACT,CAEc,CAAC,CAAC,KAAK,MAAM,cAAc,CAAC,CAAC;CAC7C;CAEA,WAA0B;EACxB,KAAK,OAAO,MAAM;EAClB,OAAO,QAAQ,QAAQ;CACzB;CAEA,aAA4B;EAC1B,OAAO,QAAQ,QAAQ;CACzB;AACF;AAEA,SAAS,WAAW,IAA8B;CAChD,OAAO,GAAG,KAAK,MAAO,GAAG,KAAK;AAChC;AAEA,SAAS,eAAe,GAAoC;CAC1D,IAAI,OAAO,MAAM,YAAY,OAAO,MAAM,YAAY,OAAO,MAAM,WACjE,OAAO;CACT,IAAI,MAAM,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG;EACpC,MAAM,IAAI,OAAO,EAAE;EACnB,QACG,MAAM,YAAY,MAAM,YAAY,MAAM,cAC3C,EAAE,OAAO,MAAM,OAAO,MAAM,CAAC;CAEjC;CACA,OAAO;AACT;AAEA,SAAgB,cAAc,MAAoC;CAChE,MAAM,QAA2C,CAAC;CAClD,KAAK,MAAM,CAAC,GAAG,MAAM,OAAO,QAAQ,KAAK,UAAU,GACjD,IAAI,eAAe,CAAC,GAAG,MAAM,KAAK;CAEpC,OAAO;EACL,QAAQ,KAAK,YAAY,CAAC,CAAC;EAC3B,cAAc,KAAK,mBAAmB,UAAU;EAChD,MAAM,KAAK;EACX,aAAa,WAAW,KAAK,SAA6B;EAC1D,YAAY,WAAW,KAAK,QAA4B;EACxD,QACE,KAAK,OAAO,SAASA,kCAAe,QAChC,UACA,KAAK,OAAO,SAASA,kCAAe,KAClC,OACA;EACR,eAAe,KAAK,OAAO,WAAW;EACtC,YAAY,OAAO,KAAK,KAAK,CAAC,CAAC,SAAS,IAAI,QAAQ;CACtD;AACF"}

package/dist/test-span-collector.d.cts

@@ -1,5 +1,4 @@
 import { ReadableSpan, SpanExporter } from "@opentelemetry/sdk-trace-base";
-
 //#region src/test-span-collector.d.ts
 /** Attribute value types that survive serialization */
 type SerializableValue = string | number | boolean | string[] | number[] | boolean[];

package/dist/test-span-collector.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"test-span-collector.d.cts","names":[],"sources":["../src/test-span-collector.ts"],"mappings":";;;;KA8CK,iBAAA;;;;;;;;KAeO,cAAA;EACV,MAAA;EACA,YAAA;EACA,IAAA;EACA,WAAA;EACA,UAAA;EACA,MAAA;EACA,aAAA;EACA,UAAA,GAAa,MAAM,SAAS,iBAAA;AAAA;AAAA,cAGjB,iBAAA,YAA6B,YAAA;EAAA,QAChC,MAAA;EAER,MAAA,CACE,KAAA,EAAO,YAAA,IACP,QAAA,GAAW,MAAA;IAAU,IAAA;EAAA;EAoF0B;;AAAc;;;EAjE/D,UAAA,CAAW,OAAA,UAAiB,UAAA,WAAqB,cAAA;;;;;;;;EAajD,SAAA,CAAU,OAAA,UAAiB,UAAA,YAAsB,cAAA;EAyBjD,QAAA,IAAY,OAAA;EAKZ,UAAA,IAAc,OAAA;AAAA;AAAA,iBAsBA,aAAA,CAAc,IAAA,EAAM,YAAA,GAAe,cAAc"}
+{"version":3,"file":"test-span-collector.d.cts","names":[],"sources":["../src/test-span-collector.ts"],"mappings":";;;KA8CK;;;;;;;;KAUO;EACV;EACA;EACA;EACA;EACA;EACA;EACA;EACA,aAAa,eAAe;;cAGjB,6BAA6B;UAChC;EAER,OACE,OAAO,gBACP,WAAW;IAAU;;;;;;;EAmBvB,WAAW,iBAAiB,qBAAqB;;;;;;;;EAajD,UAAU,iBAAiB,sBAAsB;EAyBjD,YAAY;EAKZ,cAAc;;iBAsBA,cAAc,MAAM,eAAe"}

package/dist/test-span-collector.d.ts

@@ -1,5 +1,4 @@
 import { ReadableSpan, SpanExporter } from "@opentelemetry/sdk-trace-base";
-
 //#region src/test-span-collector.d.ts
 /** Attribute value types that survive serialization */
 type SerializableValue = string | number | boolean | string[] | number[] | boolean[];

package/dist/test-span-collector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"test-span-collector.d.ts","names":[],"sources":["../src/test-span-collector.ts"],"mappings":";;;;KA8CK,iBAAA;;;;;;;;KAeO,cAAA;EACV,MAAA;EACA,YAAA;EACA,IAAA;EACA,WAAA;EACA,UAAA;EACA,MAAA;EACA,aAAA;EACA,UAAA,GAAa,MAAM,SAAS,iBAAA;AAAA;AAAA,cAGjB,iBAAA,YAA6B,YAAA;EAAA,QAChC,MAAA;EAER,MAAA,CACE,KAAA,EAAO,YAAA,IACP,QAAA,GAAW,MAAA;IAAU,IAAA;EAAA;EAoF0B;;AAAc;;;EAjE/D,UAAA,CAAW,OAAA,UAAiB,UAAA,WAAqB,cAAA;;;;;;;;EAajD,SAAA,CAAU,OAAA,UAAiB,UAAA,YAAsB,cAAA;EAyBjD,QAAA,IAAY,OAAA;EAKZ,UAAA,IAAc,OAAA;AAAA;AAAA,iBAsBA,aAAA,CAAc,IAAA,EAAM,YAAA,GAAe,cAAc"}
+{"version":3,"file":"test-span-collector.d.ts","names":[],"sources":["../src/test-span-collector.ts"],"mappings":";;;KA8CK;;;;;;;;KAUO;EACV;EACA;EACA;EACA;EACA;EACA;EACA;EACA,aAAa,eAAe;;cAGjB,6BAA6B;UAChC;EAER,OACE,OAAO,gBACP,WAAW;IAAU;;;;;;;EAmBvB,WAAW,iBAAiB,qBAAqB;;;;;;;;EAajD,UAAU,iBAAiB,sBAAsB;EAyBjD,YAAY;EAKZ,cAAc;;iBAsBA,cAAc,MAAM,eAAe"}

package/dist/test-span-collector.js.map

@@ -1 +1 @@
-{"version":3,"file":"test-span-collector.js","names":[],"sources":["../src/test-span-collector.ts"],"sourcesContent":["/**\n * TestSpanCollector — SpanExporter that groups finished spans by traceId\n * and drains per-trace for embedding in test metadata.\n *\n * Wire it to a tracer provider, register that provider with autotel, then\n * create spans through autotel's tracer so finished spans reach the collector.\n *\n * @example\n * ```typescript\n * import { TestSpanCollector } from 'autotel/test-span-collector';\n * import { SimpleSpanProcessor } from 'autotel/processors';\n * import { setAutotelTracerProvider, getAutotelTracer } from 'autotel';\n * import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';\n *\n * const collector = new TestSpanCollector();\n *\n * // OTel SDK v2: pass processors at construction, then register the provider.\n * const provider = new NodeTracerProvider({\n *   spanProcessors: [new SimpleSpanProcessor(collector)],\n * });\n * setAutotelTracerProvider(provider);\n *\n * const tracer = getAutotelTracer('test');\n * const root = tracer.startSpan('operation');\n * // ...work, child spans...\n * root.end();\n *\n * const spans = collector.drainTrace(\n *   root.spanContext().traceId,\n *   root.spanContext().spanId,\n * );\n * // spans contains the root span and its descendants\n * ```\n *\n * For high-level instrumentation written with `span()` / `track()`, prefer\n * `createTraceCollector()` from `autotel/testing`. For a plain low-level\n * exporter, use `InMemorySpanExporter` from `autotel/exporters`.\n */\n\nimport type { SpanExporter, ReadableSpan } from '@opentelemetry/sdk-trace-base';\nimport { SpanStatusCode } from '@opentelemetry/api';\n\n/** @see ExportResultCode from @opentelemetry/core */\nconst ExportResultCode = { SUCCESS: 0, FAILED: 1 } as const;\n\n/** Attribute value types that survive serialization */\ntype SerializableValue =\n  | string\n  | number\n  | boolean\n  | string[]\n  | number[]\n  | boolean[];\n\n/**\n * Portable serialized span for embedding in test metadata.\n * `startTimeMs` is derived from OTel HrTime — epoch-based wall-clock ms in the current SDK.\n *\n * Defined as a `type` (not `interface`) so it is assignable to\n * `Record<string, unknown>` in TypeScript 6+ strict mode.\n */\nexport type SerializedSpan = {\n  spanId: string;\n  parentSpanId?: string;\n  name: string;\n  startTimeMs: number;\n  durationMs: number;\n  status: 'ok' | 'error' | 'unset';\n  statusMessage?: string;\n  attributes?: Record<string, SerializableValue>;\n};\n\nexport class TestSpanCollector implements SpanExporter {\n  private traces = new Map<string, ReadableSpan[]>();\n\n  export(\n    spans: ReadableSpan[],\n    callback: (result: { code: number }) => void,\n  ): void {\n    for (const span of spans) {\n      const traceId = span.spanContext().traceId;\n      let list = this.traces.get(traceId);\n      if (!list) {\n        list = [];\n        this.traces.set(traceId, list);\n      }\n      list.push(span);\n    }\n    callback({ code: ExportResultCode.SUCCESS });\n  }\n\n  /**\n   * Drain and serialize spans that are descendants of `rootSpanId` within `traceId`.\n   * Filters to the subtree rooted at the test span to prevent cross-test mixing.\n   * Removes the entire traceId entry from the collector.\n   */\n  drainTrace(traceId: string, rootSpanId: string): SerializedSpan[] {\n    const spans = this.peekTrace(traceId, rootSpanId);\n    this.traces.delete(traceId);\n    return spans;\n  }\n\n  /**\n   * Serialize the finished spans of `traceId` without removing them — safe to\n   * call repeatedly while a trace is still growing (e.g. a scenario checker\n   * polling until an async flow's completion boundary closes).\n   *\n   * With `rootSpanId`, filters to that span's subtree like {@link drainTrace}.\n   */\n  peekTrace(traceId: string, rootSpanId?: string): SerializedSpan[] {\n    const allSpans = this.traces.get(traceId);\n    if (!allSpans?.length) return [];\n    if (rootSpanId === undefined) return allSpans.map((s) => serializeSpan(s));\n\n    // Build spanId → span index for efficient parent-chain walking\n    const byId = new Map<string, ReadableSpan>();\n    for (const s of allSpans) byId.set(s.spanContext().spanId, s);\n\n    // Filter to spans that are the root or descendants of rootSpanId\n    const included = allSpans.filter((s) => {\n      let id: string | undefined = s.spanContext().spanId;\n      while (id) {\n        if (id === rootSpanId) return true;\n        const parent = byId.get(id);\n        const parentId = parent?.parentSpanContext?.spanId || undefined;\n        if (parentId === id) break; // cycle guard\n        id = parentId;\n      }\n      return false;\n    });\n\n    return included.map((s) => serializeSpan(s));\n  }\n\n  shutdown(): Promise<void> {\n    this.traces.clear();\n    return Promise.resolve();\n  }\n\n  forceFlush(): Promise<void> {\n    return Promise.resolve();\n  }\n}\n\nfunction hrTimeToMs(hr: [number, number]): number {\n  return hr[0] * 1000 + hr[1] / 1_000_000;\n}\n\nfunction isSerializable(v: unknown): v is SerializableValue {\n  if (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean')\n    return true;\n  if (Array.isArray(v) && v.length > 0) {\n    const t = typeof v[0];\n    return (\n      (t === 'string' || t === 'number' || t === 'boolean') &&\n      v.every((e) => typeof e === t)\n    );\n  }\n  return false;\n}\n\nexport function serializeSpan(span: ReadableSpan): SerializedSpan {\n  const attrs: Record<string, SerializableValue> = {};\n  for (const [k, v] of Object.entries(span.attributes)) {\n    if (isSerializable(v)) attrs[k] = v;\n  }\n  return {\n    spanId: span.spanContext().spanId,\n    parentSpanId: span.parentSpanContext?.spanId || undefined,\n    name: span.name,\n    startTimeMs: hrTimeToMs(span.startTime as [number, number]),\n    durationMs: hrTimeToMs(span.duration as [number, number]),\n    status:\n      span.status.code === SpanStatusCode.ERROR\n        ? 'error'\n        : span.status.code === SpanStatusCode.OK\n          ? 'ok'\n          : 'unset',\n    statusMessage: span.status.message || undefined,\n    attributes: Object.keys(attrs).length > 0 ? attrs : undefined,\n  };\n}\n"],"mappings":";;;;AA2CA,MAAM,mBAAmB;CAAE,SAAS;CAAG,QAAQ;AAAE;AA6BjD,IAAa,oBAAb,MAAuD;CACrD,AAAQ,yBAAS,IAAI,IAA4B;CAEjD,OACE,OACA,UACM;EACN,KAAK,MAAM,QAAQ,OAAO;GACxB,MAAM,UAAU,KAAK,YAAY,CAAC,CAAC;GACnC,IAAI,OAAO,KAAK,OAAO,IAAI,OAAO;GAClC,IAAI,CAAC,MAAM;IACT,OAAO,CAAC;IACR,KAAK,OAAO,IAAI,SAAS,IAAI;GAC/B;GACA,KAAK,KAAK,IAAI;EAChB;EACA,SAAS,EAAE,MAAM,iBAAiB,QAAQ,CAAC;CAC7C;;;;;;CAOA,WAAW,SAAiB,YAAsC;EAChE,MAAM,QAAQ,KAAK,UAAU,SAAS,UAAU;EAChD,KAAK,OAAO,OAAO,OAAO;EAC1B,OAAO;CACT;;;;;;;;CASA,UAAU,SAAiB,YAAuC;EAChE,MAAM,WAAW,KAAK,OAAO,IAAI,OAAO;EACxC,IAAI,CAAC,UAAU,QAAQ,OAAO,CAAC;EAC/B,IAAI,eAAe,QAAW,OAAO,SAAS,KAAK,MAAM,cAAc,CAAC,CAAC;EAGzE,MAAM,uBAAO,IAAI,IAA0B;EAC3C,KAAK,MAAM,KAAK,UAAU,KAAK,IAAI,EAAE,YAAY,CAAC,CAAC,QAAQ,CAAC;EAe5D,OAZiB,SAAS,QAAQ,MAAM;GACtC,IAAI,KAAyB,EAAE,YAAY,CAAC,CAAC;GAC7C,OAAO,IAAI;IACT,IAAI,OAAO,YAAY,OAAO;IAE9B,MAAM,WADS,KAAK,IAAI,EACF,CAAC,EAAE,mBAAmB,UAAU;IACtD,IAAI,aAAa,IAAI;IACrB,KAAK;GACP;GACA,OAAO;EACT,CAEc,CAAC,CAAC,KAAK,MAAM,cAAc,CAAC,CAAC;CAC7C;CAEA,WAA0B;EACxB,KAAK,OAAO,MAAM;EAClB,OAAO,QAAQ,QAAQ;CACzB;CAEA,aAA4B;EAC1B,OAAO,QAAQ,QAAQ;CACzB;AACF;AAEA,SAAS,WAAW,IAA8B;CAChD,OAAO,GAAG,KAAK,MAAO,GAAG,KAAK;AAChC;AAEA,SAAS,eAAe,GAAoC;CAC1D,IAAI,OAAO,MAAM,YAAY,OAAO,MAAM,YAAY,OAAO,MAAM,WACjE,OAAO;CACT,IAAI,MAAM,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG;EACpC,MAAM,IAAI,OAAO,EAAE;EACnB,QACG,MAAM,YAAY,MAAM,YAAY,MAAM,cAC3C,EAAE,OAAO,MAAM,OAAO,MAAM,CAAC;CAEjC;CACA,OAAO;AACT;AAEA,SAAgB,cAAc,MAAoC;CAChE,MAAM,QAA2C,CAAC;CAClD,KAAK,MAAM,CAAC,GAAG,MAAM,OAAO,QAAQ,KAAK,UAAU,GACjD,IAAI,eAAe,CAAC,GAAG,MAAM,KAAK;CAEpC,OAAO;EACL,QAAQ,KAAK,YAAY,CAAC,CAAC;EAC3B,cAAc,KAAK,mBAAmB,UAAU;EAChD,MAAM,KAAK;EACX,aAAa,WAAW,KAAK,SAA6B;EAC1D,YAAY,WAAW,KAAK,QAA4B;EACxD,QACE,KAAK,OAAO,SAAS,eAAe,QAChC,UACA,KAAK,OAAO,SAAS,eAAe,KAClC,OACA;EACR,eAAe,KAAK,OAAO,WAAW;EACtC,YAAY,OAAO,KAAK,KAAK,CAAC,CAAC,SAAS,IAAI,QAAQ;CACtD;AACF"}
+{"version":3,"file":"test-span-collector.js","names":[],"sources":["../src/test-span-collector.ts"],"sourcesContent":["/**\n * TestSpanCollector — SpanExporter that groups finished spans by traceId\n * and drains per-trace for embedding in test metadata.\n *\n * Wire it to a tracer provider, register that provider with autotel, then\n * create spans through autotel's tracer so finished spans reach the collector.\n *\n * @example\n * ```typescript\n * import { TestSpanCollector } from 'autotel/test-span-collector';\n * import { SimpleSpanProcessor } from 'autotel/processors';\n * import { setAutotelTracerProvider, getAutotelTracer } from 'autotel';\n * import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';\n *\n * const collector = new TestSpanCollector();\n *\n * // OTel SDK v2: pass processors at construction, then register the provider.\n * const provider = new NodeTracerProvider({\n *   spanProcessors: [new SimpleSpanProcessor(collector)],\n * });\n * setAutotelTracerProvider(provider);\n *\n * const tracer = getAutotelTracer('test');\n * const root = tracer.startSpan('operation');\n * // ...work, child spans...\n * root.end();\n *\n * const spans = collector.drainTrace(\n *   root.spanContext().traceId,\n *   root.spanContext().spanId,\n * );\n * // spans contains the root span and its descendants\n * ```\n *\n * For high-level instrumentation written with `span()` / `track()`, prefer\n * `createTraceCollector()` from `autotel/testing`. For a plain low-level\n * exporter, use `InMemorySpanExporter` from `autotel/exporters`.\n */\n\nimport type { SpanExporter, ReadableSpan } from '@opentelemetry/sdk-trace-base';\nimport { SpanStatusCode } from '@opentelemetry/api';\n\n/** @see ExportResultCode from @opentelemetry/core */\nconst ExportResultCode = { SUCCESS: 0, FAILED: 1 } as const;\n\n/** Attribute value types that survive serialization */\ntype SerializableValue =\n  string | number | boolean | string[] | number[] | boolean[];\n\n/**\n * Portable serialized span for embedding in test metadata.\n * `startTimeMs` is derived from OTel HrTime — epoch-based wall-clock ms in the current SDK.\n *\n * Defined as a `type` (not `interface`) so it is assignable to\n * `Record<string, unknown>` in TypeScript 6+ strict mode.\n */\nexport type SerializedSpan = {\n  spanId: string;\n  parentSpanId?: string;\n  name: string;\n  startTimeMs: number;\n  durationMs: number;\n  status: 'ok' | 'error' | 'unset';\n  statusMessage?: string;\n  attributes?: Record<string, SerializableValue>;\n};\n\nexport class TestSpanCollector implements SpanExporter {\n  private traces = new Map<string, ReadableSpan[]>();\n\n  export(\n    spans: ReadableSpan[],\n    callback: (result: { code: number }) => void,\n  ): void {\n    for (const span of spans) {\n      const traceId = span.spanContext().traceId;\n      let list = this.traces.get(traceId);\n      if (!list) {\n        list = [];\n        this.traces.set(traceId, list);\n      }\n      list.push(span);\n    }\n    callback({ code: ExportResultCode.SUCCESS });\n  }\n\n  /**\n   * Drain and serialize spans that are descendants of `rootSpanId` within `traceId`.\n   * Filters to the subtree rooted at the test span to prevent cross-test mixing.\n   * Removes the entire traceId entry from the collector.\n   */\n  drainTrace(traceId: string, rootSpanId: string): SerializedSpan[] {\n    const spans = this.peekTrace(traceId, rootSpanId);\n    this.traces.delete(traceId);\n    return spans;\n  }\n\n  /**\n   * Serialize the finished spans of `traceId` without removing them — safe to\n   * call repeatedly while a trace is still growing (e.g. a scenario checker\n   * polling until an async flow's completion boundary closes).\n   *\n   * With `rootSpanId`, filters to that span's subtree like {@link drainTrace}.\n   */\n  peekTrace(traceId: string, rootSpanId?: string): SerializedSpan[] {\n    const allSpans = this.traces.get(traceId);\n    if (!allSpans?.length) return [];\n    if (rootSpanId === undefined) return allSpans.map((s) => serializeSpan(s));\n\n    // Build spanId → span index for efficient parent-chain walking\n    const byId = new Map<string, ReadableSpan>();\n    for (const s of allSpans) byId.set(s.spanContext().spanId, s);\n\n    // Filter to spans that are the root or descendants of rootSpanId\n    const included = allSpans.filter((s) => {\n      let id: string | undefined = s.spanContext().spanId;\n      while (id) {\n        if (id === rootSpanId) return true;\n        const parent = byId.get(id);\n        const parentId = parent?.parentSpanContext?.spanId || undefined;\n        if (parentId === id) break; // cycle guard\n        id = parentId;\n      }\n      return false;\n    });\n\n    return included.map((s) => serializeSpan(s));\n  }\n\n  shutdown(): Promise<void> {\n    this.traces.clear();\n    return Promise.resolve();\n  }\n\n  forceFlush(): Promise<void> {\n    return Promise.resolve();\n  }\n}\n\nfunction hrTimeToMs(hr: [number, number]): number {\n  return hr[0] * 1000 + hr[1] / 1_000_000;\n}\n\nfunction isSerializable(v: unknown): v is SerializableValue {\n  if (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean')\n    return true;\n  if (Array.isArray(v) && v.length > 0) {\n    const t = typeof v[0];\n    return (\n      (t === 'string' || t === 'number' || t === 'boolean') &&\n      v.every((e) => typeof e === t)\n    );\n  }\n  return false;\n}\n\nexport function serializeSpan(span: ReadableSpan): SerializedSpan {\n  const attrs: Record<string, SerializableValue> = {};\n  for (const [k, v] of Object.entries(span.attributes)) {\n    if (isSerializable(v)) attrs[k] = v;\n  }\n  return {\n    spanId: span.spanContext().spanId,\n    parentSpanId: span.parentSpanContext?.spanId || undefined,\n    name: span.name,\n    startTimeMs: hrTimeToMs(span.startTime as [number, number]),\n    durationMs: hrTimeToMs(span.duration as [number, number]),\n    status:\n      span.status.code === SpanStatusCode.ERROR\n        ? 'error'\n        : span.status.code === SpanStatusCode.OK\n          ? 'ok'\n          : 'unset',\n    statusMessage: span.status.message || undefined,\n    attributes: Object.keys(attrs).length > 0 ? attrs : undefined,\n  };\n}\n"],"mappings":";;;;AA2CA,MAAM,mBAAmB;CAAE,SAAS;CAAG,QAAQ;AAAE;AAwBjD,IAAa,oBAAb,MAAuD;CACrD,AAAQ,yBAAS,IAAI,IAA4B;CAEjD,OACE,OACA,UACM;EACN,KAAK,MAAM,QAAQ,OAAO;GACxB,MAAM,UAAU,KAAK,YAAY,CAAC,CAAC;GACnC,IAAI,OAAO,KAAK,OAAO,IAAI,OAAO;GAClC,IAAI,CAAC,MAAM;IACT,OAAO,CAAC;IACR,KAAK,OAAO,IAAI,SAAS,IAAI;GAC/B;GACA,KAAK,KAAK,IAAI;EAChB;EACA,SAAS,EAAE,MAAM,iBAAiB,QAAQ,CAAC;CAC7C;;;;;;CAOA,WAAW,SAAiB,YAAsC;EAChE,MAAM,QAAQ,KAAK,UAAU,SAAS,UAAU;EAChD,KAAK,OAAO,OAAO,OAAO;EAC1B,OAAO;CACT;;;;;;;;CASA,UAAU,SAAiB,YAAuC;EAChE,MAAM,WAAW,KAAK,OAAO,IAAI,OAAO;EACxC,IAAI,CAAC,UAAU,QAAQ,OAAO,CAAC;EAC/B,IAAI,eAAe,QAAW,OAAO,SAAS,KAAK,MAAM,cAAc,CAAC,CAAC;EAGzE,MAAM,uBAAO,IAAI,IAA0B;EAC3C,KAAK,MAAM,KAAK,UAAU,KAAK,IAAI,EAAE,YAAY,CAAC,CAAC,QAAQ,CAAC;EAe5D,OAZiB,SAAS,QAAQ,MAAM;GACtC,IAAI,KAAyB,EAAE,YAAY,CAAC,CAAC;GAC7C,OAAO,IAAI;IACT,IAAI,OAAO,YAAY,OAAO;IAE9B,MAAM,WADS,KAAK,IAAI,EACF,CAAC,EAAE,mBAAmB,UAAU;IACtD,IAAI,aAAa,IAAI;IACrB,KAAK;GACP;GACA,OAAO;EACT,CAEc,CAAC,CAAC,KAAK,MAAM,cAAc,CAAC,CAAC;CAC7C;CAEA,WAA0B;EACxB,KAAK,OAAO,MAAM;EAClB,OAAO,QAAQ,QAAQ;CACzB;CAEA,aAA4B;EAC1B,OAAO,QAAQ,QAAQ;CACzB;AACF;AAEA,SAAS,WAAW,IAA8B;CAChD,OAAO,GAAG,KAAK,MAAO,GAAG,KAAK;AAChC;AAEA,SAAS,eAAe,GAAoC;CAC1D,IAAI,OAAO,MAAM,YAAY,OAAO,MAAM,YAAY,OAAO,MAAM,WACjE,OAAO;CACT,IAAI,MAAM,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG;EACpC,MAAM,IAAI,OAAO,EAAE;EACnB,QACG,MAAM,YAAY,MAAM,YAAY,MAAM,cAC3C,EAAE,OAAO,MAAM,OAAO,MAAM,CAAC;CAEjC;CACA,OAAO;AACT;AAEA,SAAgB,cAAc,MAAoC;CAChE,MAAM,QAA2C,CAAC;CAClD,KAAK,MAAM,CAAC,GAAG,MAAM,OAAO,QAAQ,KAAK,UAAU,GACjD,IAAI,eAAe,CAAC,GAAG,MAAM,KAAK;CAEpC,OAAO;EACL,QAAQ,KAAK,YAAY,CAAC,CAAC;EAC3B,cAAc,KAAK,mBAAmB,UAAU;EAChD,MAAM,KAAK;EACX,aAAa,WAAW,KAAK,SAA6B;EAC1D,YAAY,WAAW,KAAK,QAA4B;EACxD,QACE,KAAK,OAAO,SAAS,eAAe,QAChC,UACA,KAAK,OAAO,SAAS,eAAe,KAClC,OACA;EACR,eAAe,KAAK,OAAO,WAAW;EACtC,YAAY,OAAO,KAAK,KAAK,CAAC,CAAC,SAAS,IAAI,QAAQ;CACtD;AACF"}