@opentelemetry/api
Advanced tools
Package description
The @opentelemetry/api package provides a set of APIs to instrument JavaScript applications for telemetry purposes. It allows developers to collect traces and metrics from their applications, which can then be exported to various observability backends for monitoring and analysis. The API is designed to be minimal, extensible, and vendor-neutral.
Tracing
This feature allows the creation and management of traces to monitor the flow of a request through various services. The code sample demonstrates how to create a tracer, start a new span, and then end the span.
const { trace } = require('@opentelemetry/api');
const tracer = trace.getTracer('example-tracer');
const span = tracer.startSpan('example-span');
span.end();Context Propagation
This feature enables the propagation of context information across asynchronous operations or service boundaries. The code sample shows how to associate a span with a context and execute a function within this context.
const { context, trace } = require('@opentelemetry/api');
const currentContext = context.active();
const span = trace.getTracer('example-tracer').startSpan('example-span');
context.with(trace.setSpan(currentContext, span), () => {
// Your synchronous or asynchronous operation here
span.end();
});Metrics
This feature supports the collection of quantitative measurements of operational events, such as request counts. The code sample illustrates how to create a meter, define a counter metric, and increment the counter.
const { metrics } = require('@opentelemetry/api');
const meter = metrics.getMeter('example-meter');
const counter = meter.createCounter('example-counter');
counter.add(1);Jaeger client is a package for tracing applications and sending the traces to Jaeger, a distributed tracing system. Unlike @opentelemetry/api, which is designed to be vendor-neutral and supports multiple backends, jaeger-client is specifically tailored for integration with Jaeger.
Prom-client is a package for collecting metrics in Node.js applications and exporting them to Prometheus, a monitoring and alerting toolkit. While @opentelemetry/api provides a more general approach to metrics collection compatible with various backends, prom-client is specifically focused on Prometheus integration.
Zipkin-js is a library for instrumenting Node.js applications for distributed tracing with Zipkin, a distributed tracing system. It offers functionality similar to the tracing aspects of @opentelemetry/api but is dedicated to Zipkin integration, whereas @opentelemetry/api aims for broader compatibility with different observability tools.
Changelog
1.1.0
opentelemetry-resources
exporter-trace-otlp-http, opentelemetry-core
instrumentation-http
opentelemetry-core, opentelemetry-exporter-jaeger
exporter-trace-otlp-grpc, exporter-trace-otlp-http, exporter-trace-otlp-proto, opentelemetry-context-async-hooks, opentelemetry-context-zone-peer-dep, opentelemetry-core, opentelemetry-exporter-jaeger, opentelemetry-exporter-zipkin, opentelemetry-propagator-b3, opentelemetry-propagator-jaeger, opentelemetry-resources, opentelemetry-sdk-trace-base, opentelemetry-sdk-trace-node, opentelemetry-sdk-trace-web, opentelemetry-shim-opentracing
opentelemetry-sdk-trace-web
exporter-trace-otlp-http, exporter-trace-otlp-proto
exporter-trace-otlp-grpc, exporter-trace-otlp-http, exporter-trace-otlp-proto, opentelemetry-core, opentelemetry-exporter-jaeger, opentelemetry-sdk-trace-base
opentelemetry-propagator-jaeger
exporter-trace-otlp-grpc, exporter-trace-otlp-http, exporter-trace-otlp-proto
opentelemetry-context-zone-peer-dep, opentelemetry-context-zone, opentelemetry-core, opentelemetry-exporter-zipkin, opentelemetry-propagator-b3, opentelemetry-resources, opentelemetry-sdk-trace-base, opentelemetry-sdk-trace-web, opentelemetry-semantic-conventions
exporter-trace-otlp-grpc, exporter-trace-otlp-http, exporter-trace-otlp-proto
opentelemetry-sdk-trace-base
opentelemetry-core
opentelemetry-exporter-jaeger
opentelemetry-resources
opentelemetry-propagator-jaeger
opentelemetry-exporter-zipkin, opentelemetry-sdk-trace-web
exporter-trace-otlp-grpc
opentelemetry-context-async-hooks
opentelemetry-context-async-hooks, opentelemetry-sdk-trace-node
opentelemetry-sdk-trace-base
exporter-trace-otlp-http, opentelemetry-context-zone-peer-dep, opentelemetry-context-zone, opentelemetry-core, opentelemetry-exporter-zipkin, opentelemetry-propagator-b3, opentelemetry-resources, opentelemetry-sdk-trace-base, opentelemetry-sdk-trace-web, opentelemetry-semantic-conventions
opentelemetry-core
exporter-trace-otlp-grpc, exporter-trace-otlp-http, exporter-trace-otlp-proto, opentelemetry-exporter-jaeger, opentelemetry-exporter-zipkin, opentelemetry-propagator-b3, opentelemetry-resources, opentelemetry-sdk-trace-base, opentelemetry-sdk-trace-web, opentelemetry-semantic-conventions
exporter-trace-otlp-grpc, exporter-trace-otlp-http, exporter-trace-otlp-proto, opentelemetry-context-async-hooks, opentelemetry-context-zone-peer-dep, opentelemetry-context-zone, opentelemetry-core, opentelemetry-exporter-jaeger, opentelemetry-exporter-zipkin, opentelemetry-propagator-b3, opentelemetry-propagator-jaeger, opentelemetry-resources, opentelemetry-sdk-trace-base, opentelemetry-sdk-trace-node, opentelemetry-sdk-trace-web, opentelemetry-semantic-conventions, opentelemetry-shim-opentracing, template
opentelemetry-context-async-hooks, opentelemetry-context-zone-peer-dep, opentelemetry-context-zone, opentelemetry-core, opentelemetry-exporter-jaeger, opentelemetry-exporter-zipkin, opentelemetry-propagator-b3, opentelemetry-propagator-jaeger, opentelemetry-resources, opentelemetry-sdk-trace-base, opentelemetry-sdk-trace-node, opentelemetry-sdk-trace-web, opentelemetry-semantic-conventions, opentelemetry-shim-opentracing
opentelemetry-exporter-jaeger, opentelemetry-exporter-zipkin, opentelemetry-resources, opentelemetry-semantic-conventions
opentelemetry-sdk-trace-web
Readme
API Documentation • Getting In Touch (GitHub Discussions)
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.
The methods in this package perform no operations by default. This means they can be safely called by a library or end-user application whether there is an SDK registered or not. In order to generate and export telemetry data, you will also need an SDK such as the OpenTelemetry JS SDK.
Note: ECMAScript 5+ compatibility is for this package only. Please refer to the documentation for the SDK you are using to determine its minimum ECMAScript version.
Note for library authors: Only your end users will need an OpenTelemetry SDK. If you wish to support OpenTelemetry in your library, you only need to use the OpenTelemetry API. For more information, please read the tracing documentation.
npm install @opentelemetry/api @opentelemetry/sdk-trace-base
In order to get started with tracing, you will need to first register an SDK. The SDK you are using may provide a convenience method which calls the registration methods for you, but if you would like to call them directly they are documented here: sdk registration methods.
Once you have registered an SDK, you can start and end spans. A simple example of basic SDK registration and tracing a simple operation is below. The example should export spans to the console once per second. For more information, see the tracing documentation.
const { trace } = require("@opentelemetry/api");
const { BasicTracerProvider, ConsoleSpanExporter, SimpleSpanProcessor } = require("@opentelemetry/sdk-trace-base");
// Create and register an SDK
const provider = new BasicTracerProvider();
provider.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter()));
trace.setGlobalTracerProvider(provider);
// Acquire a tracer from the global tracer provider which will be used to trace the application
const name = 'my-application-name';
const version = '0.1.0';
const tracer = trace.getTracer(name, version);
// Trace your application by creating spans
async function operation() {
const span = tracer.startSpan("do operation");
// mock some work by sleeping 1 second
await new Promise((resolve, reject) => {
setTimeout(resolve, 1000);
})
span.end();
}
async function main() {
while (true) {
await operation();
}
}
main();
Because the npm installer and node module resolution algorithm could potentially allow two or more copies of any given package to exist within the same node_modules structure, the OpenTelemetry API takes advantage of a variable on the global object to store the global API. When an API method in the API package is called, it checks if this global API exists and proxies calls to it if and only if it is a compatible API version. This means if a package has a dependency on an OpenTelemetry API version which is not compatible with the API used by the end user, the package will receive a no-op implementation of the API.
No breaking changes
api.context.bind arguments reversed and context is now a required argument.api.trace.wrapSpanContext with INVALID_SPAN_CONTEXT instead of using the NOOP_TRACER.TimedEvent which was not part of specHttpBaggage renamed to HttpBaggagePropagatorSpan#context renamed to Span#spanContextgetSpan/setSpan/getSpanContext/setSpanContext moved to trace namespacegetBaggage/setBaggage/createBaggage moved to propagation namespaceApache 2.0 - See LICENSE for more information.
FAQs
Public API for OpenTelemetry
We found that @opentelemetry/api demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
CISA launched a new project called Vulnrichment to enrich CVEs with details that help prioritize patching and mitigation efforts, as the NVD backlog of unenriched CVEs awaiting analysis surpasses 10,000.
Security News
Socket is joining forces with CISA and other industry leaders at the RSA Conference to sign the Secure by Design pledge, committing to uphold the highest security standards in our products.
Research
The Socket research team breaks down a sampling of malicious packages that download and execute files, among other suspicious behaviors, targeting the popular Discord platform.