---

Getting Started   •   API Documentation   •  

Contributing   •   Development Guide   •   Benchmarks   •   Examples

---

About this project

This is the JavaScript version of OpenTelemetry, a framework for collecting traces and metrics from applications.

Compatibility Matrix

API Version	Core version	Contrib Version
v1.0.0-rc.0	------	------
0.18.x	0.18.x	0.14.x
	0.17.x	------
	0.16.x	------
	0.15.x	0.13.x
	0.14.x	0.12.x
	0.13.x	------
	0.12.x	0.11.x
	0.11.x	0.10.x

Quick start

Application Owner

To get started tracing your own application, see the Getting Started Guide. For more information about automatic instrumentation see @opentelemetry/node, which provides auto-instrumentation for Node.js applications. If the automatic instrumentation does not suit your needs, or you would like to create manual traces, see @opentelemetry/tracing

Library Author

If you are a library author looking to build OpenTelemetry into your library, please see the documentation. As a library author, it is important that you only depend on properties and methods published on the public API. If you use any properties or methods from the SDK that are not officially a part of the public API, your library may break if an Application Owner uses a different SDK implementation.

Supported Runtimes

Platform Version	Supported
Node.JS v14	✅
Node.JS v12	✅
Node.JS v10	✅
Node.JS v8	See Node Support below
Web Browsers	✅ See Browser Support below

Node Support

Automated tests are run using the latest release of each currently active version of Node.JS. While Node.JS v8 is no longer supported by the Node.JS team, the latest version of Node.JS v8 is still included in our testing suite. Please note that versions of Node.JS v8 prior to v8.5.0 will NOT work, because OpenTelemetry Node depends on the perf_hooks module introduced in v8.5.0

Browser Support

Automated browser tests are run in the latest version of Headless Chrome. There is currently no list of officially supported browsers, but OpenTelemetry is developed using standard web technologies with wide support and should work in currently supported versions of major browsers.

Release Schedule

OpenTelemetry JS is under active development. This release isn't guaranteed to conform to a specific version of the specification, and future releases will not attempt to maintain backwards compatibility with the alpha release.

Component	Initial Version	Release Date
Tracing API	Alpha v0.1.0	October 14 2019
Tracing SDK (Node and Web)	Alpha v0.1.0	October 14 2019
Jaeger Trace Exporter	Alpha v0.1.0	October 14 2019
Trace Context Propagation	Alpha v0.1.0	October 14 2019
Zipkin Trace Exporter	Alpha v0.1.0	October 14 2019
OpenTracing Bridge	Alpha v0.1.0	October 14 2019
Metrics API	Alpha v0.2.0	November 04 2019
Metrics SDK	Alpha v0.2.0	November 04 2019
Prometheus Metric Exporter	Alpha v0.3.0	December 13 2019
Resources	Beta v0.5.0	March 16 2020
Metrics SDK (Complete)	Beta v0.5.0	March 16 2020
OpenCensus Bridge	Unknown	Unknown
Support for Tags/Baggage	Unknown	Unknown

Feature Status

Last updated March 2020

Feature	API Status	Specification Target	SDK Status
Tracing	Beta	v0.3	Beta
Metrics	Beta	v0.3	Beta
Context	Beta	v0.3	Beta
Propagation	Beta	v0.3	Beta
Baggage	Alpha	v0.3	Development
OpenTracing Bridge	N/A	v0.3	Beta
Resources	N/A	v0.3	Beta

See the project milestones for details on upcoming releases. The dates and features described here are estimates, and subject to change.

Contributing

We'd love your help!. Use tags up-for-grabs and good first issue to get started with the project. For instructions to build and make changes to this project, see the CONTRIBUTING guide.

We have a weekly SIG meeting! See the community page for meeting details and notes.

Approvers (@open-telemetry/js-approvers):

• Chengzhong Wu, Alibaba
• Gerhard Stöbich, Dynatrace
• John Bley, Splunk
• Mark Wolff, Microsoft
• Matthew Wear, LightStep
• Naseem K. Ullah, Transit
• Olivier Albertini, Ville de Montréal

Find more about the approver role in community repository.

Maintainers (@open-telemetry/js-maintainers):

• Bartlomiej Obecny, LightStep
• Daniel Dyla, Dynatrace
• Valentin Marchaud, Open Source Contributor

Find more about the maintainer role in community repository.

Thanks to all the people who already contributed

Thanks to all previous approvers and maintainers

• Daniel Khan, Dynatrace, Maintainer
• Mayur Kale, Google, Maintainer
• Brandon Gonzalez, LightStep, Approver
• Roch Devost, DataDog, Approver

Packages

API

Package	Description
@opentelemetry/api	This package provides TypeScript interfaces, enums and no-op implementations for the OpenTelemetry core trace and metrics model. It is intended for use both on the server and in the browser.
@opentelemetry/core	This package provides default and no-op implementations of the OpenTelemetry api for trace and metrics. It's intended for use both on the server and in the browser.

Implementation / SDKs

Package	Description
@opentelemetry/tracing	This module provides a full control over instrumentation and span creation. It doesn't load async_hooks or any instrumentation plugin by default. It is intended for use both on the server and in the browser.
@opentelemetry/metrics	This module provides instruments and meters for reporting of time series data.
@opentelemetry/node	This module provides automatic tracing for Node.js applications. It is intended for use on the server only.
@opentelemetry/web	This module provides automated instrumentation and tracing for Web applications. It is intended for use in the browser only.

Compatible Exporters

OpenTelemetry is vendor-agnostic and can upload data to any backend with various exporter implementations. Even though, OpenTelemetry provides support for many backends, vendors/users can also implement their own exporters for proprietary and unofficially supported backends.

See the OpenTelemetry registry for a list of exporters available.

Instrumentations & Plugins

OpenTelemetry can collect tracing data automatically using instrumentations. Vendors/Users can also create and use their own. Currently, OpenTelemetry supports automatic tracing for:

Node Instrumentations & Plugins

Core

• @opentelemetry/instrumentation-grpc previous @opentelemetry/plugin-grpc
• @opentelemetry/plugin-grpc-js
• @opentelemetry/instrumentation-http previous @opentelemetry/plugin-http and @opentelemetry/plugin-https

Contrib

These plugins are hosted at https://github.com/open-telemetry/opentelemetry-js-contrib/tree/master/plugins/node

• @opentelemetry/plugin-mongodb
• @opentelemetry/plugin-mysql
• @opentelemetry/plugin-pg
• @opentelemetry/plugin-pg-pool
• @opentelemetry/plugin-redis
• @opentelemetry/plugin-ioredis
• @opentelemetry/plugin-express
• @opentelemetry/plugin-dns
• @opentelemetry/instrumentation-hapi
• @opentelemetry/instrumentation-koa

Web Plugins

Core

• @opentelemetry/instrumentation-xml-http-request
• @opentelemetry/instrumentation-fetch

Contrib

These plugins are hosted at https://github.com/open-telemetry/opentelemetry-js-contrib/tree/master/plugins/web

• @opentelemetry/instrumentation-document-load
• @opentelemetry/instrumentation-user-interaction

To request automatic tracing support for a module not on this list, please file an issue. Alternatively, you can write an instrumentation yourself.

Shims

Package	Description
@opentelemetry/shim-opentracing	OpenTracing shim allows existing OpenTracing instrumentation to report to OpenTelemetry

Upgrade guidelines

0.17.0 to 0.18.0

• diag.setLogLevel is removed and LogLevel can be set by an optional second parameter to setLogger

PR-1975

• Breaking change - The resulting resource MUST have all attributes that are on any of the two input resources. If a key exists on both the old and updating resource, the value of the updating resource MUST be picked - previously it was opposite.

0.16.0 to 0.17.0

PR-1880 feat(diag-logger): introduce a new global level api.diag for internal diagnostic logging

PR-1925 feat(diag-logger): part 2 - breaking changes - remove api.Logger, api.NoopLogger, core.LogLevel, core.ConsoleLogger

• These PR's remove the previous Logger and LogLevel implementations and change the way you should use the replacement DiagLogger and DiagLogLevel, below are simple examples of how to change your existing usages.

Setting the global diagnostic logger

The new global api.diag provides the ability to set the global diagnostic logger setLogger() and logging level setLogLevel(), it is also a DiagLogger implementation and should be directly to log diagnostic messages.

All included logger references have been removed in preference to using the global api.diag directly, so you no longer need to pass around the logger instance via function parameters or included as part of the configuration for a component.

import { diag, DiagConsoleLogger, DiagLogLevel } from "@opentelemetry/api";
// Setting the default Global logger to use the Console
// And optionally change the logging level (Defaults to INFO)
diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.ERROR)

Using the logger anywhere in the code

import { diag } from "@opentelemetry/api";

// Remove or make optional the parameter and don't use it.
export function MyFunction() {
  diag.debug("...");
  diag.info("...");
  diag.warn("...");
  diag.error("...");
  diag.verbose("..");
}

Setting the logger back to a noop

import { diag } from "@opentelemetry/api";
diag.setLogger();

PR-1855 Use instrumentation loader to load plugins and instrumentations

• Providers do no load the plugins anymore. Also PluginLoader has been removed from providers, use registerInstrumentations instead

//Previously in node
const provider = new NodeTracerProvider({
  plugins: {
    '@grpc/grpc-js': {
      enabled: true,
      path: '@opentelemetry/plugin-grpc-js',
    },
  }
});

// Now
const provider = new NodeTracerProvider();
const { registerInstrumentations } = require('@opentelemetry/instrumentation');
registerInstrumentations({
  instrumentations: [
    {
      plugins: {
        '@grpc/grpc-js': {
          enabled: true,
          path: '@opentelemetry/plugin-grpc-js',
        },
      }
    }
  ],
  tracerProvider: provider,
});

// or if you want to load only default instrumentations / plugins
registerInstrumentations({
  tracerProvider: provider,
});

//Previously in browser
const provider = new WebTracerProvider({
  plugins: [
    new DocumentLoad()
  ]
});
// Now
const { registerInstrumentations } = require('@opentelemetry/instrumentation');
const provider = new WebTracerProvider();
registerInstrumentations({
  instrumentations: [
    new DocumentLoad(),
  ],
});

• registerInstrumentations supports loading old plugins and instrumentations together. It also supports setting tracer provider and meter provider on instrumentations

PR-1874 More specific API type names

Some types exported from "@opentelemetry/api" have been changed to be more specific.

• AttributeValue renamed to SpanAttributeValue
• Attributes renamed to SpanAttributes
• EntryTtl renamed to BaggageEntryTtl
• EntryValue renamed to BaggageEntryValue
• Status renamed to SpanStatus
• StatusCode renamed to SpanStatusCode

0.15.0 to 0.16.0

PR-1863 removed public attributes keepAlive and httpAgentOptions from nodejs CollectorTraceExporter and CollectorMetricExporter

0.14.0 to 0.15.0

PR-1764 removed some APIs from Tracer:

• Tracer.getCurrentSpan(): use api.getSpan(api.context.active())
• Tracer.withSpan(span): use api.context.with(api.setSpan(api.context.active(), span))
• Tracer.bind(target): use api.context.bind(target)

PR-1797 chore!: split metrics into its own api package:

• Any references to require("@opentelemetry/api").metrics will need to be changed to require("@opentelemetry/api-metrics").metrics

PR-1725 Use new gRPC default port

• The default port used by @opentelemetry/exporter-collector-grpc is changed from 55680 to 4317

PR-1749 chore: improve naming of span related context APIs

• Rename [gs]etActiveSpan() to [gs]etSpan()
• Rename setExtractedSpanContext() to setSpanContext()
• Rename getParentSpanContext() to getSpanContext()

Useful links

• For more information on OpenTelemetry, visit: https://opentelemetry.io/
• For help or feedback on this project, join us in GitHub Discussions

License

Apache 2.0 - See LICENSE for more information.