autotel 2.25.2 → 2.25.4

package/src/index.ts

@@ -60,6 +60,7 @@ export {
   AttributeRedactingProcessor,
   REDACTOR_PATTERNS,
   REDACTOR_PRESETS,
+  createAttributeRedactor,
   createRedactedSpan,
   type AttributeRedactorFn,
   type AttributeRedactorPreset,
@@ -151,6 +152,7 @@ export { formatDuration } from './pretty-log-formatter';
 export {
   type Sampler,
   type SamplingContext,
+  type SamplingPreset,
   AlwaysSampler,
   NeverSampler,
   RandomSampler,
@@ -158,6 +160,10 @@ export {
   UserIdSampler,
   createLinkFromHeaders,
   extractLinksFromBatch,
+  samplingPresets,
+  resolveSamplingPreset,
+  AUTOTEL_SAMPLING_TAIL_KEEP,
+  AUTOTEL_SAMPLING_TAIL_EVALUATED,
 } from './sampling';
 
 // Events API

package/src/init.customization.test.ts

@@ -3,6 +3,7 @@ import type { MetricReader } from '@opentelemetry/sdk-metrics';
 import type { NodeSDK } from '@opentelemetry/sdk-node';
 import type { SpanProcessor } from '@opentelemetry/sdk-trace-base';
 import { mock, mockDeep, type DeepMockProxy } from 'vitest-mock-extended';
+import { AlwaysSampler, NeverSampler } from './sampling';
 
 type SdkRecord = {
   options: Record<string, unknown>;
@@ -112,6 +113,7 @@ async function loadInitWithMocks() {
   return {
     init: mod.init,
     getConfig: mod.getConfig,
+    getDefaultSampler: mod.getDefaultSampler,
     resolveLogsFlag: mod.resolveLogsFlag,
     sdkInstances,
     traceExporterOptions,
@@ -128,6 +130,8 @@ describe('init() customization', () => {
     delete process.env.AUTOTEL_METRICS;
     delete process.env.AUTOTEL_LOGS;
     delete process.env.OTEL_LOGS_EXPORTER;
+    delete process.env.OTEL_TRACES_SAMPLER;
+    delete process.env.OTEL_TRACES_SAMPLER_ARG;
     delete process.env.NODE_ENV;
   });
 
@@ -227,6 +231,63 @@ describe('init() customization', () => {
     });
   });
 
+  it('resolves sampling preset shorthand to a sampler instance', async () => {
+    const { init, getDefaultSampler } = await loadInitWithMocks();
+
+    init({
+      service: 'sampling-preset-app',
+      sampling: 'development',
+    });
+
+    const sampler = getDefaultSampler();
+    expect(sampler.constructor.name).toBe('AlwaysSampler');
+    expect(sampler.shouldSample({ operationName: 'test', args: [] })).toBe(
+      true,
+    );
+  });
+
+  it('prefers explicit sampler over sampling preset shorthand', async () => {
+    const { init, getDefaultSampler } = await loadInitWithMocks();
+    const explicitSampler = new NeverSampler();
+
+    init({
+      service: 'sampling-precedence-app',
+      sampler: explicitSampler,
+      sampling: 'development',
+    });
+
+    expect(getDefaultSampler()).toBe(explicitSampler);
+  });
+
+  it('uses OTEL_TRACES_SAMPLER when no explicit sampling config is provided', async () => {
+    process.env.OTEL_TRACES_SAMPLER = 'always_off';
+    const { init, sdkInstances } = await loadInitWithMocks();
+
+    init({
+      service: 'env-sampler-app',
+    });
+
+    const options = sdkInstances.at(-1)?.options as Record<string, unknown>;
+    expect((options.sampler as { toString(): string }).toString()).toContain(
+      'AlwaysOffSampler',
+    );
+  });
+
+  it('prefers explicit sampling config over OTEL_TRACES_SAMPLER', async () => {
+    process.env.OTEL_TRACES_SAMPLER = 'always_off';
+    const { init, sdkInstances } = await loadInitWithMocks();
+
+    init({
+      service: 'explicit-over-env-sampler-app',
+      sampling: 'development',
+    });
+
+    const options = sdkInstances.at(-1)?.options as Record<string, unknown>;
+    expect((options.sampler as { toString(): string }).toString()).toBe(
+      'AutotelSamplerAdapter',
+    );
+  });
+
   it('supports sdkFactory overrides', async () => {
     const { init, sdkInstances } = await loadInitWithMocks();
     const customSdk = mockDeep<NodeSDK>();

package/src/init.integrations.test.ts

@@ -182,13 +182,18 @@ describe('init() integrations vs instrumentations', () => {
     _resetAutoInstrumentationsLoader();
   });
 
-  afterEach(() => {
+  afterEach(async () => {
     for (const mod of mockedModules) {
       vi.doUnmock(mod);
     }
     vi.clearAllMocks();
     _resetAutoInstrumentationsLoader();
     delete process.env.AUTOTEL_METRICS;
+    // Reset global OTel state that can leak between forked test files
+    const { trace, context, propagation } = await import('@opentelemetry/api');
+    trace.disable();
+    context.disable();
+    propagation.disable();
   });
 
   it('excludes manual instrumentations from auto-instrumentations when autoInstrumentations: true', async () => {

package/src/init.ts

@@ -25,8 +25,8 @@ import {
   ATTR_SERVICE_NAME,
   ATTR_SERVICE_VERSION,
 } from '@opentelemetry/semantic-conventions';
-import type { Sampler } from './sampling';
-import { AdaptiveSampler } from './sampling';
+import type { Sampler, SamplingPreset } from './sampling';
+import { samplingPresets, resolveSamplingPreset } from './sampling';
 import type { EventSubscriber } from './event-subscriber';
 import type { Logger } from './logger';
 import type { Attributes, Context, SpanKind, Link } from '@opentelemetry/api';
@@ -603,9 +603,17 @@ export interface AutotelConfig {
    */
   logs?: boolean | 'auto';
 
-  /** Sampling strategy (default: AdaptiveSampler with 10% baseline) */
+  /** Sampling strategy - takes precedence over `sampling` preset */
   sampler?: Sampler;
 
+  /**
+   * Sampling preset shorthand — resolves to a pre-configured sampler.
+   * If both `sampler` and `sampling` are provided, `sampler` takes precedence.
+   *
+   * @default 'production'
+   */
+  sampling?: SamplingPreset;
+
   /** Service version (default: auto-detect from package.json or '1.0.0') */
   version?: string;
 
@@ -1592,8 +1600,17 @@ export function init(cfg: AutotelConfig): void {
     }
   }
 
-  const autotelSampler = mergedConfig.sampler || getDefaultSampler();
-  const sampler: OtelSampler = toOtelSampler(autotelSampler);
+  const autotelSampler =
+    mergedConfig.sampler ??
+    (mergedConfig.sampling
+      ? resolveSamplingPreset(mergedConfig.sampling)
+      : undefined);
+  if (autotelSampler) {
+    mergedConfig.sampler = autotelSampler;
+  }
+  const sampler: OtelSampler = autotelSampler
+    ? toOtelSampler(autotelSampler)
+    : (envConfig.otelSampler ?? toOtelSampler(samplingPresets.production()));
 
   const sdkOptions: Partial<NodeSDKConfiguration> = {
     resource,
@@ -1921,14 +1938,7 @@ export function warnIfNotInitialized(context: string): void {
  * Get default sampler
  */
 export function getDefaultSampler(): Sampler {
-  return (
-    config?.sampler ||
-    new AdaptiveSampler({
-      baselineSampleRate: 0.1,
-      alwaysSampleErrors: true,
-      alwaysSampleSlow: true,
-    })
-  );
+  return config?.sampler || samplingPresets.production();
 }
 
 /**

package/src/instrumentation.ts

@@ -249,7 +249,7 @@ export async function initInstrumentation(
     headers: otlpHeaders,
   });
 
-  // Enables tail sampling via sampling.tail.keep attribute
+  // Enables tail sampling via autotel.sampling.tail.keep attribute
   const spanProcessor = new TailSamplingSpanProcessor(
     new BatchSpanProcessor(traceExporter),
   );

package/src/sampling.test.ts

@@ -11,6 +11,8 @@ import {
   FeatureFlagSampler,
   createLinkFromHeaders,
   extractLinksFromBatch,
+  samplingPresets,
+  resolveSamplingPreset,
   type SamplingContext,
 } from './sampling';
 import { type ILogger } from './logger';
@@ -64,9 +66,9 @@ describe('Sampling', () => {
       );
 
       const sampleCount = results.filter(Boolean).length;
-      // Allow 10% margin of error
-      expect(sampleCount).toBeGreaterThan(450);
-      expect(sampleCount).toBeLessThan(550);
+      // Allow 20% margin of error — random sampling is inherently noisy
+      expect(sampleCount).toBeGreaterThan(400);
+      expect(sampleCount).toBeLessThan(600);
     });
   });
 
@@ -964,4 +966,95 @@ describe('Sampling', () => {
       });
     });
   });
+
+  describe('samplingPresets', () => {
+    it('development() returns AlwaysSampler', () => {
+      const sampler = samplingPresets.development();
+      expect(sampler).toBeInstanceOf(AlwaysSampler);
+      expect(sampler.shouldSample(context)).toBe(true);
+    });
+
+    it('errorsOnly() returns AdaptiveSampler that drops healthy baseline', () => {
+      const sampler = samplingPresets.errorsOnly();
+      expect(sampler).toBeInstanceOf(AdaptiveSampler);
+      sampler.shouldSample(context); // prime the WeakMap baseline decision
+      // Baseline is 0, so shouldKeepTrace for successful fast requests = false
+      expect(
+        sampler.shouldKeepTrace!(context, { success: true, duration: 50 }),
+      ).toBe(false);
+    });
+
+    it('errorsOnly() keeps errors', () => {
+      const sampler = samplingPresets.errorsOnly();
+      sampler.shouldSample(context); // prime the baseline decision
+      expect(
+        sampler.shouldKeepTrace!(context, {
+          success: false,
+          duration: 50,
+          error: new Error('fail'),
+        }),
+      ).toBe(true);
+    });
+
+    it('production() returns AdaptiveSampler with 10% baseline', () => {
+      const sampler = samplingPresets.production();
+      expect(sampler).toBeInstanceOf(AdaptiveSampler);
+      expect(sampler.needsTailSampling!()).toBe(true);
+    });
+
+    it('production() keeps errors', () => {
+      const sampler = samplingPresets.production();
+      sampler.shouldSample(context);
+      expect(
+        sampler.shouldKeepTrace!(context, {
+          success: false,
+          duration: 50,
+          error: new Error('fail'),
+        }),
+      ).toBe(true);
+    });
+
+    it('production() accepts overrides', () => {
+      const sampler = samplingPresets.production({ baselineSampleRate: 1.0 });
+      sampler.shouldSample(context);
+      // With 100% baseline, all healthy traffic is kept
+      expect(
+        sampler.shouldKeepTrace!(context, { success: true, duration: 50 }),
+      ).toBe(true);
+    });
+
+    it('off() returns NeverSampler', () => {
+      const sampler = samplingPresets.off();
+      expect(sampler).toBeInstanceOf(NeverSampler);
+      expect(sampler.shouldSample(context)).toBe(false);
+    });
+  });
+
+  describe('resolveSamplingPreset', () => {
+    it('resolves development', () => {
+      const sampler = resolveSamplingPreset('development');
+      expect(sampler).toBeInstanceOf(AlwaysSampler);
+    });
+
+    it('resolves errors-only', () => {
+      const sampler = resolveSamplingPreset('errors-only');
+      expect(sampler).toBeInstanceOf(AdaptiveSampler);
+    });
+
+    it('resolves production', () => {
+      const sampler = resolveSamplingPreset('production');
+      expect(sampler).toBeInstanceOf(AdaptiveSampler);
+    });
+
+    it('resolves off', () => {
+      const sampler = resolveSamplingPreset('off');
+      expect(sampler).toBeInstanceOf(NeverSampler);
+    });
+
+    it('throws on invalid preset with helpful message', () => {
+      expect(() => resolveSamplingPreset('banana' as any)).toThrow(
+        /Unknown sampling preset: "banana".*Valid presets: development, errors-only, production, off/,
+      );
+    });
+  });
 });

package/src/sampling.ts

@@ -26,6 +26,13 @@ import type { Link, Attributes } from '@opentelemetry/api';
 import { TraceFlags } from '@opentelemetry/api';
 import { type Logger } from './logger';
 
+/**
+ * Tail sampling attribute keys (autotel-internal, not OTel semconv)
+ */
+export const AUTOTEL_SAMPLING_TAIL_KEEP = 'autotel.sampling.tail.keep';
+export const AUTOTEL_SAMPLING_TAIL_EVALUATED =
+  'autotel.sampling.tail.evaluated';
+
 /**
  * Sampler interface - return true to trace, false to skip
  */
@@ -493,6 +500,89 @@ export class FeatureFlagSampler implements Sampler {
   }
 }
 
+// ============================================================================
+// Sampling Presets
+// ============================================================================
+
+/**
+ * Named sampling presets for common environments.
+ * Use with `init({ sampling: 'production' })` or directly via factories.
+ */
+export type SamplingPreset =
+  | 'development'
+  | 'errors-only'
+  | 'production'
+  | 'off';
+
+/**
+ * Sampling preset factories.
+ *
+ * For most users, the string shorthand on `init()` is simpler:
+ * ```typescript
+ * init({ service: 'my-app', sampling: 'production' })
+ * ```
+ *
+ * Use factories when you need to customize:
+ * ```typescript
+ * init({ service: 'my-app', sampler: samplingPresets.production({ baselineSampleRate: 0.05 }) })
+ * ```
+ */
+export const samplingPresets = {
+  /** Capture everything — best for local development and debugging */
+  development: () => new AlwaysSampler(),
+
+  /** Only bad outcomes — zero baseline, errors always kept */
+  errorsOnly: () =>
+    new AdaptiveSampler({
+      baselineSampleRate: 0,
+      alwaysSampleErrors: true,
+    }),
+
+  /**
+   * Balanced production defaults — 10% baseline + errors + slow traces.
+   * Pass overrides to tune (uses the same option names as AdaptiveSampler).
+   */
+  production: (overrides?: {
+    baselineSampleRate?: number;
+    slowThresholdMs?: number;
+    alwaysSampleErrors?: boolean;
+    alwaysSampleSlow?: boolean;
+  }) =>
+    new AdaptiveSampler({
+      baselineSampleRate: 0.1,
+      alwaysSampleErrors: true,
+      alwaysSampleSlow: true,
+      slowThresholdMs: 1000,
+      ...overrides,
+    }),
+
+  /** Disable sampling entirely */
+  off: () => new NeverSampler(),
+};
+
+/**
+ * Resolve a preset string to a Sampler instance.
+ * Used internally by `init()` when `sampling` string is provided.
+ *
+ * @throws Error if preset is not recognized
+ */
+export function resolveSamplingPreset(preset: SamplingPreset): Sampler {
+  switch (preset) {
+    case 'development':
+      return samplingPresets.development();
+    case 'errors-only':
+      return samplingPresets.errorsOnly();
+    case 'production':
+      return samplingPresets.production();
+    case 'off':
+      return samplingPresets.off();
+    default:
+      throw new Error(
+        `Unknown sampling preset: "${preset}". Valid presets: development, errors-only, production, off`,
+      );
+  }
+}
+
 // ============================================================================
 // Link Helper Functions
 // ============================================================================

package/src/tail-sampling-processor.test.ts

@@ -4,6 +4,10 @@
 
 import { describe, it, expect, beforeEach } from 'vitest';
 import { TailSamplingSpanProcessor } from './tail-sampling-processor';
+import {
+  AUTOTEL_SAMPLING_TAIL_KEEP,
+  AUTOTEL_SAMPLING_TAIL_EVALUATED,
+} from './sampling';
 import type {
   SpanProcessor,
   ReadableSpan,
@@ -86,8 +90,8 @@ describe('TailSamplingSpanProcessor', () => {
 
     it('should forward spans marked to keep (sampling.tail.keep = true)', () => {
       const span = createMockSpan({
-        'sampling.tail.evaluated': true,
-        'sampling.tail.keep': true,
+        [AUTOTEL_SAMPLING_TAIL_EVALUATED]: true,
+        [AUTOTEL_SAMPLING_TAIL_KEEP]: true,
       });
 
       tailSamplingProcessor.onEnd(span);
@@ -100,8 +104,8 @@ describe('TailSamplingSpanProcessor', () => {
   describe('Span dropping', () => {
     it('should drop spans marked to drop (sampling.tail.keep = false)', () => {
       const span = createMockSpan({
-        'sampling.tail.evaluated': true,
-        'sampling.tail.keep': false,
+        [AUTOTEL_SAMPLING_TAIL_EVALUATED]: true,
+        [AUTOTEL_SAMPLING_TAIL_KEEP]: false,
       });
 
       tailSamplingProcessor.onEnd(span);
@@ -112,13 +116,13 @@ describe('TailSamplingSpanProcessor', () => {
 
     it('should drop multiple spans marked as false', () => {
       const span1 = createMockSpan({
-        'sampling.tail.evaluated': true,
-        'sampling.tail.keep': false,
+        [AUTOTEL_SAMPLING_TAIL_EVALUATED]: true,
+        [AUTOTEL_SAMPLING_TAIL_KEEP]: false,
       });
 
       const span2 = createMockSpan({
-        'sampling.tail.evaluated': true,
-        'sampling.tail.keep': false,
+        [AUTOTEL_SAMPLING_TAIL_EVALUATED]: true,
+        [AUTOTEL_SAMPLING_TAIL_KEEP]: false,
       });
 
       tailSamplingProcessor.onEnd(span1);
@@ -131,8 +135,8 @@ describe('TailSamplingSpanProcessor', () => {
   describe('Edge cases', () => {
     it('should forward spans when only evaluated but no keep attribute', () => {
       const span = createMockSpan({
-        'sampling.tail.evaluated': true,
-        // Missing 'sampling.tail.keep'
+        [AUTOTEL_SAMPLING_TAIL_EVALUATED]: true,
+        // Missing AUTOTEL_SAMPLING_TAIL_KEEP
       });
 
       tailSamplingProcessor.onEnd(span);
@@ -143,8 +147,8 @@ describe('TailSamplingSpanProcessor', () => {
 
     it('should forward spans when only keep but not evaluated', () => {
       const span = createMockSpan({
-        // Missing 'sampling.tail.evaluated'
-        'sampling.tail.keep': false,
+        // Missing AUTOTEL_SAMPLING_TAIL_EVALUATED
+        [AUTOTEL_SAMPLING_TAIL_KEEP]: false,
       });
 
       tailSamplingProcessor.onEnd(span);
@@ -156,12 +160,12 @@ describe('TailSamplingSpanProcessor', () => {
     it('should handle mixed spans (some kept, some dropped)', () => {
       const keptSpan1 = createMockSpan({ foo: 'bar' });
       const droppedSpan = createMockSpan({
-        'sampling.tail.evaluated': true,
-        'sampling.tail.keep': false,
+        [AUTOTEL_SAMPLING_TAIL_EVALUATED]: true,
+        [AUTOTEL_SAMPLING_TAIL_KEEP]: false,
       });
       const keptSpan2 = createMockSpan({
-        'sampling.tail.evaluated': true,
-        'sampling.tail.keep': true,
+        [AUTOTEL_SAMPLING_TAIL_EVALUATED]: true,
+        [AUTOTEL_SAMPLING_TAIL_KEEP]: true,
       });
 
       tailSamplingProcessor.onEnd(keptSpan1);
@@ -196,20 +200,20 @@ describe('TailSamplingSpanProcessor', () => {
       // 3. Error request (keep)
 
       const fastSpan = createMockSpan({
-        'sampling.tail.evaluated': true,
-        'sampling.tail.keep': false, // Fast, no errors
+        [AUTOTEL_SAMPLING_TAIL_EVALUATED]: true,
+        [AUTOTEL_SAMPLING_TAIL_KEEP]: false, // Fast, no errors
         duration: 50,
       });
 
       const slowSpan = createMockSpan({
-        'sampling.tail.evaluated': true,
-        'sampling.tail.keep': true, // Slow request
+        [AUTOTEL_SAMPLING_TAIL_EVALUATED]: true,
+        [AUTOTEL_SAMPLING_TAIL_KEEP]: true, // Slow request
         duration: 1000,
       });
 
       const errorSpan = createMockSpan({
-        'sampling.tail.evaluated': true,
-        'sampling.tail.keep': true, // Had error
+        [AUTOTEL_SAMPLING_TAIL_EVALUATED]: true,
+        [AUTOTEL_SAMPLING_TAIL_KEEP]: true, // Had error
         error: true,
       });
 

package/src/tail-sampling-processor.ts

@@ -1,14 +1,14 @@
 /**
  * Tail Sampling Span Processor
  *
- * Filters spans based on the `sampling.tail.keep` attribute set during execution.
+ * Filters spans based on the `autotel.sampling.tail.keep` attribute set during execution.
  * This enables adaptive sampling where we decide whether to keep a span AFTER
  * the operation completes, based on criteria like errors, duration, etc.
  *
  * How it works:
  * 1. Decorator creates span optimistically (head sampling returns true)
  * 2. Operation executes and completes
- * 3. Decorator calls shouldKeepTrace() and sets sampling.tail.keep attribute
+ * 3. Decorator calls shouldKeepTrace() and sets autotel.sampling.tail.keep attribute
  * 4. This processor checks the attribute and drops spans marked as false
  */
 
@@ -18,6 +18,10 @@ import type {
 } from '@opentelemetry/sdk-trace-base';
 import type { Context } from '@opentelemetry/api';
 import type { Span } from '@opentelemetry/sdk-trace-base';
+import {
+  AUTOTEL_SAMPLING_TAIL_KEEP,
+  AUTOTEL_SAMPLING_TAIL_EVALUATED,
+} from './sampling';
 
 export class TailSamplingSpanProcessor implements SpanProcessor {
   private wrappedProcessor: SpanProcessor;
@@ -31,8 +35,8 @@ export class TailSamplingSpanProcessor implements SpanProcessor {
   }
 
   onEnd(span: ReadableSpan): void {
-    const tailEvaluated = span.attributes['sampling.tail.evaluated'];
-    const shouldKeep = span.attributes['sampling.tail.keep'];
+    const tailEvaluated = span.attributes[AUTOTEL_SAMPLING_TAIL_EVALUATED];
+    const shouldKeep = span.attributes[AUTOTEL_SAMPLING_TAIL_KEEP];
 
     if (tailEvaluated === true && shouldKeep === false) {
       return;

package/src/trace-context.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, it } from 'vitest';
+import { enterOrRun } from './trace-context';
+
+type Box<T> = { value: T };
+
+function createFakeStorage<T>(initialValue?: T) {
+  let currentStore =
+    initialValue === undefined ? undefined : { value: initialValue };
+  const runCalls: Array<Box<T>> = [];
+  const enterWithCalls: Array<Box<T>> = [];
+
+  const storage = {
+    getStore() {
+      return currentStore;
+    },
+    run(store: Box<T>, fn: () => void) {
+      runCalls.push(store);
+      const previousStore = currentStore;
+      currentStore = store;
+      try {
+        fn();
+      } finally {
+        currentStore = previousStore;
+      }
+    },
+    enterWith(store: Box<T>) {
+      enterWithCalls.push(store);
+      currentStore = store;
+    },
+  };
+
+  return {
+    enterWithCalls,
+    runCalls,
+    storage: storage as unknown as {
+      enterWith?: (store: Box<T>) => void;
+      getStore: () => Box<T> | undefined;
+      run: (store: Box<T>, fn: () => void) => void;
+    },
+  };
+}
+
+describe('enterOrRun', () => {
+  it('mutates the existing store when already inside a run scope', () => {
+    const { storage } = createFakeStorage('outer');
+
+    enterOrRun(storage as never, 'updated');
+
+    expect(storage.getStore()?.value).toBe('updated');
+  });
+
+  it('falls back to run() when enterWith throws', () => {
+    const { runCalls, storage } = createFakeStorage<string>();
+    storage.enterWith = () => {
+      throw new Error('enterWith not supported');
+    };
+
+    enterOrRun(storage as never, 'worker-value');
+
+    expect(runCalls).toHaveLength(1);
+    expect(runCalls[0]?.value).toBe('worker-value');
+  });
+
+  it('prefers enterWith() when no store exists and the runtime supports it', () => {
+    const { enterWithCalls, storage } = createFakeStorage<string>();
+
+    enterOrRun(storage as never, 'node-value');
+
+    expect(enterWithCalls).toHaveLength(1);
+    expect(enterWithCalls[0]?.value).toBe('node-value');
+    expect(storage.getStore()?.value).toBe('node-value');
+  });
+});