@opentelemetry/sdk-metrics

What is @opentelemetry/sdk-metrics?

The @opentelemetry/sdk-metrics package is part of the OpenTelemetry JavaScript SDK, which provides tools for collecting and exporting metrics data from your applications. It allows you to create and manage various types of metrics such as counters, observers, and histograms, and to export this data to different backends for analysis and monitoring.

What are @opentelemetry/sdk-metrics's main functionalities?

Creating a Meter

This feature allows you to create a Meter instance from the MeterProvider. The Meter is used to create and manage metrics.

{"const { MeterProvider } = require('@opentelemetry/sdk-metrics');
const meterProvider = new MeterProvider();
const meter = meterProvider.getMeter('your-meter-name');"}

Creating a Counter Metric

This feature allows you to create a Counter metric, which can be used to record the number of times an event occurs.

{"const { MeterProvider } = require('@opentelemetry/sdk-metrics');
const meterProvider = new MeterProvider();
const meter = meterProvider.getMeter('your-meter-name');
const counter = meter.createCounter('requests', {
  description: 'Count of requests received'
});"}

Recording Metrics

This feature allows you to record metrics data. In this example, we increment the counter by 1 for the '/home' route.

{"const { MeterProvider } = require('@opentelemetry/sdk-metrics');
const meterProvider = new MeterProvider();
const meter = meterProvider.getMeter('your-meter-name');
const counter = meter.createCounter('requests');
counter.add(1, { route: '/home' });"}

Exporting Metrics

This feature allows you to export the collected metrics data. Here, we use the ConsoleMetricExporter to print metrics to the console at a regular interval.

{"const { MeterProvider } = require('@opentelemetry/sdk-metrics');
const { ConsoleMetricExporter } = require('@opentelemetry/exporter-metrics-console');
const meterProvider = new MeterProvider({
  exporter: new ConsoleMetricExporter(),
  interval: 1000
});
const meter = meterProvider.getMeter('your-meter-name');"}

Other packages similar to @opentelemetry/sdk-metrics

prom-client

The prom-client package is a Prometheus client for Node.js that supports the creation, collection, and exposition of metrics data. It is similar to @opentelemetry/sdk-metrics in that it provides a way to collect metrics from your application, but it is specifically designed to work with Prometheus.

metrics

The metrics package provides a set of tools for collecting and reporting various types of metrics from your Node.js applications. It is similar to @opentelemetry/sdk-metrics but has a different API and does not integrate with the OpenTelemetry ecosystem.

appmetrics

Appmetrics is a package for monitoring and reporting runtime and performance metrics in Node.js applications. It offers functionality similar to @opentelemetry/sdk-metrics but is focused on providing built-in probes for various Node.js modules and runtime statistics.

README

OpenTelemetry Metrics SDK

This module contains the Metrics SDK of opentelemetry-js.

Used standalone, this module provides methods for manual instrumentation of code, offering full control over recording metrics for client-side JavaScript (browser) and Node.js.

It does not provide automated instrumentation of known libraries or host environment metrics out-of-the-box.

Installation

npm install --save @opentelemetry/api
npm install --save @opentelemetry/sdk-metrics

Usage

The basic setup of the SDK can be seen as followings:

const opentelemetry = require('@opentelemetry/api');
const { MeterProvider } = require('@opentelemetry/sdk-metrics');

// To create an instrument, you first need to initialize the Meter provider.
// NOTE: The default OpenTelemetry meter provider does not record any metric instruments.
//       Registering a working meter provider allows the API methods to record instruments.
opentelemetry.metrics.setGlobalMeterProvider(new MeterProvider());

// To record a metric event, we used the global singleton meter to create an instrument.
const counter = opentelemetry.metrics.getMeter('default').createCounter('foo');

// record a metric event.
counter.add(1, { attributeKey: 'attribute-value' });

In conditions, we may need to setup an async instrument to observe costly events:

// Creating an async instrument, similar to synchronous instruments
const observableCounter = opentelemetry.metrics.getMeter('default')
  .createObservableCounter('observable-counter');

// Register a single-instrument callback to the async instrument.
observableCounter.addCallback(async (observableResult) => {
  // ... do async stuff
  observableResult.observe(1, { attributeKey: 'attribute-value' });
});

// Register a multi-instrument callback and associate it with a set of async instruments.
opentelemetry.metrics.getMeter('default')
  .addBatchObservableCallback(batchObservableCallback, [ observableCounter ]);
async function batchObservableCallback(batchObservableResult) {
  // ... do async stuff
  batchObservableResult.observe(observableCounter, 1, { attributeKey: 'attribute-value' });
}

Views can be registered when instantiating a MeterProvider:

const meterProvider = new MeterProvider({
  views: [
    // override the bucket boundaries on `my.histogram` to [0, 50, 100]
    new View({ aggregation: new ExplicitBucketHistogramAggregation([0, 50, 100]), instrumentName: 'my.histogram'}),
    // rename 'my.counter' to 'my.renamed.counter'
    new View({ name: 'my.renamed.counter', instrumentName: 'my.counter'})
  ]
})

Example

See examples/prometheus for an end-to-end example, including exporting metrics.

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 in GitHub Discussions

License

Apache 2.0 - See LICENSE for more information.

Changelog

1.27.0

:rocket: (Enhancement)

• feat: add processors for adding session.id attribute to spans and logs #4972

:bug: (Bug Fix)

• fix(sdk-trace-base): avoid keeping non-string status.message on Span#setStatus() #4999 @pichlermarc
• fix(sdk-metrics): Add missing catch and handle error in promise of PeriodicExportingMetricReader #5006 @jj22ee
• fix(opentelemetry-core): confusing log extract of composite propagator #5017 @rv2673
• fix(propagator-aws-xray-*): move propagators back to contrib repository #4966 @pichlermarc
  • The specification prohibits hosting these packages in the core repository
  • @opentelemetry/propagator-aws-xray is now located in open-telemetry/opentelemetry-js-contrib
  • @opentelemetry/propagator-aws-xray-lambda is now located in open-telemetry/opentelemetry-js-contrib

:house: (Internal)

• deps: set @opentelemetry/api dependency min version to 1.3.0 in examples, experimental/packages, integration-tests and selenium-tests #4992
• refactor(sdk-metrics): replace MetricsAttributes with Attributes #5021 @david-luna
• refactor(instrumentation-http): replace SpanAttributes and MetricsAttributes with Attributes #5023 @david-luna
• chore(exporter-zipkin): remove usages of Span constructor #5030 @david-luna
• test(instrumentation-http): remove usages of new Span in tests #5035 @david-luna