@opentelemetry/sdk-trace-base

OpenTelemetry Tracing SDK

The tracing module contains the foundation for all tracing SDKs of opentelemetry-js.

Used standalone, this module provides methods for manual instrumentation of code, offering full control over span creation for client-side JavaScript (browser) and Node.js.

It does not provide automated instrumentation of known libraries, context propagation or distributed-context out-of-the-box.

For a TracerProvider that includes default context management and propagation for Node.js, please see @opentelemetry/sdk-trace-node.

For a TracerProvider that includes default context management and propagation for Browser, please see @opentelemetry/sdk-trace-web.

Installation

npm install --save @opentelemetry/api
npm install --save @opentelemetry/sdk-trace-base

Usage

const { trace } = require('@opentelemetry/api');
const { BasicTracerProvider } = require('@opentelemetry/sdk-trace-base');

// To start a trace, you first need to initialize the Tracer provider.
// NOTE: The default OpenTelemetry tracer provider does not record any tracing information.
//       Registering a working tracer provider allows the API methods to record traces.
trace.setGlobalTracerProvider(new BasicTracerProvider());

// Important: requires a context manager and propagator to be registered manually.
// propagation.setGlobalPropagator(propagator);     // replace `propagator` with your `TextMapPropagator`, for example: `W3CTraceContextPropagator` from `@openetelemetry/core`
// context.setGlobalContextManager(contextManager); // replace `contextManager` with your `ContextManager`: `AsyncLocalStorageContextManager` from `@openetelemetry/async-hooks`

// To create a span in a trace, we used the global singleton tracer to start a new span.
const span = trace.getTracer('default').startSpan('foo');

// Set a span attribute
span.setAttribute('key', 'value');

// We must end the spans so they become available for exporting.
span.end();

Config

Tracing configuration is a merge of user supplied configuration with both the default configuration as specified in 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

const {
  AlwaysOnSampler,
  BasicTracerProvider,
} = require("@opentelemetry/sdk-trace-base");

const tracerProvider = new BasicTracerProvider({
  sampler: new AlwaysOnSampler()
});

AlwaysOff Sampler

Doesn't sample any trace, regardless of upstream sampling decisions.

const {
  AlwaysOffSampler,
  BasicTracerProvider,
} = require("@opentelemetry/sdk-trace-base");

const tracerProvider = new BasicTracerProvider({
  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 {
  BasicTracerProvider,
  TraceIdRatioBasedSampler,
} = require("@opentelemetry/sdk-trace-base");

const tracerProvider = new BasicTracerProvider({
  // 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 {
  AlwaysOffSampler,
  BasicTracerProvider,
  ParentBasedSampler,
  TraceIdRatioBasedSampler,
} = require("@opentelemetry/sdk-trace-base");

const tracerProvider = new BasicTracerProvider({
  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 for an end-to-end example, including exporting created spans.

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.

Changelog

2.2.0

:bug: Bug Fixes

• fix(core): avoid leaking Node.js types via unrefTimer() util #5986 @pichlermarc
• fix(core): avoid leaking Node.js types via otperformance #5987 @pichlermarc
  • important: this bug fix may be breaking for certain uses of otperformance
    • otperformance.now() and otperformance.timeOrigin are not affected.
    • the previously used type was incorrect and overly broad, leading to unexpected run-time behavior runtimes that are not Node.js.
    • these problems are now caught on compile-time: if you have been using this API and this change is breaking to you, please consider using your target platform's performance implementation instead.

:house: Internal

• test(shim-opentracing): add comparison thresholds in flaky assertions #5974 @cjihrig
• test(exporter-jaeger): clean up OTEL_EXPORTER_JAEGER_AGENT_PORT between tests #6003 @cjihrig
• test(sdk-trace-base): ensure environment variables are cleaned up between tests #6011 @cjihrig
• perf(opentelemetry-core): optimize attribute serialization #5866 @43081j
• test: test Node.js 25 in CI #6019 @cjihrig

Similar packages

Other packages similar to @opentelemetry/sdk-trace-base

jaeger-client

The jaeger-client package is a Node.js client for Jaeger, a distributed tracing system. It provides similar functionality to @opentelemetry/sdk-trace-base, allowing developers to send trace data to a Jaeger backend. However, it is specific to Jaeger, whereas OpenTelemetry provides a more vendor-neutral approach.

zipkin-javascript-opentracing

This package is an OpenTracing-compatible tracer implementation for Zipkin in JavaScript. Like @opentelemetry/sdk-trace-base, it enables tracing and exporting trace data but is tailored for integration with Zipkin, a different distributed tracing system.

lightstep-tracer

Lightstep's tracer library for JavaScript is designed to monitor and trace application performance. It is similar to @opentelemetry/sdk-trace-base in that it collects trace data, but it is specifically built to work with Lightstep's performance monitoring platform.