autotel 2.25.2 → 2.25.3

package/src/env-config.ts

@@ -1,12 +1,22 @@
 /**
  * Standard OpenTelemetry environment variables
  */
+import type { Sampler as OtelSampler } from '@opentelemetry/sdk-trace-base';
+import {
+  AlwaysOffSampler,
+  AlwaysOnSampler,
+  ParentBasedSampler,
+  TraceIdRatioBasedSampler,
+} from '@opentelemetry/sdk-trace-base';
+
 export interface OtelEnvVars {
   OTEL_SERVICE_NAME?: string;
   OTEL_EXPORTER_OTLP_ENDPOINT?: string;
   OTEL_EXPORTER_OTLP_HEADERS?: string;
   OTEL_RESOURCE_ATTRIBUTES?: string;
   OTEL_EXPORTER_OTLP_PROTOCOL?: 'http' | 'grpc';
+  OTEL_TRACES_SAMPLER?: string;
+  OTEL_TRACES_SAMPLER_ARG?: string;
 }
 
 /**
@@ -33,6 +43,7 @@ export interface EnvConfig {
   protocol?: 'http' | 'grpc';
   headers?: Record<string, string>;
   resourceAttributes?: Record<string, string>;
+  otelSampler?: OtelSampler;
 }
 
 /**
@@ -93,9 +104,99 @@ export function resolveOtelEnv(): OtelEnvVars {
     }
   }
 
+  if (process.env.OTEL_TRACES_SAMPLER) {
+    const value = process.env.OTEL_TRACES_SAMPLER.trim();
+    if (value) {
+      env.OTEL_TRACES_SAMPLER = value;
+    }
+  }
+
+  if (process.env.OTEL_TRACES_SAMPLER_ARG) {
+    const value = process.env.OTEL_TRACES_SAMPLER_ARG.trim();
+    if (value) {
+      env.OTEL_TRACES_SAMPLER_ARG = value;
+    }
+  }
+
   return env;
 }
 
+function parseRatioSamplerArg(
+  samplerName: string,
+  samplerArg: string | undefined,
+): number {
+  if (samplerArg === undefined) {
+    return 1.0;
+  }
+
+  const ratio = Number(samplerArg);
+  if (!Number.isFinite(ratio) || ratio < 0 || ratio > 1) {
+    console.error(
+      `[autotel] Invalid OTEL_TRACES_SAMPLER_ARG="${samplerArg}" for ${samplerName}. Expected a number in [0..1]. Falling back to 1.0.`,
+    );
+    return 1.0;
+  }
+
+  return ratio;
+}
+
+function warnOnUnusedSamplerArg(
+  samplerName: string,
+  samplerArg: string | undefined,
+): void {
+  if (samplerArg !== undefined) {
+    console.error(
+      `[autotel] OTEL_TRACES_SAMPLER_ARG is not used by OTEL_TRACES_SAMPLER="${samplerName}". Ignoring value "${samplerArg}".`,
+    );
+  }
+}
+
+export function createSamplerFromEnv(
+  env: Pick<OtelEnvVars, 'OTEL_TRACES_SAMPLER' | 'OTEL_TRACES_SAMPLER_ARG'>,
+): OtelSampler | undefined {
+  const samplerName = env.OTEL_TRACES_SAMPLER;
+  if (!samplerName) {
+    return undefined;
+  }
+
+  switch (samplerName) {
+    case 'always_on':
+      warnOnUnusedSamplerArg(samplerName, env.OTEL_TRACES_SAMPLER_ARG);
+      return new AlwaysOnSampler();
+    case 'always_off':
+      warnOnUnusedSamplerArg(samplerName, env.OTEL_TRACES_SAMPLER_ARG);
+      return new AlwaysOffSampler();
+    case 'traceidratio':
+      return new TraceIdRatioBasedSampler(
+        parseRatioSamplerArg(samplerName, env.OTEL_TRACES_SAMPLER_ARG),
+      );
+    case 'parentbased_always_on':
+      warnOnUnusedSamplerArg(samplerName, env.OTEL_TRACES_SAMPLER_ARG);
+      return new ParentBasedSampler({ root: new AlwaysOnSampler() });
+    case 'parentbased_always_off':
+      warnOnUnusedSamplerArg(samplerName, env.OTEL_TRACES_SAMPLER_ARG);
+      return new ParentBasedSampler({ root: new AlwaysOffSampler() });
+    case 'parentbased_traceidratio':
+      return new ParentBasedSampler({
+        root: new TraceIdRatioBasedSampler(
+          parseRatioSamplerArg(samplerName, env.OTEL_TRACES_SAMPLER_ARG),
+        ),
+      });
+    case 'jaeger_remote':
+    case 'parentbased_jaeger_remote':
+    case 'xray':
+      console.error(
+        `[autotel] OTEL_TRACES_SAMPLER="${samplerName}" is not supported yet by autotel. Falling back to the next sampler source.`,
+      );
+      return undefined;
+    default:
+      console.error(
+        `[autotel] Unknown OTEL_TRACES_SAMPLER="${samplerName}". Falling back to the next sampler source.`,
+      );
+      return undefined;
+  }
+}
+
 /**
  * Parse OTEL_RESOURCE_ATTRIBUTES from comma-separated key=value pairs
  * Example: "service.version=1.0.0,deployment.environment=production"
@@ -191,6 +292,11 @@ export function envToConfig(env: OtelEnvVars): EnvConfig {
     config.resourceAttributes = resourceAttrs;
   }
 
+  const sampler = createSamplerFromEnv(env);
+  if (sampler) {
+    config.otelSampler = sampler;
+  }
+
   return config;
 }
 

package/src/functional.ts

@@ -42,7 +42,13 @@ import {
 } from '@opentelemetry/api';
 import { getConfig } from './config';
 import { getConfig as getInitConfig, getSdk } from './init';
-import { type Sampler, type SamplingContext, AlwaysSampler } from './sampling';
+import {
+  type Sampler,
+  type SamplingContext,
+  AlwaysSampler,
+  AUTOTEL_SAMPLING_TAIL_KEEP,
+  AUTOTEL_SAMPLING_TAIL_EVALUATED,
+} from './sampling';
 import { getEventQueue } from './track';
 import type { TraceContext } from './trace-context';
 import {
@@ -797,8 +803,8 @@ function wrapWithTracing<TArgs extends unknown[], TReturn>(
               duration,
               error,
             });
-            span.setAttribute('sampling.tail.keep', shouldKeepSpan);
-            span.setAttribute('sampling.tail.evaluated', true);
+            span.setAttribute(AUTOTEL_SAMPLING_TAIL_KEEP, shouldKeepSpan);
+            span.setAttribute(AUTOTEL_SAMPLING_TAIL_EVALUATED, true);
           }
         };
 
@@ -1104,8 +1110,8 @@ function wrapWithTracingSync<TArgs extends unknown[], TReturn>(
               duration,
               error,
             });
-            span.setAttribute('sampling.tail.keep', shouldKeepSpan);
-            span.setAttribute('sampling.tail.evaluated', true);
+            span.setAttribute(AUTOTEL_SAMPLING_TAIL_KEEP, shouldKeepSpan);
+            span.setAttribute(AUTOTEL_SAMPLING_TAIL_EVALUATED, true);
           }
         };
 
@@ -1352,8 +1358,8 @@ function executeImmediately<TReturn = unknown>(
             duration,
             error,
           });
-          span.setAttribute('sampling.tail.keep', shouldKeepSpan);
-          span.setAttribute('sampling.tail.evaluated', true);
+          span.setAttribute(AUTOTEL_SAMPLING_TAIL_KEEP, shouldKeepSpan);
+          span.setAttribute(AUTOTEL_SAMPLING_TAIL_EVALUATED, true);
         }
       };
 

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
 // ============================================================================