feat: add ParentOrElseSampler

packages/opentelemetry-core/README.md

@@ -80,35 +80,35 @@ api.propagation.setGlobalPropagator(new HttpCorrelationContext());
 
 Sampler is used to make decisions on `Span` sampling.
 
-#### Always Sampler
+#### AlwaysOn
 
 Samples every trace regardless of upstream sampling decisions.
 
 > This is used as a default Sampler
 
 ```js
 const { NodeTracerProvider } = require("@opentelemetry/node");
-const { ALWAYS_SAMPLER } = require("@opentelemetry/core");
+const { AlwaysOnSampler } = require("@opentelemetry/core");
 
 const tracerProvider = new NodeTracerProvider({
-  sampler: ALWAYS_SAMPLER
+  sampler: new AlwaysOnSampler()
 });
 ```
 
-#### Never Sampler
+#### AlwaysOff
 
 Doesn't sample any trace, regardless of upstream sampling decisions.
 
 ```js
 const { NodeTracerProvider } = require("@opentelemetry/node");
-const { NEVER_SAMPLER } = require("@opentelemetry/core");
+const { AlwaysOffSampler } = require("@opentelemetry/core");
 
 const tracerProvider = new NodeTracerProvider({
-  sampler: NEVER_SAMPLER
+  sampler: new AlwaysOffSampler()
 });
 ```
 
-#### Probability Sampler
+#### Probability
 
 Samples a configurable percentage of traces, and additionally samples any trace that was sampled upstream.
 
@@ -121,6 +121,19 @@ const tracerProvider = new NodeTracerProvider({
 });
 ```
 
+#### ParentOrElse
+
+A composite sampler that either respects the parent span's sampling decision or delegates to `delegateSampler` for root spans.
+
+```js
+const { NodeTracerProvider } = require("@opentelemetry/node");
+const { ParentOrElseSampler, AlwaysOffSampler } = require("@opentelemetry/core");
+
+const tracerProvider = new NodeTracerProvider({
+  sampler: new ParentOrElseSampler(new AlwaysOffSampler())
+});
+```
+
 ## Useful links
 
 - For more information on OpenTelemetry, visit: <https://opentelemetry.io/>

packages/opentelemetry-core/src/index.ts

@@ -29,6 +29,9 @@ export * from './correlation-context/correlation-context';
 export * from './correlation-context/propagation/HttpCorrelationContext';
 export * from './platform';
 export * from './trace/NoRecordingSpan';
+export * from './trace/sampler/AlwaysOffSampler';
+export * from './trace/sampler/AlwaysOnSampler';
+export * from './trace/sampler/ParentOrElseSampler';
 export * from './trace/sampler/ProbabilitySampler';
 export * from './trace/spancontext-utils';
 export * from './trace/TraceState';

packages/opentelemetry-core/src/trace/sampler/AlwaysOffSampler.ts

@@ -0,0 +1,30 @@
+/*
+ * 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 { Sampler, SamplingDecision, SamplingResult } from '@opentelemetry/api';
+
+/** Sampler that samples no traces. */
+export class AlwaysOffSampler implements Sampler {
+  shouldSample(): SamplingResult {
+    return {
+      decision: SamplingDecision.NOT_RECORD,
+    };
+  }
+
+  toString(): string {
+    return `AlwaysOffSampler`;
+  }
+}

packages/opentelemetry-core/src/trace/sampler/AlwaysOnSampler.ts

@@ -0,0 +1,30 @@
+/*
+ * 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 { Sampler, SamplingDecision, SamplingResult } from '@opentelemetry/api';
+
+/** Sampler that samples all traces. */
+export class AlwaysOnSampler implements Sampler {
+  shouldSample(): SamplingResult {
+    return {
+      decision: SamplingDecision.RECORD_AND_SAMPLED,
+    };
+  }
+
+  toString(): string {
+    return `AlwaysOnSampler`;
+  }
+}

packages/opentelemetry-core/src/trace/sampler/ParentOrElseSampler.ts

@@ -0,0 +1,65 @@
+/*
+ * 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 {
+  Sampler,
+  SpanContext,
+  TraceFlags,
+  SamplingDecision,
+  SpanKind,
+  Attributes,
+  Link,
+  SamplingResult,
+} from '@opentelemetry/api';
+
+/**
+ * A composite sampler that either respects the parent span's sampling decision
+ * or delegates to `delegateSampler` for root spans.
+ */
+export class ParentOrElseSampler implements Sampler {
+  constructor(private _delegateSampler: Sampler) {}
+
+  shouldSample(
+    parentContext: SpanContext | undefined,
+    traceId: string,
+    spanName: string,
+    spanKind: SpanKind,
+    attributes: Attributes,
+    links: Link[]
+  ): SamplingResult {
+    // Respect the parent sampling decision if there is one
+    if (parentContext) {
+      return {
+        decision:
+          (TraceFlags.SAMPLED & parentContext.traceFlags) === TraceFlags.SAMPLED
+            ? SamplingDecision.RECORD_AND_SAMPLED
+            : SamplingDecision.NOT_RECORD,
+      };
+    }
+    return this._delegateSampler.shouldSample(
+      parentContext,
+      traceId,
+      spanName,
+      spanKind,
+      attributes,
+      links
+    );
+  }
+
+  toString(): string {
+    return `ParentOrElse{${this._delegateSampler.toString()}}`;
+  }
+}

packages/opentelemetry-core/src/trace/sampler/ProbabilitySampler.ts

@@ -19,6 +19,7 @@ import {
   SpanContext,
   TraceFlags,
   SamplingDecision,
+  SamplingResult,
 } from '@opentelemetry/api';
 
 /** Sampler that samples a given fraction of traces. */
@@ -27,9 +28,10 @@ export class ProbabilitySampler implements Sampler {
     this._probability = this._normalize(_probability);
   }
 
-  shouldSample(parentContext?: SpanContext) {
-    // Respect the parent sampling decision if there is one
-    if (parentContext && typeof parentContext.traceFlags !== 'undefined') {
+  shouldSample(parentContext?: SpanContext): SamplingResult {
+    // Respect the parent sampling decision if there is one.
+    // TODO(#1284): add an option to ignore parent regarding to spec.
+    if (parentContext) {
       return {
         decision:
           (TraceFlags.SAMPLED & parentContext.traceFlags) === TraceFlags.SAMPLED
@@ -46,8 +48,6 @@ export class ProbabilitySampler implements Sampler {
   }
 
   toString(): string {
-    // TODO: Consider to use `AlwaysSampleSampler` and `NeverSampleSampler`
-    // based on the specs.
     return `ProbabilitySampler{${this._probability}}`;
   }
 
@@ -56,6 +56,3 @@ export class ProbabilitySampler implements Sampler {
     return probability >= 1 ? 1 : probability <= 0 ? 0 : probability;
   }
 }
-
-export const ALWAYS_SAMPLER = new ProbabilitySampler(1);
-export const NEVER_SAMPLER = new ProbabilitySampler(0);

packages/opentelemetry-core/test/trace/AlwaysOffSampler.test.ts

@@ -0,0 +1,32 @@
+/*
+ * 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 * as api from '@opentelemetry/api';
+import { AlwaysOffSampler } from '../../src/trace/sampler/AlwaysOffSampler';
+
+describe('AlwaysOffSampler', () => {
+  it('should reflect sampler name', () => {
+    const sampler = new AlwaysOffSampler();
+    assert.strictEqual(sampler.toString(), 'AlwaysOffSampler');
+  });
+
+  it('should return decision: api.SamplingDecision.NOT_RECORD for AlwaysOffSampler', () => {
+    const sampler = new AlwaysOffSampler();
+    assert.deepStrictEqual(sampler.shouldSample(), {
+      decision: api.SamplingDecision.NOT_RECORD,
+    });
+  });
+});

packages/opentelemetry-core/test/trace/AlwaysOnSampler.test.ts

@@ -0,0 +1,32 @@
+/*
+ * 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 * as api from '@opentelemetry/api';
+import { AlwaysOnSampler } from '../../src/trace/sampler/AlwaysOnSampler';
+
+describe('AlwaysOnSampler', () => {
+  it('should reflect sampler name', () => {
+    const sampler = new AlwaysOnSampler();
+    assert.strictEqual(sampler.toString(), 'AlwaysOnSampler');
+  });
+
+  it('should return api.SamplingDecision.RECORD_AND_SAMPLED for AlwaysOnSampler', () => {
+    const sampler = new AlwaysOnSampler();
+    assert.deepStrictEqual(sampler.shouldSample(), {
+      decision: api.SamplingDecision.RECORD_AND_SAMPLED,
+    });
+  });
+});