Skip to content

Commit df58fac

Browse files
legendecasdyladan
legendecas
and
dyladan
authored
feat(sdk-trace-base): move Sampler declaration into sdk-trace-base (#3088)
 Co-authored-by: Daniel Dyla <[email protected]>
1 parent 3db1056 commit df58fac

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

41 files changed

+1189
-140
lines changed

‎CHANGELOG.md

+2
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@ All notable changes to this project will be documented in this file.
88

99
### :rocket: (Enhancement)
1010

11+
feat(sdk-trace-base): move Sampler declaration into sdk-trace-base [#3088](https://github.com/open-telemetry/opentelemetry-js/pull/3088) @legendecas
12+
1113
### :bug: (Bug Fix)
1214

1315
### :books: (Refine Doc)

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

+3-2
Original file line numberDiff line numberDiff line change
@@ -15,14 +15,15 @@
1515
*/
1616

1717
import type { ContextManager, SpanAttributes } from '@opentelemetry/api';
18-
import { Sampler, TextMapPropagator } from '@opentelemetry/api';
18+
import { TextMapPropagator } from '@opentelemetry/api';
1919
import { InstrumentationOption } from '@opentelemetry/instrumentation';
2020
import { Resource } from '@opentelemetry/resources';
2121
import { MetricReader } from '@opentelemetry/sdk-metrics-base';
2222
import {
23+
Sampler,
2324
SpanExporter,
2425
SpanLimits,
25-
SpanProcessor
26+
SpanProcessor,
2627
} from '@opentelemetry/sdk-trace-base';
2728

2829
export interface NodeSDKConfiguration {

‎packages/opentelemetry-core/README.md

-106
Original file line numberDiff line numberDiff line change
@@ -13,11 +13,6 @@ This package provides default implementations of the OpenTelemetry API for trace
1313
- [W3CTraceContextPropagator Propagator](#w3ctracecontextpropagator-propagator)
1414
- [Composite Propagator](#composite-propagator)
1515
- [Baggage Propagator](#baggage-propagator)
16-
- [Built-in Sampler](#built-in-sampler)
17-
- [AlwaysOn Sampler](#alwayson-sampler)
18-
- [AlwaysOff Sampler](#alwaysoff-sampler)
19-
- [TraceIdRatioBased Sampler](#traceidratiobased-sampler)
20-
- [ParentBased Sampler](#parentbased-sampler)
2116
- [Useful links](#useful-links)
2217
- [License](#license)
2318

@@ -61,107 +56,6 @@ const { W3CBaggagePropagator } = require("@opentelemetry/core");
6156
api.propagation.setGlobalPropagator(new W3CBaggagePropagator());
6257
```
6358

64-
### Built-in Sampler
65-
66-
Sampler is used to make decisions on `Span` sampling.
67-
68-
#### AlwaysOn Sampler
69-
70-
Samples every trace regardless of upstream sampling decisions.
71-
72-
> This is used as a default Sampler
73-
74-
```js
75-
const { NodeTracerProvider } = require("@opentelemetry/sdk-trace-node");
76-
const { AlwaysOnSampler } = require("@opentelemetry/core");
77-
78-
const tracerProvider = new NodeTracerProvider({
79-
sampler: new AlwaysOnSampler()
80-
});
81-
```
82-
83-
#### AlwaysOff Sampler
84-
85-
Doesn't sample any trace, regardless of upstream sampling decisions.
86-
87-
```js
88-
const { NodeTracerProvider } = require("@opentelemetry/sdk-trace-node");
89-
const { AlwaysOffSampler } = require("@opentelemetry/core");
90-
91-
const tracerProvider = new NodeTracerProvider({
92-
sampler: new AlwaysOffSampler()
93-
});
94-
```
95-
96-
#### TraceIdRatioBased Sampler
97-
98-
Samples some percentage of traces, calculated deterministically using the trace ID.
99-
Any trace that would be sampled at a given percentage will also be sampled at any higher percentage.
100-
101-
The `TraceIDRatioSampler` may be used with the `ParentBasedSampler` to respect the sampled flag of an incoming trace.
102-
103-
```js
104-
const { NodeTracerProvider } = require("@opentelemetry/sdk-trace-node");
105-
const { TraceIdRatioBasedSampler } = require("@opentelemetry/core");
106-
107-
const tracerProvider = new NodeTracerProvider({
108-
// See details of ParentBasedSampler below
109-
sampler: new ParentBasedSampler({
110-
// Trace ID Ratio Sampler accepts a positional argument
111-
// which represents the percentage of traces which should
112-
// be sampled.
113-
root: new TraceIdRatioBasedSampler(0.5)
114-
});
115-
});
116-
```
117-
118-
#### ParentBased Sampler
119-
120-
- This is a composite sampler. `ParentBased` helps distinguished between the
121-
following cases:
122-
- No parent (root span).
123-
- Remote parent with `sampled` flag `true`
124-
- Remote parent with `sampled` flag `false`
125-
- Local parent with `sampled` flag `true`
126-
- Local parent with `sampled` flag `false`
127-
128-
Required parameters:
129-
130-
- `root(Sampler)` - Sampler called for spans with no parent (root spans)
131-
132-
Optional parameters:
133-
134-
- `remoteParentSampled(Sampler)` (default: `AlwaysOn`)
135-
- `remoteParentNotSampled(Sampler)` (default: `AlwaysOff`)
136-
- `localParentSampled(Sampler)` (default: `AlwaysOn`)
137-
- `localParentNotSampled(Sampler)` (default: `AlwaysOff`)
138-
139-
|Parent| parent.isRemote() | parent.isSampled()| Invoke sampler|
140-
|--|--|--|--|
141-
|absent| n/a | n/a |`root()`|
142-
|present|true|true|`remoteParentSampled()`|
143-
|present|true|false|`remoteParentNotSampled()`|
144-
|present|false|true|`localParentSampled()`|
145-
|present|false|false|`localParentNotSampled()`|
146-
147-
```js
148-
const { NodeTracerProvider } = require("@opentelemetry/sdk-trace-node");
149-
const { ParentBasedSampler, AlwaysOffSampler, TraceIdRatioBasedSampler } = require("@opentelemetry/core");
150-
151-
const tracerProvider = new NodeTracerProvider({
152-
sampler: new ParentBasedSampler({
153-
// By default, the ParentBasedSampler will respect the parent span's sampling
154-
// decision. This is configurable by providing a different sampler to use
155-
// based on the situation. See configuration details above.
156-
//
157-
// This will delegate the sampling decision of all root traces (no parent)
158-
// to the TraceIdRatioBasedSampler.
159-
// See details of TraceIdRatioBasedSampler above.
160-
root: new TraceIdRatioBasedSampler(0.5)
161-
})
162-
});
163-
```
164-
16559
## Useful links
16660

16761
- For more information on OpenTelemetry, visit: <https://opentelemetry.io/>

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

+3
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,9 @@ import { IdGenerator } from '../../trace/IdGenerator';
1818
const SPAN_ID_BYTES = 8;
1919
const TRACE_ID_BYTES = 16;
2020

21+
/**
22+
* @deprecated Use the one defined in @opentelemetry/sdk-trace-base instead.
23+
*/
2124
export class RandomIdGenerator implements IdGenerator {
2225
/**
2326
* Returns a random 16-byte trace ID formatted/encoded as a 32 lowercase hex

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

+3
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,9 @@ import { IdGenerator } from '../../trace/IdGenerator';
1818
const SPAN_ID_BYTES = 8;
1919
const TRACE_ID_BYTES = 16;
2020

21+
/**
22+
* @deprecated Use the one defined in @opentelemetry/sdk-trace-base instead.
23+
*/
2124
export class RandomIdGenerator implements IdGenerator {
2225
/**
2326
* Returns a random 16-byte trace ID formatted/encoded as a 32 lowercase hex

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

+4-1
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,10 @@
1414
* limitations under the License.
1515
*/
1616

17-
/** IdGenerator provides an interface for generating Trace Id and Span Id */
17+
/**
18+
* @deprecated Use the one defined in @opentelemetry/sdk-trace-base instead.
19+
* IdGenerator provides an interface for generating Trace Id and Span Id.
20+
*/
1821
export interface IdGenerator {
1922
/** Returns a trace ID composed of 32 lowercase hex characters. */
2023
generateTraceId(): string;

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

+4-1
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,10 @@
1616

1717
import { Sampler, SamplingDecision, SamplingResult } from '@opentelemetry/api';
1818

19-
/** Sampler that samples no traces. */
19+
/**
20+
* @deprecated Use the one defined in @opentelemetry/sdk-trace-base instead.
21+
* Sampler that samples no traces.
22+
*/
2023
export class AlwaysOffSampler implements Sampler {
2124
shouldSample(): SamplingResult {
2225
return {

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

+4-1
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,10 @@
1616

1717
import { Sampler, SamplingDecision, SamplingResult } from '@opentelemetry/api';
1818

19-
/** Sampler that samples all traces. */
19+
/**
20+
* @deprecated Use the one defined in @opentelemetry/sdk-trace-base instead.
21+
* Sampler that samples all traces.
22+
*/
2023
export class AlwaysOnSampler implements Sampler {
2124
shouldSample(): SamplingResult {
2225
return {

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

+1
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ import { AlwaysOffSampler } from './AlwaysOffSampler';
2929
import { AlwaysOnSampler } from './AlwaysOnSampler';
3030

3131
/**
32+
* @deprecated Use the one defined in @opentelemetry/sdk-trace-base instead.
3233
* A composite sampler that either respects the parent span's sampling decision
3334
* or delegates to `delegateSampler` for root spans.
3435
*/

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

+4-1
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,10 @@ import {
2121
isValidTraceId,
2222
} from '@opentelemetry/api';
2323

24-
/** Sampler that samples a given fraction of traces based of trace id deterministically. */
24+
/**
25+
* @deprecated Use the one defined in @opentelemetry/sdk-trace-base instead.
26+
* Sampler that samples a given fraction of traces based of trace id deterministically.
27+
*/
2528
export class TraceIdRatioBasedSampler implements Sampler {
2629
private _upperBound: number;
2730

‎packages/opentelemetry-sdk-trace-base/README.md

+101
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,107 @@ Tracing configuration is a merge of user supplied configuration with both the de
4646
configuration as specified in [config.ts](./src/config.ts) and an
4747
environmentally configurable sampling (via `OTEL_TRACES_SAMPLER` and `OTEL_TRACES_SAMPLER_ARG`).
4848

49+
## Built-in Samplers
50+
51+
Sampler is used to make decisions on `Span` sampling.
52+
53+
### AlwaysOn Sampler
54+
55+
Samples every trace regardless of upstream sampling decisions.
56+
57+
> This is used as a default Sampler
58+
59+
```js
60+
const { NodeTracerProvider } = require("@opentelemetry/sdk-trace-node");
61+
const { AlwaysOnSampler } = require("@opentelemetry/core");
62+
63+
const tracerProvider = new NodeTracerProvider({
64+
sampler: new AlwaysOnSampler()
65+
});
66+
```
67+
68+
### AlwaysOff Sampler
69+
70+
Doesn't sample any trace, regardless of upstream sampling decisions.
71+
72+
```js
73+
const { NodeTracerProvider } = require("@opentelemetry/sdk-trace-node");
74+
const { AlwaysOffSampler } = require("@opentelemetry/core");
75+
76+
const tracerProvider = new NodeTracerProvider({
77+
sampler: new AlwaysOffSampler()
78+
});
79+
```
80+
81+
### TraceIdRatioBased Sampler
82+
83+
Samples some percentage of traces, calculated deterministically using the trace ID.
84+
Any trace that would be sampled at a given percentage will also be sampled at any higher percentage.
85+
86+
The `TraceIDRatioSampler` may be used with the `ParentBasedSampler` to respect the sampled flag of an incoming trace.
87+
88+
```js
89+
const { NodeTracerProvider } = require("@opentelemetry/sdk-trace-node");
90+
const { TraceIdRatioBasedSampler } = require("@opentelemetry/core");
91+
92+
const tracerProvider = new NodeTracerProvider({
93+
// See details of ParentBasedSampler below
94+
sampler: new ParentBasedSampler({
95+
// Trace ID Ratio Sampler accepts a positional argument
96+
// which represents the percentage of traces which should
97+
// be sampled.
98+
root: new TraceIdRatioBasedSampler(0.5)
99+
});
100+
});
101+
```
102+
103+
### ParentBased Sampler
104+
105+
- This is a composite sampler. `ParentBased` helps distinguished between the
106+
following cases:
107+
- No parent (root span).
108+
- Remote parent with `sampled` flag `true`
109+
- Remote parent with `sampled` flag `false`
110+
- Local parent with `sampled` flag `true`
111+
- Local parent with `sampled` flag `false`
112+
113+
Required parameters:
114+
115+
- `root(Sampler)` - Sampler called for spans with no parent (root spans)
116+
117+
Optional parameters:
118+
119+
- `remoteParentSampled(Sampler)` (default: `AlwaysOn`)
120+
- `remoteParentNotSampled(Sampler)` (default: `AlwaysOff`)
121+
- `localParentSampled(Sampler)` (default: `AlwaysOn`)
122+
- `localParentNotSampled(Sampler)` (default: `AlwaysOff`)
123+
124+
|Parent| parent.isRemote() | parent.isSampled()| Invoke sampler|
125+
|--|--|--|--|
126+
|absent| n/a | n/a |`root()`|
127+
|present|true|true|`remoteParentSampled()`|
128+
|present|true|false|`remoteParentNotSampled()`|
129+
|present|false|true|`localParentSampled()`|
130+
|present|false|false|`localParentNotSampled()`|
131+
132+
```js
133+
const { NodeTracerProvider } = require("@opentelemetry/sdk-trace-node");
134+
const { ParentBasedSampler, AlwaysOffSampler, TraceIdRatioBasedSampler } = require("@opentelemetry/core");
135+
136+
const tracerProvider = new NodeTracerProvider({
137+
sampler: new ParentBasedSampler({
138+
// By default, the ParentBasedSampler will respect the parent span's sampling
139+
// decision. This is configurable by providing a different sampler to use
140+
// based on the situation. See configuration details above.
141+
//
142+
// This will delegate the sampling decision of all root traces (no parent)
143+
// to the TraceIdRatioBasedSampler.
144+
// See details of TraceIdRatioBasedSampler above.
145+
root: new TraceIdRatioBasedSampler(0.5)
146+
})
147+
});
148+
```
149+
49150
## Example
50151

51152
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.

‎packages/opentelemetry-sdk-trace-base/src/IdGenerator.ts

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
/*
2+
* Copyright The OpenTelemetry Authors
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* https://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
17+
/** IdGenerator provides an interface for generating Trace Id and Span Id */
18+
export interface IdGenerator {
19+
/** Returns a trace ID composed of 32 lowercase hex characters. */
20+
generateTraceId(): string;
21+
/** Returns a span ID composed of 16 lowercase hex characters. */
22+
generateSpanId(): string;
23+
}

0 commit comments

Comments
 (0)