@opentelemetry/core

What is @opentelemetry/core?

The @opentelemetry/core package is part of the OpenTelemetry project, which provides a set of APIs, libraries, agents, and instrumentation to provide observability for applications. Specifically, the core package includes fundamental building blocks for creating and managing telemetry data (metrics, traces, logs) and is designed to be used by other OpenTelemetry packages to create a complete observability framework.

What are @opentelemetry/core's main functionalities?

Context Management

This feature allows for the propagation of context information across asynchronous operations in your application. The context is used to store and access current execution-specific data, such as active span in tracing.

const { context, ROOT_CONTEXT } = require('@opentelemetry/core');
const ctx = context.active();
const newContext = context.with(ROOT_CONTEXT, () => {});

Propagation

Propagation is used to transmit context (e.g., traces and correlations) across process boundaries. It includes utilities to inject and extract context information from carriers in various formats.

const { propagation, defaultTextMapGetter } = require('@opentelemetry/core');
const carrier = {};
const context = propagation.extract(ROOT_CONTEXT, carrier, defaultTextMapGetter);

Instrumentation

Instrumentation is a core part of OpenTelemetry, allowing developers to collect telemetry data (metrics, logs, and traces) from their applications. This feature provides diagnostic logging capabilities.

const { diag } = require('@opentelemetry/core');
diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.INFO);

Other packages similar to @opentelemetry/core

jaeger-client

Jaeger client is a distributed tracing system. It's similar to @opentelemetry/core in that it provides tracing capabilities, but it's specifically designed for use with the Jaeger backend. Unlike OpenTelemetry, which aims to be vendor-neutral, Jaeger client is tailored for Jaeger.

prom-client

Prom-client is a client for the Prometheus monitoring system, focusing on gathering metrics. It's similar to the metrics collection part of @opentelemetry/core but is specifically designed for use with Prometheus rather than being part of a broader observability framework.

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

• OpenTelemetry Core
  • Built-in Implementations
    • Built-in Propagators
      • W3CTraceContextPropagator Propagator
      • Composite Propagator
      • Baggage Propagator
    • Built-in Sampler
      • AlwaysOn Sampler
      • AlwaysOff Sampler
      • TraceIdRatioBased Sampler
      • ParentBased Sampler
  • Useful links
  • License

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

Changelog

1.3.0

:boom: Breaking Change

• chore: remove unused InstrumentationConfig#path #2944 @flarna

:rocket: (Enhancement)

• feat(ConsoleSpanExporter): export span links #2917 @trentm
• feat: warn when hooked module is already loaded #2926 @nozik
• feat: implement OSDetector #2927 @rauno56
• feat: implement HostDetector #2921 @rauno56
• feat(opentelemetry-core): add InstrumentationScope #2959 @pichlermarc

:bug: (Bug Fix)

• fix(sdk-web): parse url with relative url string #2972 @legendecas