feat(sdk-trace-base): move Sampler declaration into sdk-trace-base (#3088)

Co-authored-by: Daniel Dyla <[email protected]>

Author: legendecas

CHANGELOG.md

@@ -8,6 +8,8 @@ All notable changes to this project will be documented in this file.
 
 ### :rocket: (Enhancement)
 
+feat(sdk-trace-base): move Sampler declaration into sdk-trace-base [#3088](https://github.com/open-telemetry/opentelemetry-js/pull/3088) @legendecas
+
 ### :bug: (Bug Fix)
 
 ### :books: (Refine Doc)

experimental/packages/opentelemetry-sdk-node/src/types.ts

@@ -15,14 +15,15 @@
  */
 
 import type { ContextManager, SpanAttributes } from '@opentelemetry/api';
-import { Sampler, TextMapPropagator } from '@opentelemetry/api';
+import { TextMapPropagator } from '@opentelemetry/api';
 import { InstrumentationOption } from '@opentelemetry/instrumentation';
 import { Resource } from '@opentelemetry/resources';
 import { MetricReader } from '@opentelemetry/sdk-metrics-base';
 import {
+  Sampler,
   SpanExporter,
   SpanLimits,
-  SpanProcessor
+  SpanProcessor,
 } from '@opentelemetry/sdk-trace-base';
 
 export interface NodeSDKConfiguration {

packages/opentelemetry-core/README.md

@@ -13,11 +13,6 @@ This package provides default implementations of the OpenTelemetry API for trace
       - [W3CTraceContextPropagator Propagator](#w3ctracecontextpropagator-propagator)
       - [Composite Propagator](#composite-propagator)
       - [Baggage Propagator](#baggage-propagator)
-    - [Built-in Sampler](#built-in-sampler)
-      - [AlwaysOn Sampler](#alwayson-sampler)
-      - [AlwaysOff Sampler](#alwaysoff-sampler)
-      - [TraceIdRatioBased Sampler](#traceidratiobased-sampler)
-      - [ParentBased Sampler](#parentbased-sampler)
   - [Useful links](#useful-links)
   - [License](#license)
 
@@ -61,107 +56,6 @@ const { W3CBaggagePropagator } = require("@opentelemetry/core");
 api.propagation.setGlobalPropagator(new W3CBaggagePropagator());
 ```
 
-### Built-in Sampler
-
-Sampler is used to make decisions on `Span` sampling.
-
-#### AlwaysOn Sampler
-
-Samples every trace regardless of upstream sampling decisions.
-
-> This is used as a default Sampler
-
-```js
-const { NodeTracerProvider } = require("@opentelemetry/sdk-trace-node");
-const { AlwaysOnSampler } = require("@opentelemetry/core");
-
-const tracerProvider = new NodeTracerProvider({
-  sampler: new AlwaysOnSampler()
-});
-```
-
-#### AlwaysOff Sampler
-
-Doesn't sample any trace, regardless of upstream sampling decisions.
-
-```js
-const { NodeTracerProvider } = require("@opentelemetry/sdk-trace-node");
-const { AlwaysOffSampler } = require("@opentelemetry/core");
-
-const tracerProvider = new NodeTracerProvider({
-  sampler: new AlwaysOffSampler()
-});
-```
-
-#### TraceIdRatioBased Sampler
-
-Samples some percentage of traces, calculated deterministically using the trace ID.
-Any trace that would be sampled at a given percentage will also be sampled at any higher percentage.
-
-The `TraceIDRatioSampler` may be used with the `ParentBasedSampler` to respect the sampled flag of an incoming trace.
-
-```js
-const { NodeTracerProvider } = require("@opentelemetry/sdk-trace-node");
-const { TraceIdRatioBasedSampler } = require("@opentelemetry/core");
-
-const tracerProvider = new NodeTracerProvider({
-  // See details of ParentBasedSampler below
-  sampler: new ParentBasedSampler({
-    // Trace ID Ratio Sampler accepts a positional argument
-    // which represents the percentage of traces which should
-    // be sampled.
-    root: new TraceIdRatioBasedSampler(0.5)
-  });
-});
-```
-
-#### ParentBased Sampler
-
-- This is a composite sampler. `ParentBased` helps distinguished between the
-following cases:
-  - No parent (root span).
-  - Remote parent with `sampled` flag `true`
-  - Remote parent with `sampled` flag `false`
-  - Local parent with `sampled` flag `true`
-  - Local parent with `sampled` flag `false`
-
-Required parameters:
-
-- `root(Sampler)` - Sampler called for spans with no parent (root spans)
-
-Optional parameters:
-
-- `remoteParentSampled(Sampler)` (default: `AlwaysOn`)
-- `remoteParentNotSampled(Sampler)` (default: `AlwaysOff`)
-- `localParentSampled(Sampler)` (default: `AlwaysOn`)
-- `localParentNotSampled(Sampler)` (default: `AlwaysOff`)
-
-|Parent| parent.isRemote() | parent.isSampled()| Invoke sampler|
-|--|--|--|--|
-|absent| n/a | n/a |`root()`|
-|present|true|true|`remoteParentSampled()`|
-|present|true|false|`remoteParentNotSampled()`|
-|present|false|true|`localParentSampled()`|
-|present|false|false|`localParentNotSampled()`|
-
-```js
-const { NodeTracerProvider } = require("@opentelemetry/sdk-trace-node");
-const { ParentBasedSampler, AlwaysOffSampler, TraceIdRatioBasedSampler } = require("@opentelemetry/core");
-
-const tracerProvider = new NodeTracerProvider({
-  sampler: new ParentBasedSampler({
-    // By default, the ParentBasedSampler will respect the parent span's sampling
-    // decision. This is configurable by providing a different sampler to use
-    // based on the situation. See configuration details above.
-    //
-    // This will delegate the sampling decision of all root traces (no parent)
-    // to the TraceIdRatioBasedSampler.
-    // See details of TraceIdRatioBasedSampler above.
-    root: new TraceIdRatioBasedSampler(0.5)
-  })
-});
-```
-
 ## Useful links
 
 - For more information on OpenTelemetry, visit: <https://opentelemetry.io/>

packages/opentelemetry-core/src/platform/browser/RandomIdGenerator.ts

@@ -18,6 +18,9 @@ import { IdGenerator } from '../../trace/IdGenerator';
 const SPAN_ID_BYTES = 8;
 const TRACE_ID_BYTES = 16;
 
+/**
+ * @deprecated Use the one defined in @opentelemetry/sdk-trace-base instead.
+ */
 export class RandomIdGenerator implements IdGenerator {
   /**
    * Returns a random 16-byte trace ID formatted/encoded as a 32 lowercase hex

packages/opentelemetry-core/src/platform/node/RandomIdGenerator.ts

@@ -18,6 +18,9 @@ import { IdGenerator } from '../../trace/IdGenerator';
 const SPAN_ID_BYTES = 8;
 const TRACE_ID_BYTES = 16;
 
+/**
+ * @deprecated Use the one defined in @opentelemetry/sdk-trace-base instead.
+ */
 export class RandomIdGenerator implements IdGenerator {
   /**
    * Returns a random 16-byte trace ID formatted/encoded as a 32 lowercase hex

packages/opentelemetry-core/src/trace/IdGenerator.ts

@@ -14,7 +14,10 @@
  * limitations under the License.
  */
 
-/** IdGenerator provides an interface for generating Trace Id and Span Id */
+/**
+ * @deprecated Use the one defined in @opentelemetry/sdk-trace-base instead.
+ * IdGenerator provides an interface for generating Trace Id and Span Id.
+ */
 export interface IdGenerator {
   /** Returns a trace ID composed of 32 lowercase hex characters. */
   generateTraceId(): string;

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

@@ -16,7 +16,10 @@
 
 import { Sampler, SamplingDecision, SamplingResult } from '@opentelemetry/api';
 
-/** Sampler that samples no traces. */
+/**
+ * @deprecated Use the one defined in @opentelemetry/sdk-trace-base instead.
+ * Sampler that samples no traces.
+ */
 export class AlwaysOffSampler implements Sampler {
   shouldSample(): SamplingResult {
     return {

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

@@ -16,7 +16,10 @@
 
 import { Sampler, SamplingDecision, SamplingResult } from '@opentelemetry/api';
 
-/** Sampler that samples all traces. */
+/**
+ * @deprecated Use the one defined in @opentelemetry/sdk-trace-base instead.
+ * Sampler that samples all traces.
+ */
 export class AlwaysOnSampler implements Sampler {
   shouldSample(): SamplingResult {
     return {

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

@@ -29,6 +29,7 @@ import { AlwaysOffSampler } from './AlwaysOffSampler';
 import { AlwaysOnSampler } from './AlwaysOnSampler';
 
 /**
+ * @deprecated Use the one defined in @opentelemetry/sdk-trace-base instead.
  * A composite sampler that either respects the parent span's sampling decision
  * or delegates to `delegateSampler` for root spans.
  */

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

@@ -21,7 +21,10 @@ import {
   isValidTraceId,
 } from '@opentelemetry/api';
 
-/** Sampler that samples a given fraction of traces based of trace id deterministically. */
+/**
+ * @deprecated Use the one defined in @opentelemetry/sdk-trace-base instead.
+ * Sampler that samples a given fraction of traces based of trace id deterministically.
+ */
 export class TraceIdRatioBasedSampler implements Sampler {
   private _upperBound: number;