feat(sampler-composite): add ComposableAnnotatingSampler and ComposableRuleBasedSampler

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): add ComposableAnnotatingSampler and ComposableRuleBasedSampler [#6305](https://github.com/open-telemetry/opentelemetry-js/pull/6305) @trentm
+
 ### :bug: Bug Fixes
 
 ### :books: Documentation

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

@@ -16,10 +16,10 @@
 import type { ComposableSampler, SamplingIntent } from './types';
 import { INVALID_THRESHOLD } from './util';
 
-const intent: SamplingIntent = {
+const intent: SamplingIntent = Object.freeze({
   threshold: INVALID_THRESHOLD,
   thresholdReliable: false,
-};
+});
 
 class ComposableAlwaysOffSampler implements ComposableSampler {
   getSamplingIntent(): SamplingIntent {

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

@@ -16,10 +16,10 @@
 import type { ComposableSampler, SamplingIntent } from './types';
 import { MIN_THRESHOLD } from './util';
 
-const intent: SamplingIntent = {
+const intent: SamplingIntent = Object.freeze({
   threshold: MIN_THRESHOLD,
   thresholdReliable: true,
-};
+});
 
 class ComposableAlwaysOnSampler implements ComposableSampler {
   getSamplingIntent(): SamplingIntent {

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

@@ -0,0 +1,69 @@
+/*
+ * 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 { Attributes, Context, Link, SpanKind } from '@opentelemetry/api';
+import type { ComposableSampler, SamplingIntent } from './types';
+
+class ComposableAnnotatingSampler implements ComposableSampler {
+  private readonly delegate: ComposableSampler;
+  private readonly attributes: Attributes;
+  private readonly description: string;
+
+  constructor(delegate: ComposableSampler, attributes: Attributes) {
+    // Shallow copy `attributes` to avoid changes to the original object (at
+    // least top-level fields) impacting the sampler. Freeze the object so
+    // we can return it in `getSamplingIntent` without copying there.
+    this.attributes = Object.freeze({ ...attributes });
+    this.delegate = delegate;
+    this.description = `ComposableAnnotatingSampler(${delegate}, attributes)`;
+  }
+
+  getSamplingIntent(
+    context: Context,
+    traceId: string,
+    spanName: string,
+    spanKind: SpanKind,
+    attributes: Attributes,
+    links: Link[]
+  ): SamplingIntent {
+    const intent = this.delegate.getSamplingIntent(
+      context,
+      traceId,
+      spanName,
+      spanKind,
+      attributes,
+      links
+    );
+    return {
+      threshold: intent.threshold,
+      thresholdReliable: intent.thresholdReliable,
+      attributes: intent.attributes
+        ? { ...intent.attributes, ...this.attributes }
+        : this.attributes,
+      updateTraceState: intent.updateTraceState,
+    };
+  }
+
+  toString(): string {
+    return this.description;
+  }
+}
+
+export function createComposableAnnotatingSampler(
+  delegate: ComposableSampler,
+  attributes: Attributes
+): ComposableSampler {
+  return new ComposableAnnotatingSampler(delegate, attributes);
+}

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

@@ -18,5 +18,7 @@ export { createComposableAlwaysOffSampler } from './alwaysoff';
 export { createComposableAlwaysOnSampler } from './alwayson';
 export { createComposableTraceIDRatioBasedSampler } from './traceidratio';
 export { createComposableParentThresholdSampler } from './parentthreshold';
+export { createComposableAnnotatingSampler } from './annotating';
+export { createComposableRuleBasedSampler } from './rulebased';
 export { createCompositeSampler } from './composite';
 export type { ComposableSampler, SamplingIntent } from './types';

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

@@ -0,0 +1,71 @@
+/*
+ * 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 { Attributes, Context, Link, SpanKind } from '@opentelemetry/api';
+
+import type { ComposableSampler, SamplingIntent, SamplingRule } from './types';
+import { INVALID_THRESHOLD } from './util';
+
+const NON_SAMPLING_INTENT: SamplingIntent = Object.freeze({
+  threshold: INVALID_THRESHOLD,
+  thresholdReliable: false,
+});
+
+class ComposableRuleBasedSampler implements ComposableSampler {
+  private readonly rules: SamplingRule[];
+  private readonly description: string;
+
+  constructor(rules: SamplingRule[]) {
+    this.rules = rules;
+    const ruleReprs = rules.map(
+      rule => `(${rule[0].name || '(anonymous)'}, ${rule[1].toString()})`
+    );
+    this.description = `ComposableRuleBasedSampler([${ruleReprs.join(', ')}])`;
+  }
+
+  getSamplingIntent(
+    context: Context,
+    traceId: string,
+    spanName: string,
+    spanKind: SpanKind,
+    attributes: Attributes,
+    links: Link[]
+  ): SamplingIntent {
+    for (const [predicate, sampler] of this.rules) {
+      if (predicate(context, traceId, spanName, spanKind, attributes, links)) {
+        return sampler.getSamplingIntent(
+          context,
+          traceId,
+          spanName,
+          spanKind,
+          attributes,
+          links
+        );
+      }
+    }
+    return NON_SAMPLING_INTENT;
+  }
+
+  toString(): string {
+    return this.description;
+  }
+}
+
+export function createComposableRuleBasedSampler(
+  rules: SamplingRule[]
+): ComposableSampler {
+  return new ComposableRuleBasedSampler(rules);
+}

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

@@ -32,18 +32,18 @@ class ComposableTraceIDRatioBasedSampler implements ComposableSampler {
     const thresholdStr =
       threshold === MAX_THRESHOLD ? 'max' : serializeTh(threshold);
     if (threshold !== MAX_THRESHOLD) {
-      this.intent = {
+      this.intent = Object.freeze({
         threshold: threshold,
         thresholdReliable: true,
-      };
+      });
     } else {
       // 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 = {
+      this.intent = Object.freeze({
         threshold: INVALID_THRESHOLD,
         thresholdReliable: false,
-      };
+      });
     }
     this.description = `ComposableTraceIDRatioBasedSampler(threshold=${thresholdStr}, ratio=${ratio})`;
   }

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

@@ -42,3 +42,8 @@ export interface ComposableSampler {
   /** Returns the sampler name or short description with the configuration. */
   toString(): string;
 }
+
+export type SamplingPredicate = (
+  ...args: Parameters<Sampler['shouldSample']>
+) => boolean;
+export type SamplingRule = [SamplingPredicate, ComposableSampler];

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

@@ -0,0 +1,87 @@
+/*
+ * 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 * as assert from 'assert';
+
+import { context, SpanKind } from '@opentelemetry/api';
+
+import {
+  createComposableAlwaysOnSampler,
+  createComposableAnnotatingSampler,
+} from '../src';
+
+describe('ComposableAnnotatingSampler', () => {
+  const alwaysOnSampler = createComposableAlwaysOnSampler();
+
+  it('should have a description', () => {
+    const sampler = createComposableAnnotatingSampler(alwaysOnSampler, {});
+    assert.strictEqual(
+      sampler.toString(),
+      'ComposableAnnotatingSampler(ComposableAlwaysOnSampler, attributes)'
+    );
+  });
+
+  it('should add attributes to SamplingIntent', () => {
+    const delegateIntent = alwaysOnSampler.getSamplingIntent(
+      context.active(),
+      'unused',
+      'span-name',
+      SpanKind.SERVER,
+      {},
+      []
+    );
+    const sampler = createComposableAnnotatingSampler(alwaysOnSampler, {
+      foo: 'bar',
+    });
+    const intent = sampler.getSamplingIntent(
+      context.active(),
+      'unused',
+      'span-name',
+      SpanKind.SERVER,
+      {},
+      []
+    );
+    assert.strictEqual(intent.threshold, delegateIntent.threshold);
+    assert.strictEqual(
+      intent.thresholdReliable,
+      delegateIntent.thresholdReliable
+    );
+    assert.deepStrictEqual(intent.attributes, { foo: 'bar' });
+  });
+
+  it('should merge attributes', () => {
+    const sampler = createComposableAnnotatingSampler(
+      createComposableAnnotatingSampler(alwaysOnSampler, {
+        foo: 'baz',
+        wuz: 'here',
+      }),
+      { foo: 'bar', spam: 'eggs' }
+    );
+    const intent = sampler.getSamplingIntent(
+      context.active(),
+      'unused',
+      'span-name',
+      SpanKind.SERVER,
+      {},
+      []
+    );
+    assert.deepStrictEqual(intent.attributes, {
+      foo: 'bar', // outer annotating sampler wins
+      spam: 'eggs',
+      wuz: 'here',
+    });
+  });
+});