@opentelemetry/sdk-trace-base

What is @opentelemetry/sdk-trace-base?

The @opentelemetry/sdk-trace-base package is part of the OpenTelemetry JavaScript SDK, which provides the core functionality for tracing. It allows developers to collect and export trace data to various backends for analysis and visualization. The package includes base classes and interfaces for implementing custom trace exporters, span processors, and configuration.

What are @opentelemetry/sdk-trace-base's main functionalities?

Basic Tracer Provider Setup

This code sets up a basic tracer provider with a simple span processor that exports spans to the console. It's the starting point for setting up OpenTelemetry tracing in an application.

const { BasicTracerProvider, SimpleSpanProcessor } = require('@opentelemetry/sdk-trace-base');
const { ConsoleSpanExporter } = require('@opentelemetry/tracing');

const provider = new BasicTracerProvider();
const consoleExporter = new ConsoleSpanExporter();
provider.addSpanProcessor(new SimpleSpanProcessor(consoleExporter));
provider.register();

Custom Span Processor

This code demonstrates how to create a custom span processor by extending the SpanProcessor class from the @opentelemetry/sdk-trace-base package. Developers can add custom logic for handling spans on start, on end, and during shutdown.

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

class MySpanProcessor extends SpanProcessor {
  onStart(span) {
    // Custom logic for when a span starts.
  }

  onEnd(span) {
    // Custom logic for when a span ends.
  }

  shutdown() {
    // Custom logic for shutdown.
  }
}

Configuring a Tracer Provider

This code snippet shows how to configure a tracer provider with a specific span processor and exporter. It's a common pattern for initializing tracing in an application with OpenTelemetry.

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

const provider = new BasicTracerProvider();
const exporter = new ConsoleSpanExporter();
const processor = new SimpleSpanProcessor(exporter);

provider.addSpanProcessor(processor);
provider.register();

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.

README

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 for asynchronous invocations or distributed-context out-of-the-box.

For automated instrumentation for Node.js, please see @opentelemetry/sdk-trace-node.

Installation

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

Usage

const opentelemetry = 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.
new BasicTracerProvider().register();

// To create a span in a trace, we used the global singleton tracer to start a new span.
const span = opentelemetry.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).

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.