autotel 2.1.0

package/dist/sampling.cjs

@@ -0,0 +1,40 @@
+'use strict';
+
+var chunkHE6T6FIX_cjs = require('./chunk-HE6T6FIX.cjs');
+require('./chunk-4OAT42CA.cjs');
+require('./chunk-Y4Y2S7BM.cjs');
+require('./chunk-URRW6M2C.cjs');
+require('./chunk-G7VZBCD6.cjs');
+
+
+
+Object.defineProperty(exports, "AdaptiveSampler", {
+  enumerable: true,
+  get: function () { return chunkHE6T6FIX_cjs.AdaptiveSampler; }
+});
+Object.defineProperty(exports, "AlwaysSampler", {
+  enumerable: true,
+  get: function () { return chunkHE6T6FIX_cjs.AlwaysSampler; }
+});
+Object.defineProperty(exports, "CompositeSampler", {
+  enumerable: true,
+  get: function () { return chunkHE6T6FIX_cjs.CompositeSampler; }
+});
+Object.defineProperty(exports, "FeatureFlagSampler", {
+  enumerable: true,
+  get: function () { return chunkHE6T6FIX_cjs.FeatureFlagSampler; }
+});
+Object.defineProperty(exports, "NeverSampler", {
+  enumerable: true,
+  get: function () { return chunkHE6T6FIX_cjs.NeverSampler; }
+});
+Object.defineProperty(exports, "RandomSampler", {
+  enumerable: true,
+  get: function () { return chunkHE6T6FIX_cjs.RandomSampler; }
+});
+Object.defineProperty(exports, "UserIdSampler", {
+  enumerable: true,
+  get: function () { return chunkHE6T6FIX_cjs.UserIdSampler; }
+});
+//# sourceMappingURL=sampling.cjs.map
+//# sourceMappingURL=sampling.cjs.map

package/dist/sampling.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"sampling.cjs"}

package/dist/sampling.d.cts

@@ -0,0 +1,260 @@
+import { Logger } from './logger.cjs';
+import 'pino';
+
+/**
+ * Sampling Strategies
+ *
+ * Provides intelligent sampling beyond simple random rates.
+ * Helps reduce telemetry costs while capturing critical data.
+ *
+ * Key strategies:
+ * - Always trace errors and slow requests (critical for debugging)
+ * - Sample by user ID for consistent request tracing
+ * - Adaptive sampling based on load
+ * - Sample by feature flags for A/B testing correlation
+ *
+ * @example
+ * ```typescript
+ * import { AlwaysOnErrorSampler, UserIdSampler } from './sampling'
+ *
+ * @Instrumented({
+ *   serviceName: 'user',
+ *   sampler: new AlwaysOnErrorSampler(0.1) // 10% baseline, 100% on errors
+ * })
+ * class UserService { }
+ * ```
+ */
+
+/**
+ * Sampler interface - return true to trace, false to skip
+ */
+interface Sampler {
+    /**
+     * Decide whether to trace this operation
+     *
+     * @param context - Sampling context
+     * @returns true to trace, false to skip
+     */
+    shouldSample(context: SamplingContext): boolean;
+    /**
+     * Whether this sampler needs tail sampling (post-execution decision)
+     * If true, spans are always created and shouldKeepTrace() is called after execution
+     *
+     * @returns true if this sampler needs to evaluate after operation completes
+     */
+    needsTailSampling?(): boolean;
+    /**
+     * Re-evaluate sampling decision after operation completes (tail sampling)
+     * Only called if needsTailSampling() returns true
+     *
+     * @param context - Sampling context
+     * @param result - Operation result
+     * @returns true if this trace should be kept, false to drop it
+     */
+    shouldKeepTrace?(context: SamplingContext, result: OperationResult): boolean;
+}
+/**
+ * Context information for sampling decisions
+ */
+interface SamplingContext {
+    /** Operation name */
+    operationName: string;
+    /** Method arguments (for extracting user IDs, etc.) */
+    args: unknown[];
+    /** Optional metadata (e.g., feature flags, request headers) */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Result of a trace operation (for post-execution sampling)
+ */
+interface OperationResult {
+    /** Whether the operation succeeded */
+    success: boolean;
+    /** Duration in milliseconds */
+    duration: number;
+    /** Error if operation failed */
+    error?: Error;
+}
+/**
+ * Simple random sampler
+ *
+ * @example
+ * ```typescript
+ * new RandomSampler(0.1) // Sample 10% of requests
+ * ```
+ */
+declare class RandomSampler implements Sampler {
+    private readonly sampleRate;
+    constructor(sampleRate: number);
+    shouldSample(_context: SamplingContext): boolean;
+}
+/**
+ * Always sample (100% tracing)
+ */
+declare class AlwaysSampler implements Sampler {
+    shouldSample(_context: SamplingContext): boolean;
+}
+/**
+ * Never sample (0% tracing)
+ */
+declare class NeverSampler implements Sampler {
+    shouldSample(_context: SamplingContext): boolean;
+}
+/**
+ * Adaptive sampler that always traces errors and slow requests
+ *
+ * This is the recommended sampler for production use.
+ * It ensures you never miss critical issues while keeping costs down.
+ *
+ * Strategy:
+ * - Always trace errors (critical for debugging)
+ * - Always trace slow requests (performance issues)
+ * - Use baseline sample rate for successful fast requests
+ *
+ * **IMPORTANT - Tail Sampling Requirement:**
+ * This sampler uses tail sampling (makes decisions AFTER execution).
+ * You MUST use TailSamplingSpanProcessor for it to work correctly:
+ *
+ * - If using initInstrumentation(): TailSamplingSpanProcessor is auto-configured
+ * - If using custom TracerProvider: You MUST manually register TailSamplingSpanProcessor
+ *
+ * Without TailSamplingSpanProcessor, ALL spans are exported (defeating the cost savings).
+ *
+ * @see TailSamplingSpanProcessor
+ * @see README.md "Tail Sampling with Custom Providers" section
+ *
+ * @example
+ * ```typescript
+ * new AdaptiveSampler({
+ *   baselineSampleRate: 0.1,    // 10% of normal requests
+ *   slowThresholdMs: 1000,       // Requests > 1s are "slow"
+ *   alwaysSampleErrors: true,    // Always trace errors
+ *   alwaysSampleSlow: true       // Always trace slow requests
+ * })
+ * ```
+ */
+declare class AdaptiveSampler implements Sampler {
+    private baselineSampleRate;
+    private slowThresholdMs;
+    private alwaysSampleErrors;
+    private alwaysSampleSlow;
+    private logger?;
+    private readonly samplingDecisions;
+    private readonly operationResults;
+    constructor(options?: {
+        baselineSampleRate?: number;
+        slowThresholdMs?: number;
+        alwaysSampleErrors?: boolean;
+        alwaysSampleSlow?: boolean;
+        logger?: Logger;
+    });
+    needsTailSampling(): boolean;
+    shouldSample(context: SamplingContext): boolean;
+    /**
+     * Re-evaluate sampling decision after operation completes
+     *
+     * This allows us to always capture errors and slow requests,
+     * even if they weren't initially sampled.
+     *
+     * @param context - Sampling context
+     * @param result - Operation result
+     * @returns true if this operation should be kept (not discarded)
+     */
+    shouldKeepTrace(context: SamplingContext, result: OperationResult): boolean;
+}
+/**
+ * User-based sampler for consistent tracing
+ *
+ * Always samples requests from specific user IDs.
+ * Useful for debugging specific user issues or monitoring VIP users.
+ *
+ * @example
+ * ```typescript
+ * new UserIdSampler({
+ *   baselineSampleRate: 0.01,      // 1% of normal users
+ *   alwaysSampleUsers: ['vip_123'], // Always trace VIP users
+ *   extractUserId: (args) => args[0]?.userId // Extract user ID from first arg
+ * })
+ * ```
+ */
+declare class UserIdSampler implements Sampler {
+    private baselineSampleRate;
+    private alwaysSampleUsers;
+    private extractUserId;
+    private logger?;
+    constructor(options: {
+        baselineSampleRate?: number;
+        alwaysSampleUsers?: string[];
+        extractUserId: (args: unknown[]) => string | undefined;
+        logger?: Logger;
+    });
+    shouldSample(context: SamplingContext): boolean;
+    /**
+     * Add user IDs to always-sample list
+     */
+    addAlwaysSampleUsers(...userIds: string[]): void;
+    /**
+     * Remove user IDs from always-sample list
+     */
+    removeAlwaysSampleUsers(...userIds: string[]): void;
+    /**
+     * Simple hash function for consistent user sampling
+     */
+    private hashString;
+}
+/**
+ * Composite sampler that combines multiple samplers
+ *
+ * Samples if ANY of the child samplers returns true.
+ *
+ * @example
+ * ```typescript
+ * new CompositeSampler([
+ *   new UserIdSampler({ extractUserId: (args) => args[0]?.userId }),
+ *   new AdaptiveSampler({ baselineSampleRate: 0.1 })
+ * ])
+ * ```
+ */
+declare class CompositeSampler implements Sampler {
+    private readonly samplers;
+    constructor(samplers: Sampler[]);
+    shouldSample(context: SamplingContext): boolean;
+}
+/**
+ * Feature flag sampler
+ *
+ * Always samples requests with specific feature flags enabled.
+ * Perfect for correlating A/B test experiments with metrics.
+ *
+ * @example
+ * ```typescript
+ * new FeatureFlagSampler({
+ *   baselineSampleRate: 0.01,
+ *   alwaysSampleFlags: ['new_checkout', 'experimental_ui'],
+ *   extractFlags: (args, metadata) => metadata?.featureFlags
+ * })
+ * ```
+ */
+declare class FeatureFlagSampler implements Sampler {
+    private baselineSampleRate;
+    private alwaysSampleFlags;
+    private extractFlags;
+    private logger?;
+    constructor(options: {
+        baselineSampleRate?: number;
+        alwaysSampleFlags?: string[];
+        extractFlags: (args: unknown[], metadata?: Record<string, unknown>) => string[] | undefined;
+        logger?: Logger;
+    });
+    shouldSample(context: SamplingContext): boolean;
+    /**
+     * Add feature flags to always-sample list
+     */
+    addAlwaysSampleFlags(...flags: string[]): void;
+    /**
+     * Remove feature flags from always-sample list
+     */
+    removeAlwaysSampleFlags(...flags: string[]): void;
+}
+
+export { AdaptiveSampler, AlwaysSampler, CompositeSampler, FeatureFlagSampler, NeverSampler, type OperationResult, RandomSampler, type Sampler, type SamplingContext, UserIdSampler };

package/dist/sampling.d.ts

@@ -0,0 +1,260 @@
+import { Logger } from './logger.js';
+import 'pino';
+
+/**
+ * Sampling Strategies
+ *
+ * Provides intelligent sampling beyond simple random rates.
+ * Helps reduce telemetry costs while capturing critical data.
+ *
+ * Key strategies:
+ * - Always trace errors and slow requests (critical for debugging)
+ * - Sample by user ID for consistent request tracing
+ * - Adaptive sampling based on load
+ * - Sample by feature flags for A/B testing correlation
+ *
+ * @example
+ * ```typescript
+ * import { AlwaysOnErrorSampler, UserIdSampler } from './sampling'
+ *
+ * @Instrumented({
+ *   serviceName: 'user',
+ *   sampler: new AlwaysOnErrorSampler(0.1) // 10% baseline, 100% on errors
+ * })
+ * class UserService { }
+ * ```
+ */
+
+/**
+ * Sampler interface - return true to trace, false to skip
+ */
+interface Sampler {
+    /**
+     * Decide whether to trace this operation
+     *
+     * @param context - Sampling context
+     * @returns true to trace, false to skip
+     */
+    shouldSample(context: SamplingContext): boolean;
+    /**
+     * Whether this sampler needs tail sampling (post-execution decision)
+     * If true, spans are always created and shouldKeepTrace() is called after execution
+     *
+     * @returns true if this sampler needs to evaluate after operation completes
+     */
+    needsTailSampling?(): boolean;
+    /**
+     * Re-evaluate sampling decision after operation completes (tail sampling)
+     * Only called if needsTailSampling() returns true
+     *
+     * @param context - Sampling context
+     * @param result - Operation result
+     * @returns true if this trace should be kept, false to drop it
+     */
+    shouldKeepTrace?(context: SamplingContext, result: OperationResult): boolean;
+}
+/**
+ * Context information for sampling decisions
+ */
+interface SamplingContext {
+    /** Operation name */
+    operationName: string;
+    /** Method arguments (for extracting user IDs, etc.) */
+    args: unknown[];
+    /** Optional metadata (e.g., feature flags, request headers) */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Result of a trace operation (for post-execution sampling)
+ */
+interface OperationResult {
+    /** Whether the operation succeeded */
+    success: boolean;
+    /** Duration in milliseconds */
+    duration: number;
+    /** Error if operation failed */
+    error?: Error;
+}
+/**
+ * Simple random sampler
+ *
+ * @example
+ * ```typescript
+ * new RandomSampler(0.1) // Sample 10% of requests
+ * ```
+ */
+declare class RandomSampler implements Sampler {
+    private readonly sampleRate;
+    constructor(sampleRate: number);
+    shouldSample(_context: SamplingContext): boolean;
+}
+/**
+ * Always sample (100% tracing)
+ */
+declare class AlwaysSampler implements Sampler {
+    shouldSample(_context: SamplingContext): boolean;
+}
+/**
+ * Never sample (0% tracing)
+ */
+declare class NeverSampler implements Sampler {
+    shouldSample(_context: SamplingContext): boolean;
+}
+/**
+ * Adaptive sampler that always traces errors and slow requests
+ *
+ * This is the recommended sampler for production use.
+ * It ensures you never miss critical issues while keeping costs down.
+ *
+ * Strategy:
+ * - Always trace errors (critical for debugging)
+ * - Always trace slow requests (performance issues)
+ * - Use baseline sample rate for successful fast requests
+ *
+ * **IMPORTANT - Tail Sampling Requirement:**
+ * This sampler uses tail sampling (makes decisions AFTER execution).
+ * You MUST use TailSamplingSpanProcessor for it to work correctly:
+ *
+ * - If using initInstrumentation(): TailSamplingSpanProcessor is auto-configured
+ * - If using custom TracerProvider: You MUST manually register TailSamplingSpanProcessor
+ *
+ * Without TailSamplingSpanProcessor, ALL spans are exported (defeating the cost savings).
+ *
+ * @see TailSamplingSpanProcessor
+ * @see README.md "Tail Sampling with Custom Providers" section
+ *
+ * @example
+ * ```typescript
+ * new AdaptiveSampler({
+ *   baselineSampleRate: 0.1,    // 10% of normal requests
+ *   slowThresholdMs: 1000,       // Requests > 1s are "slow"
+ *   alwaysSampleErrors: true,    // Always trace errors
+ *   alwaysSampleSlow: true       // Always trace slow requests
+ * })
+ * ```
+ */
+declare class AdaptiveSampler implements Sampler {
+    private baselineSampleRate;
+    private slowThresholdMs;
+    private alwaysSampleErrors;
+    private alwaysSampleSlow;
+    private logger?;
+    private readonly samplingDecisions;
+    private readonly operationResults;
+    constructor(options?: {
+        baselineSampleRate?: number;
+        slowThresholdMs?: number;
+        alwaysSampleErrors?: boolean;
+        alwaysSampleSlow?: boolean;
+        logger?: Logger;
+    });
+    needsTailSampling(): boolean;
+    shouldSample(context: SamplingContext): boolean;
+    /**
+     * Re-evaluate sampling decision after operation completes
+     *
+     * This allows us to always capture errors and slow requests,
+     * even if they weren't initially sampled.
+     *
+     * @param context - Sampling context
+     * @param result - Operation result
+     * @returns true if this operation should be kept (not discarded)
+     */
+    shouldKeepTrace(context: SamplingContext, result: OperationResult): boolean;
+}
+/**
+ * User-based sampler for consistent tracing
+ *
+ * Always samples requests from specific user IDs.
+ * Useful for debugging specific user issues or monitoring VIP users.
+ *
+ * @example
+ * ```typescript
+ * new UserIdSampler({
+ *   baselineSampleRate: 0.01,      // 1% of normal users
+ *   alwaysSampleUsers: ['vip_123'], // Always trace VIP users
+ *   extractUserId: (args) => args[0]?.userId // Extract user ID from first arg
+ * })
+ * ```
+ */
+declare class UserIdSampler implements Sampler {
+    private baselineSampleRate;
+    private alwaysSampleUsers;
+    private extractUserId;
+    private logger?;
+    constructor(options: {
+        baselineSampleRate?: number;
+        alwaysSampleUsers?: string[];
+        extractUserId: (args: unknown[]) => string | undefined;
+        logger?: Logger;
+    });
+    shouldSample(context: SamplingContext): boolean;
+    /**
+     * Add user IDs to always-sample list
+     */
+    addAlwaysSampleUsers(...userIds: string[]): void;
+    /**
+     * Remove user IDs from always-sample list
+     */
+    removeAlwaysSampleUsers(...userIds: string[]): void;
+    /**
+     * Simple hash function for consistent user sampling
+     */
+    private hashString;
+}
+/**
+ * Composite sampler that combines multiple samplers
+ *
+ * Samples if ANY of the child samplers returns true.
+ *
+ * @example
+ * ```typescript
+ * new CompositeSampler([
+ *   new UserIdSampler({ extractUserId: (args) => args[0]?.userId }),
+ *   new AdaptiveSampler({ baselineSampleRate: 0.1 })
+ * ])
+ * ```
+ */
+declare class CompositeSampler implements Sampler {
+    private readonly samplers;
+    constructor(samplers: Sampler[]);
+    shouldSample(context: SamplingContext): boolean;
+}
+/**
+ * Feature flag sampler
+ *
+ * Always samples requests with specific feature flags enabled.
+ * Perfect for correlating A/B test experiments with metrics.
+ *
+ * @example
+ * ```typescript
+ * new FeatureFlagSampler({
+ *   baselineSampleRate: 0.01,
+ *   alwaysSampleFlags: ['new_checkout', 'experimental_ui'],
+ *   extractFlags: (args, metadata) => metadata?.featureFlags
+ * })
+ * ```
+ */
+declare class FeatureFlagSampler implements Sampler {
+    private baselineSampleRate;
+    private alwaysSampleFlags;
+    private extractFlags;
+    private logger?;
+    constructor(options: {
+        baselineSampleRate?: number;
+        alwaysSampleFlags?: string[];
+        extractFlags: (args: unknown[], metadata?: Record<string, unknown>) => string[] | undefined;
+        logger?: Logger;
+    });
+    shouldSample(context: SamplingContext): boolean;
+    /**
+     * Add feature flags to always-sample list
+     */
+    addAlwaysSampleFlags(...flags: string[]): void;
+    /**
+     * Remove feature flags from always-sample list
+     */
+    removeAlwaysSampleFlags(...flags: string[]): void;
+}
+
+export { AdaptiveSampler, AlwaysSampler, CompositeSampler, FeatureFlagSampler, NeverSampler, type OperationResult, RandomSampler, type Sampler, type SamplingContext, UserIdSampler };

package/dist/sampling.js

@@ -0,0 +1,7 @@
+export { AdaptiveSampler, AlwaysSampler, CompositeSampler, FeatureFlagSampler, NeverSampler, RandomSampler, UserIdSampler } from './chunk-5R2M36QB.js';
+import './chunk-5GWX5LFW.js';
+import './chunk-KVGNW3FC.js';
+import './chunk-P6JUDYNO.js';
+import './chunk-Z6ZWNWWR.js';
+//# sourceMappingURL=sampling.js.map
+//# sourceMappingURL=sampling.js.map

package/dist/sampling.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"sampling.js"}

package/dist/semantic-helpers.cjs

@@ -0,0 +1,35 @@
+'use strict';
+
+var chunkKIXWPOCO_cjs = require('./chunk-KIXWPOCO.cjs');
+require('./chunk-WBWNM6LB.cjs');
+require('./chunk-TRI4V5BF.cjs');
+require('./chunk-NHCNRQD3.cjs');
+require('./chunk-YLPNXZFI.cjs');
+require('./chunk-ABPEQ6RK.cjs');
+require('./chunk-GVLK7YUU.cjs');
+require('./chunk-HE6T6FIX.cjs');
+require('./chunk-4OAT42CA.cjs');
+require('./chunk-Y4Y2S7BM.cjs');
+require('./chunk-URRW6M2C.cjs');
+require('./chunk-G7VZBCD6.cjs');
+
+
+
+Object.defineProperty(exports, "traceDB", {
+  enumerable: true,
+  get: function () { return chunkKIXWPOCO_cjs.traceDB; }
+});
+Object.defineProperty(exports, "traceHTTP", {
+  enumerable: true,
+  get: function () { return chunkKIXWPOCO_cjs.traceHTTP; }
+});
+Object.defineProperty(exports, "traceLLM", {
+  enumerable: true,
+  get: function () { return chunkKIXWPOCO_cjs.traceLLM; }
+});
+Object.defineProperty(exports, "traceMessaging", {
+  enumerable: true,
+  get: function () { return chunkKIXWPOCO_cjs.traceMessaging; }
+});
+//# sourceMappingURL=semantic-helpers.cjs.map
+//# sourceMappingURL=semantic-helpers.cjs.map

package/dist/semantic-helpers.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"semantic-helpers.cjs"}