autotel 2.25.2 → 2.25.4

package/src/env-config.test.ts

@@ -1,8 +1,15 @@
 import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import {
+  AlwaysOffSampler,
+  AlwaysOnSampler,
+  ParentBasedSampler,
+  TraceIdRatioBasedSampler,
+} from '@opentelemetry/sdk-trace-base';
 import {
   resolveOtelEnv,
   parseResourceAttributes,
   parseOtlpHeaders,
+  createSamplerFromEnv,
   envToConfig,
   resolveConfigFromEnv,
 } from './env-config';
@@ -45,6 +52,16 @@ describe('env-config', () => {
       const env = resolveOtelEnv();
       expect(env.OTEL_EXPORTER_OTLP_PROTOCOL).toBe('grpc');
     });
+
+    it('should resolve trace sampler env vars', () => {
+      process.env.OTEL_TRACES_SAMPLER = 'traceidratio';
+      process.env.OTEL_TRACES_SAMPLER_ARG = '0.5';
+
+      const env = resolveOtelEnv();
+
+      expect(env.OTEL_TRACES_SAMPLER).toBe('traceidratio');
+      expect(env.OTEL_TRACES_SAMPLER_ARG).toBe('0.5');
+    });
   });
 
   describe('parseResourceAttributes', () => {
@@ -198,6 +215,58 @@ describe('env-config', () => {
       const config = envToConfig({});
       expect(config).toEqual({});
     });
+
+    it('should map OTEL_TRACES_SAMPLER to an SDK sampler', () => {
+      const config = envToConfig({
+        OTEL_TRACES_SAMPLER: 'always_on',
+      });
+
+      expect(config.otelSampler).toBeInstanceOf(AlwaysOnSampler);
+    });
+  });
+
+  describe('createSamplerFromEnv', () => {
+    it('supports always_on', () => {
+      const sampler = createSamplerFromEnv({
+        OTEL_TRACES_SAMPLER: 'always_on',
+      });
+
+      expect(sampler).toBeInstanceOf(AlwaysOnSampler);
+    });
+
+    it('supports always_off', () => {
+      const sampler = createSamplerFromEnv({
+        OTEL_TRACES_SAMPLER: 'always_off',
+      });
+
+      expect(sampler).toBeInstanceOf(AlwaysOffSampler);
+    });
+
+    it('supports traceidratio', () => {
+      const sampler = createSamplerFromEnv({
+        OTEL_TRACES_SAMPLER: 'traceidratio',
+        OTEL_TRACES_SAMPLER_ARG: '0.25',
+      });
+
+      expect(sampler).toBeInstanceOf(TraceIdRatioBasedSampler);
+    });
+
+    it('supports parentbased_traceidratio', () => {
+      const sampler = createSamplerFromEnv({
+        OTEL_TRACES_SAMPLER: 'parentbased_traceidratio',
+        OTEL_TRACES_SAMPLER_ARG: '0.25',
+      });
+
+      expect(sampler).toBeInstanceOf(ParentBasedSampler);
+    });
+
+    it('returns undefined for unsupported remote samplers', () => {
+      const sampler = createSamplerFromEnv({
+        OTEL_TRACES_SAMPLER: 'jaeger_remote',
+      });
+
+      expect(sampler).toBeUndefined();
+    });
   });
 
   describe('resolveConfigFromEnv', () => {
@@ -242,5 +311,13 @@ describe('env-config', () => {
         },
       });
     });
+
+    it('should include otelSampler when OTEL_TRACES_SAMPLER is set', () => {
+      process.env.OTEL_TRACES_SAMPLER = 'parentbased_always_off';
+
+      const config = resolveConfigFromEnv();
+
+      expect(config.otelSampler).toBeInstanceOf(ParentBasedSampler);
+    });
   });
 });

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;
 }