feat(sdk-trace-base): move Sampler declaration into sdk-trace-base (o…

…pen-telemetry#3088) Co-authored-by: Daniel Dyla <[email protected]>
weyert · Jul 29, 2022 · df58fac · df58fac
1 parent 3db1056
commit df58fac
Show file tree

Hide file tree

Showing 41 changed files with 1,189 additions and 140 deletions.
diff --git a/CHANGELOG.md b/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)

diff --git a/experimental/packages/opentelemetry-sdk-node/src/types.ts b/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 {

diff --git a/packages/opentelemetry-core/README.md b/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/>

diff --git a/packages/opentelemetry-core/src/platform/browser/RandomIdGenerator.ts b/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

diff --git a/packages/opentelemetry-core/src/platform/node/RandomIdGenerator.ts b/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

diff --git a/packages/opentelemetry-core/src/trace/IdGenerator.ts b/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;

diff --git a/packages/opentelemetry-core/src/trace/sampler/AlwaysOffSampler.ts b/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 {

diff --git a/packages/opentelemetry-core/src/trace/sampler/AlwaysOnSampler.ts b/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 {

diff --git a/packages/opentelemetry-core/src/trace/sampler/ParentBasedSampler.ts b/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.
  */

diff --git a/packages/opentelemetry-core/src/trace/sampler/TraceIdRatioBasedSampler.ts b/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;
 

diff --git a/packages/opentelemetry-sdk-trace-base/README.md b/packages/opentelemetry-sdk-trace-base/README.md
@@ -46,6 +46,107 @@ Tracing configuration is a merge of user supplied configuration with both the de
 configuration as specified in [config.ts](./src/config.ts) and an
 environmentally configurable sampling (via `OTEL_TRACES_SAMPLER` and `OTEL_TRACES_SAMPLER_ARG`).
 
+## Built-in Samplers
+
+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)
+  })
+});
+```
+
 ## Example
 
 See [examples/basic-tracer-node](https://github.com/open-telemetry/opentelemetry-js/tree/main/examples/basic-tracer-node) for an end-to-end example, including exporting created spans.

diff --git a/packages/opentelemetry-sdk-trace-base/src/IdGenerator.ts b/packages/opentelemetry-sdk-trace-base/src/IdGenerator.ts
@@ -0,0 +1,23 @@
+/*
+ * 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.
+ */
+
+/** 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;
+  /** Returns a span ID composed of 16 lowercase hex characters. */
+  generateSpanId(): string;
+}