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

CHANGELOG.md

@@ -11,6 +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
 
 ### :boom: Breaking Changes
 

experimental/packages/sampler-composite/.eslintignore

@@ -0,0 +1,2 @@
+build
+src/generated

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,63 @@
+# 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` an `ComposableAnnotating` are not implemented.
+
+## Quick Start
+
+To get started you will need to install a compatible OpenTelemetry SDK.
+
+### Install Peer Dependencies
+
+```sh
+npm install @opentelemetry/sdk-trace-node # Or web
+```
+
+### 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 {
+  CompositeSampler,
+  ComposableAlwaysOffSampler,
+  ComposableAlwaysOnSampler,
+  ComposableParentThresholdSampler,
+  ComposableTraceIDRatioBasedSampler,
+} from '@opentelemetry/sampler-composite';
+
+// never sample
+const sampler = new CompositeSampler(new ComposableAlwaysOffSampler());
+// always sample
+const sampler = new CompositeSampler(new ComposableAlwaysOnSampler());
+// follow the parent, or otherwise sample with a probability if root
+const sampler = new CompositeSampler(
+    new ComposableParentThresholdSampler(new ComposableTraceIDRatioBasedSampler(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/karma.conf.js

@@ -0,0 +1,24 @@
+/*!
+ * 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
+ *
+ *      http://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.
+ */
+
+const karmaWebpackConfig = require('../../../karma.webpack');
+const karmaBaseConfig = require('../../../karma.base');
+
+module.exports = (config) => {
+  config.set(Object.assign({}, karmaBaseConfig, {
+    webpack: karmaWebpackConfig
+  }))
+};

experimental/packages/sampler-composite/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@opentelemetry/sampler-composite",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "0.203.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": "cross-var lerna run version --scope $npm_package_name --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",
+    "@types/request-promise-native": "1.0.21",
+    "@types/sinon": "17.0.4",
+    "@types/superagent": "8.1.9",
+    "axios": "1.8.4",
+    "cross-var": "1.1.0",
+    "lerna": "6.6.2",
+    "mocha": "11.1.0",
+    "nock": "13.5.6",
+    "nyc": "17.1.0",
+    "sinon": "18.0.1",
+    "superagent": "10.1.1",
+    "typescript": "5.0.4"
+  },
+  "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/otlp-transformer",
+  "sideEffects": false
+}

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

@@ -0,0 +1,35 @@
+/*
+ * 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,
+};
+
+/**
+ * A composable sampler that does not sample any span.
+ */
+export class ComposableAlwaysOffSampler implements ComposableSampler {
+  getSamplingIntent(): SamplingIntent {
+    return intent;
+  }
+
+  toString(): string {
+    return 'ComposableAlwaysOffSampler';
+  }
+}

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

@@ -0,0 +1,35 @@
+/*
+ * 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,
+};
+
+/**
+ * A composable sampler that samples all span.
+ */
+export class ComposableAlwaysOnSampler implements ComposableSampler {
+  getSamplingIntent(): SamplingIntent {
+    return intent;
+  }
+
+  toString(): string {
+    return 'ComposableAlwaysOnSampler';
+  }
+}

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

@@ -0,0 +1,108 @@
+/*
+ * 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,
+} from '@opentelemetry/api';
+import { TraceState as CoreTraceState } from '@opentelemetry/core';
+import {
+  Sampler,
+  SamplingDecision,
+  SamplingResult,
+} from '@opentelemetry/sdk-trace-base';
+import { ComposableSampler } from './types';
+import { getSpanContext } from '../../../../api/src/trace/context-utils';
+import { parseOtelTraceState, serializeTraceState } from './tracestate';
+import {
+  INVALID_THRESHOLD,
+  isValidRandomValue,
+  isValidThreshold,
+} from './util';
+
+export 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 = getSpanContext(context);
+
+    const traceState = spanContext?.traceState;
+    const 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.threshold = intent.threshold;
+    } else {
+      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,
+    };
+  }
+}

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 { ComposableAlwaysOffSampler } from './alwaysoff';
+export { ComposableAlwaysOnSampler } from './alwayson';
+export { ComposableTraceIDRatioBasedSampler } from './traceidratio';
+export { ComposableParentThresholdSampler } from './parentthreshold';
+export { CompositeSampler } from './composite';
+export type { ComposableSampler, SamplingIntent } from './types';