feat(trace): use dynamic composite ratio sampler

packages/opentelemetry-node/lib/central-config.js

@@ -420,6 +420,35 @@ const REMOTE_CONFIG_HANDLERS = [
             return null;
         },
     },
+
+    {
+        keys: ['sampling_rate'],
+        setter: (config, sdkInfo) => {
+            const rawRate = config['sampling_rate'];
+            let valRate;
+            switch (typeof rawRate) {
+                case 'undefined':
+                    valRate = 1.0;
+                    break;
+                case 'number':
+                    valRate = rawRate;
+                    break;
+                case 'string':
+                    valRate = Number(rawRate);
+                    if (isNaN(valRate)) {
+                        return `unknown 'sampling_rate' value: "${rawRate}"`;
+                    }
+                    break;
+                default:
+                    return `unknown 'sampling_rate' value type: ${typeof rawRate} (${rawRate})`;
+            }
+
+            sdkInfo.sampler.setRatio(valRate);
+            log.info(`central-config: set "sampling_rate" to "${valRate}"`);
+
+            return null;
+        },
+    },
 ];
 
 /**

packages/opentelemetry-node/lib/sampler.js

@@ -0,0 +1,88 @@
+/*
+ * Copyright Elasticsearch B.V. and contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+const {
+    createCompositeSampler,
+    createComposableParentThresholdSampler,
+    createComposableTraceIDRatioBasedSampler,
+} = require('@opentelemetry/sampler-composite');
+
+/**
+ * @typedef {import('@opentelemetry/api').Attributes} Attributes
+ * @typedef {import('@opentelemetry/api').Context} Context
+ * @typedef {import('@opentelemetry/api').Link} Link
+ * @typedef {import('@opentelemetry/api').SpanKind} SpanKind
+ * @typedef {import('@opentelemetry/sdk-trace-base').Sampler} Sampler
+ * @typedef {import('@opentelemetry/sdk-trace-base').SamplingResult} SamplingResult
+ */
+
+/**
+ * A parent-based ratio sampler which can have its ratio updated dynamically.
+ *
+ * @implements {Sampler}
+ */
+class DynamicCompositeParentThresholdTraceIdRatioBasedSampler {
+    #delegate;
+
+    constructor(ratio = 1.0) {
+        this.#delegate = newSampler(ratio);
+    }
+
+    /**
+     * @param {Context} context
+     * @param {string} traceId
+     * @param {string} spanName
+     * @param {SpanKind} spanKind
+     * @param {Attributes} attributes
+     * @param {Link[]} links
+     * @returns {SamplingResult}
+     */
+    shouldSample(context, traceId, spanName, spanKind, attributes, links) {
+        return this.#delegate.shouldSample(
+            context,
+            traceId,
+            spanName,
+            spanKind,
+            attributes,
+            links
+        );
+    }
+
+    /**
+     * @param {number} ratio
+     */
+    setRatio(ratio) {
+        this.#delegate = newSampler(ratio);
+    }
+
+    toString() {
+        return this.#delegate.toString();
+    }
+}
+
+/**
+ * @param {number} ratio A number between 0 and 1 representing the sampling ratio.
+ */
+function newSampler(ratio) {
+    return createCompositeSampler(
+        createComposableParentThresholdSampler(
+            createComposableTraceIDRatioBasedSampler(ratio)
+        )
+    );
+}
+
+/**
+ * @param {number} ratio
+ * @returns {Sampler} A ratio sampler which can have its ratio updated dynamically.
+ */
+function createDynamicCompositeParentThresholdTraceIdRatioBasedSampler(
+    ratio = 1.0
+) {
+    return new DynamicCompositeParentThresholdTraceIdRatioBasedSampler(ratio);
+}
+
+module.exports = {
+    createDynamicCompositeParentThresholdTraceIdRatioBasedSampler,
+};

packages/opentelemetry-node/lib/sdk.js

@@ -45,6 +45,9 @@
     setupDynConfExporters,
     dynConfSpanExporters,
 } = require('./dynconf');
+const {
+    createDynamicCompositeParentThresholdTraceIdRatioBasedSampler,
+} = require('./sampler');
 const DISTRO_VERSION = require('../package.json').version;
 
 /**
@@ -66,7 +69,7 @@
         try {
             await shutdownFn();
         } catch (err) {
             console.warn('warning: error shutting down OTel SDK', err);
         }
         process.exit(128 + os.constants.signals.SIGTERM);
     });
@@ -76,7 +79,7 @@
         try {
             await shutdownFn();
         } catch (err) {
             console.warn('warning: error shutting down OTel SDK', err);
         }
     });
 }
@@ -131,11 +134,15 @@
         }
     }
 
+    const sampler =
+        createDynamicCompositeParentThresholdTraceIdRatioBasedSampler();
+
     const instrs = cfg.instrumentations || getInstrumentations();
     /** @type {Partial<NodeSDKConfiguration>} */
     const defaultConfig = {
         resourceDetectors: resolveDetectors(cfg.resourceDetectors),
         instrumentations: instrs,
+        sampler,
         // Avoid setting `spanProcessor` or `traceExporter` to have NodeSDK
         // use its `TracerProviderWithEnvExporters` for tracing setup.
     };
@@ -306,6 +313,7 @@
         noopTracerProvider,
         // @ts-ignore: Ignore access of private _tracerProvider for now. (TODO)
         sdkTracerProvider: sdk._tracerProvider,
+        sampler,
         contextPropagationOnly,
     });
 

packages/opentelemetry-node/package.json

@@ -126,6 +126,7 @@
     "@opentelemetry/resource-detector-azure": "^0.14.0",
     "@opentelemetry/resource-detector-container": "^0.7.0",
     "@opentelemetry/resources": "^2.0.0",
+    "@opentelemetry/sampler-composite": "^0.206.0",
     "@opentelemetry/sdk-logs": "^0.206.0",
     "@opentelemetry/sdk-metrics": "^2.0.0",
     "@opentelemetry/sdk-node": "^0.206.0",

packages/opentelemetry-node/test/central-config.test.js

@@ -770,6 +770,50 @@ test('central-config', (suite) => {
             },
         },
 
+        {
+            name: 'central-config-gen-telemetry.js sampling_rate=0.0',
+            args: ['./fixtures/central-config-gen-telemetry.js'],
+            cwd: __dirname,
+            env: () => {
+                return {
+                    NODE_OPTIONS: '--import @elastic/opentelemetry-node',
+                    ELASTIC_OTEL_NODE_ENABLE_LOG_SENDING: 'true',
+                    // Skip cloud resource detectors to avoid delay and noise.
+                    OTEL_NODE_RESOURCE_DETECTORS:
+                        'env,host,os,process,serviceinstance,container',
+                    ELASTIC_OTEL_OPAMP_ENDPOINT: opampServer.endpoint,
+                    ELASTIC_OTEL_EXPERIMENTAL_OPAMP_HEARTBEAT_INTERVAL: '300',
+                    ELASTIC_OTEL_TEST_OPAMP_CLIENT_DIAG_ENABLED: 'true',
+                    // Set a short metric export interval to allow the
+                    // fixture script to wait for an interval after receiving
+                    // central config before proceeding.
+                    OTEL_METRIC_EXPORT_INTERVAL: '500',
+                    OTEL_METRIC_EXPORT_TIMEOUT: '450',
+                };
+            },
+            before: () => {
+                const config = {
+                    sampling_rate: '0.0',
+                };
+                opampServer.setAgentConfigMap({
+                    configMap: {
+                        elastic: {
+                            body: Buffer.from(JSON.stringify(config), 'utf8'),
+                            contentType: 'application/json',
+                        },
+                    },
+                });
+            },
+            after: () => {
+                opampServer.setAgentConfigMap({configMap: {}});
+            },
+            // verbose: true,
+            checkTelemetry: (t, col, stdout) => {
+                console.log(stdout);
+                t.equal(col.sortedSpans.length, 0, 'no spans');
+            },
+        },
+
         // TODO: Test unpatching cases with ESM. Does that work?
     ];
 

packages/opentelemetry-node/types/sampler.d.ts

@@ -0,0 +1,11 @@
+export type Attributes = import('@opentelemetry/api').Attributes;
+export type Context = import('@opentelemetry/api').Context;
+export type Link = import('@opentelemetry/api').Link;
+export type SpanKind = import('@opentelemetry/api').SpanKind;
+export type Sampler = import('@opentelemetry/sdk-trace-base').Sampler;
+export type SamplingResult = import('@opentelemetry/sdk-trace-base').SamplingResult;
+/**
+ * @param {number} ratio
+ * @returns {Sampler} A ratio sampler which can have its ratio updated dynamically.
+ */
+export function createDynamicCompositeParentThresholdTraceIdRatioBasedSampler(ratio?: number): Sampler;

scripts/gen-notice.sh

@@ -87,10 +87,12 @@ npm ls --omit=dev --all --parseable \
             "tr46": "license.MIT.txt",
             "@bufbuild/protobuf": "license.apache2.txt",
             "safe-json-stringify": "license.MIT.txt",
+            // Releases after https://github.com/open-telemetry/opentelemetry-js/pull/6002
+            // will have a LICENSE file.
+            "@opentelemetry/sampler-composite": "license.apache2.txt",
         }
         const licTypeFromPkgName = {
-            // instr-openai will get the license field in https://github.com/elastic/elastic-otel-node/pull/1015
-            "@opentelemetry/instrumentation-openai": "Apache-2.0",
+            // Packages that have a license, but no "license" entry in package.json.
         }
         const allowNoLicFile = [
             "binary-search" // CC is a public domain dedication, no need for license text.