feat(sampler-composite): add experimental implementation of composite sampling spec

CHANGELOG.md

@@ -11,7 +11,7 @@ For notes on migrating to 2.x / 0.200.x see [the upgrade guide](doc/upgrade-to-2
 ## Unreleased
 
 * feat(instrumentation-http): Added support for redacting specific url query string values and url credentials in instrumentations [#5743](https://github.com/open-telemetry/opentelemetry-js/pull/5743) @rads-1996
-* feat(sampler-consistent): Added experimental implementations of draft consistent sampling spec [#5839](https://github.com/open-telemetry/opentelemetry-js/pull/5839) @anuraaga
+* feat(sampler-composite): Added experimental implementations of draft composite sampling spec [#5839](https://github.com/open-telemetry/opentelemetry-js/pull/5839) @anuraaga
 
 ### :boom: Breaking Changes
 

experimental/packages/sampler-composite/README.md

@@ -22,20 +22,20 @@ in exported spans to reconstruct population metrics.
 
 ```typescript
 import {
-  CompositeSampler,
-  ComposableAlwaysOffSampler,
-  ComposableAlwaysOnSampler,
-  ComposableParentThresholdSampler,
-  ComposableTraceIDRatioBasedSampler,
+  createCompositeSampler,
+  createComposableAlwaysOffSampler,
+  createComposableAlwaysOnSampler,
+  createComposableParentThresholdSampler,
+  createComposableTraceIDRatioBasedSampler,
 } from '@opentelemetry/sampler-composite';
 
 // never sample
-const sampler = new CompositeSampler(new ComposableAlwaysOffSampler());
+const sampler = createCompositeSampler(createComposableAlwaysOffSampler());
 // always sample
-const sampler = new CompositeSampler(new ComposableAlwaysOnSampler());
+const sampler = createCompositeSampler(createComposableAlwaysOnSampler());
 // follow the parent, or otherwise sample with a probability if root
-const sampler = new CompositeSampler(
-    new ComposableParentThresholdSampler(new ComposableTraceIDRatioBasedSampler(0.3)));
+const sampler = createCompositeSampler(
+    createComposableParentThresholdSampler(createComposableTraceIDRatioBasedSampler(0.3)));
 ```
 
 ## Useful links

experimental/packages/sampler-composite/package.json

@@ -21,7 +21,7 @@
     "lint:fix": "eslint . --ext .ts --fix",
     "version": "node ../../../scripts/version-update.js",
     "watch": "tsc --build --watch",
-    "precompile": "cross-var lerna run version --scope $npm_package_name --include-dependencies",
+    "precompile": "lerna run version --scope @opentelemetry/sampler-composite --include-dependencies",
     "prewatch": "npm run precompile",
     "peer-api-check": "node ../../../scripts/peer-api-check.js",
     "align-api-deps": "node ../../../scripts/align-api-deps.js"
@@ -57,10 +57,8 @@
     "@opentelemetry/api": "1.9.0",
     "@types/mocha": "10.0.10",
     "@types/node": "18.6.5",
-    "cross-var": "1.1.0",
     "lerna": "6.6.2",
     "mocha": "11.1.0",
-    "nock": "13.5.6",
     "nyc": "17.1.0"
   },
   "dependencies": {

experimental/packages/sampler-composite/src/alwaysoff.ts

@@ -36,6 +36,6 @@ const _sampler = new ComposableAlwaysOffSampler();
 /**
  * Returns a composable sampler that does not sample any span.
  */
-export function composable_always_off_sampler(): ComposableSampler {
+export function createComposableAlwaysOffSampler(): ComposableSampler {
   return _sampler;
 }

experimental/packages/sampler-composite/src/alwayson.ts

@@ -36,6 +36,6 @@ const _sampler = new ComposableAlwaysOnSampler();
 /**
  * Returns a composable sampler that samples all span.
  */
-export function composable_always_on_sampler(): ComposableSampler {
+export function createComposableAlwaysOnSampler(): ComposableSampler {
   return _sampler;
 }

experimental/packages/sampler-composite/src/composite.ts

@@ -49,7 +49,7 @@ class CompositeSampler implements Sampler {
     const spanContext = trace.getSpanContext(context);
 
     const traceState = spanContext?.traceState;
-    const otTraceState = parseOtelTraceState(traceState);
+    let otTraceState = parseOtelTraceState(traceState);
 
     const intent = this.delegate.getSamplingIntent(
       context,
@@ -78,9 +78,15 @@ class CompositeSampler implements Sampler {
       ? SamplingDecision.RECORD_AND_SAMPLED
       : SamplingDecision.NOT_RECORD;
     if (sampled && adjustedCountCorrect) {
-      otTraceState.threshold = intent.threshold;
+      otTraceState = {
+        ...otTraceState,
+        threshold: intent.threshold,
+      };
     } else {
-      otTraceState.threshold = INVALID_THRESHOLD;
+      otTraceState = {
+        ...otTraceState,
+        threshold: INVALID_THRESHOLD,
+      };
     }
 
     const otts = serializeTraceState(otTraceState);
@@ -105,12 +111,16 @@ class CompositeSampler implements Sampler {
       traceState: newTraceState,
     };
   }
+
+  toString(): string {
+    return this.delegate.toString();
+  }
 }
 
 /**
  * Returns a composite sampler that uses a composable sampler to make its
  * sampling decisions while handling tracestate.
  */
-export function composite_sampler(delegate: ComposableSampler): Sampler {
+export function createCompositeSampler(delegate: ComposableSampler): Sampler {
   return new CompositeSampler(delegate);
 }

experimental/packages/sampler-composite/src/index.ts

@@ -14,9 +14,9 @@
  * limitations under the License.
  */
 
-export { composable_always_off_sampler } from './alwaysoff';
-export { composable_always_on_sampler } from './alwayson';
-export { composable_trace_id_ratio_based_sampler } from './traceidratio';
-export { composable_parent_threshold_sampler } from './parentthreshold';
-export { composite_sampler } from './composite';
+export { createComposableAlwaysOffSampler } from './alwaysoff';
+export { createComposableAlwaysOnSampler } from './alwayson';
+export { createComposableTraceIDRatioBasedSampler } from './traceidratio';
+export { createComposableParentThresholdSampler } from './parentthreshold';
+export { createCompositeSampler } from './composite';
 export type { ComposableSampler, SamplingIntent } from './types';

experimental/packages/sampler-composite/src/parentthreshold.ts

@@ -31,7 +31,7 @@ class ComposableParentThresholdSampler implements ComposableSampler {
   private readonly description: string;
 
   constructor(private readonly rootSampler: ComposableSampler) {
-    this.description = `ComposableParentThresholdSampler(root_sampler=${rootSampler})`;
+    this.description = `ComposableParentThresholdSampler(rootSampler=${rootSampler})`;
   }
 
   getSamplingIntent(
@@ -82,7 +82,7 @@ class ComposableParentThresholdSampler implements ComposableSampler {
  * Returns a composable sampler that respects the sampling decision of the
  * parent span or falls back to the given sampler if it is a root span.
  */
-export function composable_parent_threshold_sampler(
+export function createComposableParentThresholdSampler(
   rootSampler: ComposableSampler
 ): ComposableSampler {
   return new ComposableParentThresholdSampler(rootSampler);

experimental/packages/sampler-composite/src/traceidratio.ts

@@ -37,7 +37,9 @@ class ComposableTraceIDRatioBasedSampler implements ComposableSampler {
         thresholdReliable: true,
       };
     } else {
-      // Same as AlwaysOff, notably the threshold is not considered reliable
+      // Same as AlwaysOff, notably the threshold is not considered reliable. The spec mentions
+      // returning an instance of ComposableAlwaysOffSampler in this case but it seems clearer
+      // if the description of the sampler matches the user's request.
       this.intent = {
         threshold: INVALID_THRESHOLD,
         thresholdReliable: false,
@@ -58,7 +60,7 @@ class ComposableTraceIDRatioBasedSampler implements ComposableSampler {
 /**
  * Returns a composable sampler that samples each span with a fixed ratio.
  */
-export function composable_trace_id_ratio_based_sampler(
+export function createComposableTraceIDRatioBasedSampler(
   ratio: number
 ): ComposableSampler {
   return new ComposableTraceIDRatioBasedSampler(ratio);

experimental/packages/sampler-composite/src/tracestate.ts

@@ -32,12 +32,10 @@ export type OtelTraceState = {
   rest?: string[];
 };
 
-export function invalidTraceState(): OtelTraceState {
-  return {
-    randomValue: INVALID_RANDOM_VALUE,
-    threshold: INVALID_THRESHOLD,
-  };
-}
+export const INVALID_TRACE_STATE: OtelTraceState = {
+  randomValue: INVALID_RANDOM_VALUE,
+  threshold: INVALID_THRESHOLD,
+};
 
 const TRACE_STATE_SIZE_LIMIT = 256;
 const MAX_VALUE_LENGTH = 14; // 56 bits, 4 bits per hex digit
@@ -47,12 +45,13 @@ export function parseOtelTraceState(
 ): OtelTraceState {
   const ot = traceState?.get('ot');
   if (!ot || ot.length > TRACE_STATE_SIZE_LIMIT) {
-    return invalidTraceState();
+    return INVALID_TRACE_STATE;
   }
 
   let threshold = INVALID_THRESHOLD;
   let randomValue = INVALID_RANDOM_VALUE;
 
+  // Parse based on https://opentelemetry.io/docs/specs/otel/trace/tracestate-handling/
   const members = ot.split(';');
   let rest: string[] | undefined;
   for (const member of members) {
@@ -115,15 +114,11 @@ function parseTh(value: string, defaultValue: bigint): bigint {
     return defaultValue;
   }
 
-  let parsed: bigint;
   try {
-    parsed = BigInt(`0x${value}`);
+    return BigInt('0x' + value.padEnd(MAX_VALUE_LENGTH, '0'));
   } catch {
     return defaultValue;
   }
-
-  const trailingZeros = MAX_VALUE_LENGTH - value.length;
-  return parsed << BigInt(trailingZeros * 4);
 }
 
 function parseRv(value: string, defaultValue: bigint): bigint {

experimental/packages/sampler-composite/test/alwaysoff.test.ts

@@ -19,11 +19,14 @@ import * as assert from 'assert';
 import { context, SpanKind } from '@opentelemetry/api';
 import { SamplingDecision } from '@opentelemetry/sdk-trace-base';
 
-import { composite_sampler, composable_always_off_sampler } from '../src';
+import {
+  createCompositeSampler,
+  createComposableAlwaysOffSampler,
+} from '../src';
 import { traceIdGenerator } from './util';
 
 describe('ComposableAlwaysOffSampler', () => {
-  const composableSampler = composable_always_off_sampler();
+  const composableSampler = createComposableAlwaysOffSampler();
 
   it('should have a description', () => {
     assert.strictEqual(
@@ -47,7 +50,7 @@ describe('ComposableAlwaysOffSampler', () => {
   });
 
   it('should never sample', () => {
-    const sampler = composite_sampler(composableSampler);
+    const sampler = createCompositeSampler(composableSampler);
     const generator = traceIdGenerator();
     let numSampled = 0;
     for (let i = 0; i < 10000; i++) {

experimental/packages/sampler-composite/test/alwayson.test.ts

@@ -19,11 +19,14 @@ import * as assert from 'assert';
 import { context, SpanKind } from '@opentelemetry/api';
 import { SamplingDecision } from '@opentelemetry/sdk-trace-base';
 
-import { composite_sampler, composable_always_on_sampler } from '../src';
+import {
+  createCompositeSampler,
+  createComposableAlwaysOnSampler,
+} from '../src';
 import { traceIdGenerator } from './util';
 
 describe('ComposableAlwaysOnSampler', () => {
-  const composableSampler = composable_always_on_sampler();
+  const composableSampler = createComposableAlwaysOnSampler();
 
   it('should have a description', () => {
     assert.strictEqual(
@@ -47,7 +50,7 @@ describe('ComposableAlwaysOnSampler', () => {
   });
 
   it('should always sample', () => {
-    const sampler = composite_sampler(composableSampler);
+    const sampler = createCompositeSampler(composableSampler);
     const generator = traceIdGenerator();
     let numSampled = 0;
     for (let i = 0; i < 10000; i++) {