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

experimental/CHANGELOG.md

@@ -10,6 +10,8 @@ For notes on migrating to 2.x / 0.200.x see [the upgrade guide](doc/upgrade-to-2
 
 ### :rocket: Features
 
+* feat(sampler-composite): Added experimental implementations of draft composite sampling spec [#5839](https://github.com/open-telemetry/opentelemetry-js/pull/5839) @anuraaga
+
 ### :bug: Bug Fixes
 
 * fix(instrumentation-http): respect requireParent flag when INVALID_SPAN_CONTEXT is used [#4788](https://github.com/open-telemetry/opentelemetry-js/pull/4788) @reberhardt7

experimental/packages/sampler-composite/.eslintignore

@@ -0,0 +1 @@
+build

experimental/packages/sampler-composite/.eslintrc.js

@@ -0,0 +1,8 @@
+module.exports = {
+    "env": {
+        "mocha": true,
+        "commonjs": true,
+        "shared-node-browser": true
+    },
+    ...require('../../../eslint.base.js')
+}

experimental/packages/sampler-composite/README.md

@@ -0,0 +1,57 @@
+# OpenTelemetry Composite Sampling
+
+[![NPM Published Version][npm-img]][npm-url]
+[![Apache License][license-image]][license-image]
+
+**Note: This is an experimental package under active development. New releases may include breaking changes.**
+
+This package provides implementations of composite samplers that propagate sampling information across a trace.
+This implements the [experimental specification][probability-sampling].
+
+Currently `ComposableRuleBased` and `ComposableAnnotating` are not implemented.
+
+## Quick Start
+
+To get started you will need to install a compatible OpenTelemetry SDK.
+
+### Samplers
+
+This module exports samplers that follow the general behavior of the standard SDK samplers, but ensuring
+it is consistent across a trace by using the tracestate header. Notably, the tracestate can be examined
+in exported spans to reconstruct population metrics.
+
+```typescript
+import {
+  createCompositeSampler,
+  createComposableAlwaysOffSampler,
+  createComposableAlwaysOnSampler,
+  createComposableParentThresholdSampler,
+  createComposableTraceIDRatioBasedSampler,
+} from '@opentelemetry/sampler-composite';
+
+// never sample
+const sampler = createCompositeSampler(createComposableAlwaysOffSampler());
+// always sample
+const sampler = createCompositeSampler(createComposableAlwaysOnSampler());
+// follow the parent, or otherwise sample with a probability if root
+const sampler = createCompositeSampler(
+    createComposableParentThresholdSampler(createComposableTraceIDRatioBasedSampler(0.3)));
+```
+
+## Useful links
+
+- For more information on OpenTelemetry, visit: <https://opentelemetry.io/>
+- For more about OpenTelemetry JavaScript: <https://github.com/open-telemetry/opentelemetry-js>
+- For help or feedback on this project, join us in [GitHub Discussions][discussions-url]
+
+## License
+
+Apache 2.0 - See [LICENSE][license-url] for more information.
+
+[discussions-url]: https://github.com/open-telemetry/opentelemetry-js/discussions
+[license-url]: https://github.com/open-telemetry/opentelemetry-js/blob/main/LICENSE
+[license-image]: https://img.shields.io/badge/license-Apache_2.0-green.svg?style=flat
+[npm-url]: https://www.npmjs.com/package/@opentelemetry/sampler-composite
+[npm-img]: https://badge.fury.io/js/%40opentelemetry%sampler-composite.svg
+
+[probability-sampling]: https://opentelemetry.io/docs/specs/otel/trace/tracestate-probability-sampling/

experimental/packages/sampler-composite/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@opentelemetry/sampler-composite",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "0.205.0",
+  "description": "Composite samplers for OpenTelemetry tracing",
+  "module": "build/esm/index.js",
+  "esnext": "build/esnext/index.js",
+  "types": "build/src/index.d.ts",
+  "main": "build/src/index.js",
+  "repository": "open-telemetry/opentelemetry-js",
+  "scripts": {
+    "prepublishOnly": "npm run compile",
+    "compile": "tsc --build",
+    "clean": "tsc --build --clean",
+    "test": "nyc mocha 'test/**/*.test.ts'",
+    "tdd": "npm run test -- --watch-extensions ts --watch",
+    "lint": "eslint . --ext .ts",
+    "lint:fix": "eslint . --ext .ts --fix",
+    "version": "node ../../../scripts/version-update.js",
+    "watch": "tsc --build --watch",
+    "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"
+  },
+  "keywords": [
+    "opentelemetry",
+    "nodejs",
+    "sampling",
+    "tracing"
+  ],
+  "author": "OpenTelemetry Authors",
+  "license": "Apache-2.0",
+  "engines": {
+    "node": "^18.19.0 || >=20.6.0"
+  },
+  "files": [
+    "build/esm/**/*.js",
+    "build/esm/**/*.js.map",
+    "build/esm/**/*.d.ts",
+    "build/esnext/**/*.js",
+    "build/esnext/**/*.js.map",
+    "build/esnext/**/*.d.ts",
+    "build/src/**/*.js",
+    "build/src/**/*.js.map",
+    "build/src/**/*.d.ts",
+    "LICENSE",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "@opentelemetry/api": "^1.3.0"
+  },
+  "devDependencies": {
+    "@opentelemetry/api": "1.9.0",
+    "@types/mocha": "10.0.10",
+    "@types/node": "18.6.5",
+    "lerna": "6.6.2",
+    "mocha": "11.1.0",
+    "nyc": "17.1.0"
+  },
+  "dependencies": {
+    "@opentelemetry/core": "2.0.1",
+    "@opentelemetry/sdk-trace-base": "2.0.1"
+  },
+  "homepage": "https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/sampler-composite",
+  "sideEffects": false
+}

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

@@ -0,0 +1,41 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { ComposableSampler, SamplingIntent } from './types';
+import { INVALID_THRESHOLD } from './util';
+
+const intent: SamplingIntent = {
+  threshold: INVALID_THRESHOLD,
+  thresholdReliable: false,
+};
+
+class ComposableAlwaysOffSampler implements ComposableSampler {
+  getSamplingIntent(): SamplingIntent {
+    return intent;
+  }
+
+  toString(): string {
+    return 'ComposableAlwaysOffSampler';
+  }
+}
+
+const _sampler = new ComposableAlwaysOffSampler();
+
+/**
+ * Returns a composable sampler that does not sample any span.
+ */
+export function createComposableAlwaysOffSampler(): ComposableSampler {
+  return _sampler;
+}

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

@@ -0,0 +1,41 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { ComposableSampler, SamplingIntent } from './types';
+import { MIN_THRESHOLD } from './util';
+
+const intent: SamplingIntent = {
+  threshold: MIN_THRESHOLD,
+  thresholdReliable: true,
+};
+
+class ComposableAlwaysOnSampler implements ComposableSampler {
+  getSamplingIntent(): SamplingIntent {
+    return intent;
+  }
+
+  toString(): string {
+    return 'ComposableAlwaysOnSampler';
+  }
+}
+
+const _sampler = new ComposableAlwaysOnSampler();
+
+/**
+ * Returns a composable sampler that samples all span.
+ */
+export function createComposableAlwaysOnSampler(): ComposableSampler {
+  return _sampler;
+}

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

@@ -0,0 +1,126 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import {
+  Context,
+  SpanKind,
+  Attributes,
+  Link,
+  TraceState,
+  trace,
+} from '@opentelemetry/api';
+import { TraceState as CoreTraceState } from '@opentelemetry/core';
+import {
+  Sampler,
+  SamplingDecision,
+  SamplingResult,
+} from '@opentelemetry/sdk-trace-base';
+import { ComposableSampler } from './types';
+import { parseOtelTraceState, serializeTraceState } from './tracestate';
+import {
+  INVALID_THRESHOLD,
+  isValidRandomValue,
+  isValidThreshold,
+} from './util';
+
+class CompositeSampler implements Sampler {
+  constructor(private readonly delegate: ComposableSampler) {}
+
+  shouldSample(
+    context: Context,
+    traceId: string,
+    spanName: string,
+    spanKind: SpanKind,
+    attributes: Attributes,
+    links: Link[]
+  ): SamplingResult {
+    const spanContext = trace.getSpanContext(context);
+
+    const traceState = spanContext?.traceState;
+    let otTraceState = parseOtelTraceState(traceState);
+
+    const intent = this.delegate.getSamplingIntent(
+      context,
+      traceId,
+      spanName,
+      spanKind,
+      attributes,
+      links
+    );
+
+    let adjustedCountCorrect = false;
+    let sampled = false;
+    if (isValidThreshold(intent.threshold)) {
+      adjustedCountCorrect = intent.thresholdReliable;
+      let randomness: bigint;
+      if (isValidRandomValue(otTraceState.randomValue)) {
+        randomness = otTraceState.randomValue;
+      } else {
+        // Use last 56 bits of trace_id as randomness.
+        randomness = BigInt(`0x${traceId.slice(-14)}`);
+      }
+      sampled = intent.threshold <= randomness;
+    }
+
+    const decision = sampled
+      ? SamplingDecision.RECORD_AND_SAMPLED
+      : SamplingDecision.NOT_RECORD;
+    if (sampled && adjustedCountCorrect) {
+      otTraceState = {
+        ...otTraceState,
+        threshold: intent.threshold,
+      };
+    } else {
+      otTraceState = {
+        ...otTraceState,
+        threshold: INVALID_THRESHOLD,
+      };
+    }
+
+    const otts = serializeTraceState(otTraceState);
+
+    let newTraceState: TraceState | undefined;
+    if (traceState) {
+      newTraceState = traceState;
+      if (intent.updateTraceState) {
+        newTraceState = intent.updateTraceState(newTraceState);
+      }
+    }
+    if (otts) {
+      if (!newTraceState) {
+        newTraceState = new CoreTraceState();
+      }
+      newTraceState = newTraceState.set('ot', otts);
+    }
+
+    return {
+      decision,
+      attributes: intent.attributes,
+      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 createCompositeSampler(delegate: ComposableSampler): Sampler {
+  return new CompositeSampler(delegate);
+}

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

@@ -0,0 +1,22 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+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';