Skip to content

Latest commit

 

History

History
354 lines (259 loc) · 22.7 KB

README.md

File metadata and controls

354 lines (259 loc) · 22.7 KB
Raw

Getting Started   •   API and SDK Reference

GitHub release (latest by date including pre-releases) Codecov Status license
Build Status Beta

Contributing   •   Examples

About this project

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

Quick Start

The following describes how to set up tracing for a basic web application. For more detailed documentation, see the website at https://opentelemetry.io/docs/instrumentation/js/.

Installation

Dependencies with the latest tag on NPM should be compatible with each other. See the version compatibility matrix below for more information.

npm install --save @opentelemetry/api
npm install --save @opentelemetry/sdk-node
npm install --save @opentelemetry/auto-instrumentations-node

Note: auto-instrumentations-node is a meta package from opentelemetry-js-contrib that provides a simple way to initialize multiple Node.js instrumentations.

Set up Tracing

// tracing.js

'use strict'

const process = require('process');
const opentelemetry = require('@opentelemetry/sdk-node');
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
const { ConsoleSpanExporter } = require('@opentelemetry/sdk-trace-base');
const { Resource } = require('@opentelemetry/resources');
const { SEMRESATTRS_SERVICE_NAME } = require('@opentelemetry/semantic-conventions');

// configure the SDK to export telemetry data to the console
// enable all auto-instrumentations from the meta package
const traceExporter = new ConsoleSpanExporter();
const sdk = new opentelemetry.NodeSDK({
  resource: new Resource({
    [SEMRESATTRS_SERVICE_NAME]: 'my-service',
  }),
  traceExporter,
  instrumentations: [getNodeAutoInstrumentations()]
});

// initialize the SDK and register with the OpenTelemetry API
// this enables the API to record telemetry
sdk.start();

// gracefully shut down the SDK on process exit
process.on('SIGTERM', () => {
  sdk.shutdown()
    .then(() => console.log('Tracing terminated'))
    .catch((error) => console.log('Error terminating tracing', error))
    .finally(() => process.exit(0));
});

Run Your Application

node -r ./tracing.js app.js

The above example will emit auto-instrumented telemetry about your Node.js application to the console. For a more in-depth example, see the Getting Started Guide. For more information about automatic instrumentation see @opentelemetry/sdk-trace-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/sdk-trace-base

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 v22 ✔️
Node.JS v20 ✔️
Node.JS v18 ✔️
Node.JS v16 ✔️
Node.JS v14 ✔️
Older Node Versions See Node Support
Web Browsers See Browser Support below

Node Support

Only Node.js Active or Maintenance LTS versions are supported. Previous versions of node may work, but they are not tested by OpenTelemetry and they are not guaranteed to work. Note that versions of Node.JS v8 prior to v8.12.0 will NOT work, because OpenTelemetry Node depends on the perf_hooks module introduced in v8.5.0 and performance.timeOrigin that is set correctly starting in v8.12.0.

Browser Support

Important

Client instrumentation for the browser is experimental and mostly unspecified. If you are interested in helping out, get in touch with the Client Instrumentation SIG.

There is currently no list of officially supported browsers. OpenTelemetry is developed using standard web technologies and aims to work in currently supported versions of major browsers.

Package Version Compatibility

OpenTelemetry is released as a set of distinct packages in 3 categories: API, stable SDK, and experimental. The API is located at /api, the stable SDK packages are in the /packages directory, and the experimental packages are listed in the /experimental/packages directory. There may also be API packages for experimental signals in the experimental directory. All stable packages are released with the same version, and all experimental packages are released with the same version. The below table describes which versions of each set of packages are expected to work together.

Stable Packages Experimental Packages
1.21.x 0.48.x
1.20.x 0.47.x
1.19.x 0.46.x
1.18.x 0.45.x
1.17.x 0.44.x
Older version compatibility matrix
Stable Packages Experimental Packages
1.16.x 0.42.x
1.15.x 0.41.x
1.14.x 0.40.x
1.13.x 0.39.x
1.12.x 0.38.x
1.11.x 0.37.x
1.10.x 0.36.x
1.9.x 0.35.x
1.8.x (this and later versions require API >=1.3.0 for metrics)0.34.x
1.7.x 0.33.x
1.6.x 0.32.x
1.5.x 0.31.x
1.4.x 0.30.x
1.3.x 0.29.x
1.2.x 0.29.x
1.1.x 0.28.x
1.0.x 0.27.x
1.0.x (this and later versions require API >=1.0.0 for traces)0.26.x

Versioning

The current version for each package can be found in the respective package.json file for that module. For additional details see the versioning and stability document in the specification.

Feature Status

Signal API Status SDK Status
Tracing Stable Stable
Metrics Stable Stable
Logs Development Development

For a more detailed breakdown of feature support see the specification compliance matrix.

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.

Community members

Maintainers (@open-telemetry/javascript-maintainers)

Find more about the maintainer role in the community repository.

Approvers (@open-telemetry/javascript-approvers)

Find more about the approver role in the community repository.

Triager (@open-telemetry/javascript-triagers)

Find more about the triager role in the community repository.

Emeriti

Find more about the emeritus role in community repository.

Thanks to all the people who already contributed

Repo contributors

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/sdk-trace-base This module provides a full control over instrumentation and span creation. It doesn't load async_hooks or any instrumentation by default. It is intended for use both on the server and in the browser.
@opentelemetry/sdk-metrics This module provides instruments and meters for reporting of time series data.
@opentelemetry/sdk-trace-node This module provides automatic tracing for Node.js applications. It is intended for use on the server only.
@opentelemetry/sdk-trace-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

OpenTelemetry can collect tracing data automatically using instrumentations.

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

Currently, OpenTelemetry supports automatic tracing for:

Node Instrumentations

Core
Contrib

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

Web Instrumentations

Core
Contrib

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

Shims

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

Useful links

License

Apache 2.0 - See LICENSE for more information.