Package Exports

@opentelemetry/api

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@opentelemetry/api) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

OpenTelemetry API for JavaScript

This package provides everything needed to interact with the OpenTelemetry API, including all TypeScript interfaces, enums, and no-op implementations. It is intended for use both on the server and in the browser.

Quick Start

To get started tracing you need to install the SDK and plugins, create a TracerProvider, and register it with the API.

Install Dependencies

$ # Install tracing dependencies
$ npm install \
    @opentelemetry/core \
    @opentelemetry/node \
    @opentelemetry/tracing \
    @opentelemetry/exporter-jaeger \ # add exporters as needed
    @opentelemetry/plugin-http # add plugins as needed

$ # Install metrics dependencies
$ npm install \
    @opentelemetry/metrics \
    @opentelemetry/exporter-prometheus # add exporters as needed

Initialize the SDK

Before any other module in your application is loaded, you must initialize the global tracer and meter providers. If you fail to initialize a provider, no-op implementations will be provided to any library which acquires them from the API.

To collect traces and metrics, you will have to tell the SDK where to export telemetry data to. This example uses Jaeger and Prometheus, but exporters exist for other tracing backends. If you're not sure if there is an exporter for your tracing backend, contact your tracing provider.

Tracing

const { NodeTracerProvider } = require("@opentelemetry/node");
const { SimpleSpanProcessor } = require("@opentelemetry/tracing");
const { JaegerExporter } = require("@opentelemetry/exporter-jaeger");

const tracerProvider = new NodeTracerProvider();

/**
 * The SimpleSpanProcessor does no batching and exports spans
 * immediately when they end. For most production use cases,
 * OpenTelemetry recommends use of the BatchSpanProcessor.
 */
tracerProvider.addSpanProcessor(
  new SimpleSpanProcessor(
    new JaegerExporter(
      /* export options */
    )
  )
);

/**
 * Registering the provider with the API allows it to be discovered
 * and used by instrumentation libraries. The OpenTelemetry API provides
 * methods to set global SDK implementations, but the default SDK provides
 * a convenience method named `register` which registers sane defaults
 * for you.
 *
 * By default the NodeTracerProvider uses Trace Context for propagation
 * and AsyncHooksScopeManager for context management. To learn about
 * customizing this behavior, see API Registration Options below.
 */
tracerProvider.register();

Metrics

const api = require("@opentelemetry/api");
const { MeterProvider } = require("@opentelemetry/metrics");
const { PrometheusExporter } = require("@opentelemetry/exporter-prometheus");

const meterProvider = new MeterProvider({
  // The Prometheus exporter runs an HTTP server which
  // the Prometheus backend scrapes to collect metrics.
  exporter: new PrometheusExporter({ startServer: true }),
  interval: 1000,
});

/**
 * Registering the provider with the API allows it to be discovered
 * and used by instrumentation libraries.
 */
api.metrics.setGlobalMeterProvider(meterProvider);

Advanced Use

API Registration Options

If you prefer to choose your own propagator or context manager, you may pass an options object into the tracerProvider.register() method. Omitted or undefined options will be replaced by a default value and null values will be skipped.

const { B3Propagator } = require("@opentelemetry/core");

tracerProvider.register({
  // Use B3 Propagation
  propagator: new B3Propagator(),

  // Skip registering a default context manager
  contextManager: null,
})

API Methods

If you are writing an instrumentation library, or prefer to call the API methods directly rather than using the register method on the Tracer/Meter Provider, OpenTelemetry provides direct access to the underlying API methods through the @opentelemetry/api package. API entry points are defined as global singleton objects trace, metrics, propagation, and context which contain methods used to initialize SDK implementations and acquire resources from the API.

const api = require("@opentelemetry/api")

/* Initialize TraceProvider */
api.trace.setGlobalTracerProvider(traceProvider);
/* returns traceProvider (no-op if a working provider has not been initialized) */
api.trace.getTracerProvider();
/* returns a tracer from the registered global tracer provider (no-op if a working provider has not been initialized); */
api.trace.getTracer(name, version);

/* Initialize MeterProvider */
api.metrics.setGlobalMeterProvider(meterProvider);
/* returns meterProvider (no-op if a working provider has not been initialized) */
api.metrics.getMeterProvider();
/* returns a meter from the registered global meter provider (no-op if a working provider has not been initialized); */
api.metrics.getMeter(name, version);

/* Initialize Propagator */
api.propagation.setGlobalPropagator(httpTraceContextPropagator)

/* Initialize Context Manager */
api.context.setGlobalContextManager(asyncHooksContextManager);

Library Authors

Library authors need only to depend on the @opentelemetry/api package and trust that the application owners which use their library will initialize an appropriate SDK.

const api = require("@opentelemetry/api");

const tracer = api.trace.getTracer("my-library-name", "0.2.3");

async function doSomething() {
  const span = tracer.startSpan("doSomething", { parent: tracer.getCurrentSpan() });
  try {
    const result = await doSomethingElse();
    span.end();
    return result;
  } catch (err) {
    span.setStatus({
      // use an appropriate status code here
      code: api.CanonicalCode.INTERNAL,
      message: err.message,
    });
    span.end();
    return null;
  }
}

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 on gitter

License

Apache 2.0 - See LICENSE for more information.