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

OpenTelemetry Core

Built-in Propagators

HttpTraceContextPropagator 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 { HttpTraceContextPropagator } = require("@opentelemetry/core");

/* Set Global Propagator */
api.propagation.setGlobalPropagator(new HttpTraceContextPropagator());

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 { HttpBaggagePropagator } = require("@opentelemetry/core");

/* Set Global Propagator */
api.propagation.setGlobalPropagator(new HttpBaggagePropagator());

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/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/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/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()`

const { NodeTracerProvider } = require("@opentelemetry/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