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
$
$ npm install \
@opentelemetry/core \
@opentelemetry/node \
@opentelemetry/tracing \
@opentelemetry/exporter-jaeger \
@opentelemetry/plugin-http
$
$ npm install \
@opentelemetry/metrics \
@opentelemetry/exporter-prometheus
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();
tracerProvider.addSpanProcessor(
new SimpleSpanProcessor(
new JaegerExporter(
)
)
);
tracerProvider.register();
Metrics
const api = require("@opentelemetry/api");
const { MeterProvider } = require("@opentelemetry/metrics");
const { PrometheusExporter } = require("@opentelemetry/exporter-prometheus");
const meterProvider = new MeterProvider({
exporter: new PrometheusExporter({ startServer: true }),
interval: 1000,
});
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({
propagator: new B3Propagator(),
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");
api.trace.setGlobalTracerProvider(traceProvider);
api.trace.getTracerProvider();
api.trace.getTracer(name, version);
api.metrics.setGlobalMeterProvider(meterProvider);
api.metrics.getMeterProvider();
api.metrics.getMeter(name, version);
api.propagation.setGlobalPropagator(httpTraceContextPropagator);
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({
code: api.CanonicalCode.INTERNAL,
message: err.message,
});
span.end();
return null;
}
}
Useful links
License
Apache 2.0 - See LICENSE for more information.