README
OpenTelemetry Core
This package provides default implementations of the OpenTelemetry API for trace and metrics. It's intended for use both on the server and in the browser.
Built-in Implementations
Built-in Propagators
W3CTraceContextPropagator Propagator
OpenTelemetry provides a text-based approach to propagate context to remote services using the W3C Trace Context HTTP headers.
const api = require("@opentelemetry/api");
const { W3CTraceContextPropagator } = require("@opentelemetry/core");
/* Set Global Propagator */
api.propagation.setGlobalPropagator(new W3CTraceContextPropagator());
Composite Propagator
Combines multiple propagators into a single propagator.
This is used as a default Propagator
const api = require("@opentelemetry/api");
const { CompositePropagator } = require("@opentelemetry/core");
/* Set Global Propagator */
api.propagation.setGlobalPropagator(new CompositePropagator());
Baggage Propagator
Provides a text-based approach to propagate baggage to remote services using the OpenTelemetry Baggage Propagation HTTP headers.
const api = require("@opentelemetry/api");
const { W3CBaggagePropagator } = require("@opentelemetry/core");
/* Set Global Propagator */
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
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.
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.
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
flagtrue
- Remote parent with
sampled
flagfalse
- Local parent with
sampled
flagtrue
- Local parent with
sampled
flagfalse
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()
|
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/
- For more about OpenTelemetry JavaScript: https://github.com/open-telemetry/opentelemetry-js
- For help or feedback on this project, join us in GitHub Discussions
License
Apache 2.0 - See LICENSE for more information.