@opentelemetry/metrics

OpenTelemetry Metrics SDK

OpenTelemetry metrics allow a user to collect data and export it to a metrics backend like Prometheus.

Installation

npm install --save @opentelemetry/metrics

Usage

Counter

Choose this kind of metric when the value is a quantity, the sum is of primary interest, and the event count and value distribution are not of primary interest. It is restricted to non-negative increments. Example uses for Counter:

• count the number of bytes received
• count the number of requests completed
• count the number of accounts created
• count the number of checkpoints run
• count the number of 5xx errors.

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

// Initialize the Meter to capture measurements in various ways.
const meter = new MeterProvider().getMeter('your-meter-name');

const counter = meter.createCounter('metric_name', {
  description: 'Example of a counter'
});

const labels = { pid: process.pid };

// Create a BoundInstrument associated with specified label values.
const boundCounter = counter.bind(labels);
boundCounter.add(10);

UpDownCounter

UpDownCounter is similar to Counter except that it supports negative increments. It is generally useful for capturing changes in an amount of resources used, or any quantity that rises and falls during a request.

Example uses for UpDownCounter:

• count the number of active requests
• count memory in use by instrumenting new and delete
• count queue size by instrumenting enqueue and dequeue
• count semaphore up and down operations

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

// Initialize the Meter to capture measurements in various ways.
const meter = new MeterProvider().getMeter('your-meter-name');

const counter = meter.createUpDownCounter('metric_name', {
  description: 'Example of a UpDownCounter'
});

const labels = { pid: process.pid };

// Create a BoundInstrument associated with specified label values.
const boundCounter = counter.bind(labels);
boundCounter.add(Math.random() > 0.5 ? 1 : -1);

Value Observer

Choose this kind of metric when only last value is important without worry about aggregation. The callback can be sync or async.

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

const meter = new MeterProvider().getMeter('your-meter-name');


// async callback - for operation that needs to wait for value
meter.createValueObserver('your_metric_name', {
  description: 'Example of an async observer with callback',
}, async (observerResult) => {
  const value = await getAsyncValue();
  observerResult.observe(value, { label: '1' });
});

function getAsyncValue() {
  return new Promise((resolve) => {
    setTimeout(()=> {
      resolve(Math.random());
    }, 100);
  });
}

// sync callback in case you don't need to wait for value
meter.createValueObserver('your_metric_name', {
  description: 'Example of a sync observer with callback',
}, (observerResult) => {
  observerResult.observe(getRandomValue(), { label: '1' });
  observerResult.observe(getRandomValue(), { label: '2' });
});

function getRandomValue() {
  return Math.random();
}

UpDownSumObserver

Choose this kind of metric when sum is important and you want to capture any value that starts at zero and rises or falls throughout the process lifetime. The callback can be sync or async.

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

const meter = new MeterProvider().getMeter('your-meter-name');

// async callback - for operation that needs to wait for value
meter.createUpDownSumObserver('your_metric_name', {
  description: 'Example of an async observer with callback',
}, async (observerResult) => {
  const value = await getAsyncValue();
  observerResult.observe(value, { label: '1' });
});

function getAsyncValue() {
  return new Promise((resolve) => {
    setTimeout(()=> {
      resolve(Math.random());
    }, 100);
  });
}

// sync callback in case you don't need to wait for value
meter.createUpDownSumObserver('your_metric_name', {
  description: 'Example of a sync observer with callback',
}, (observerResult) => {
  observerResult.observe(getRandomValue(), { label: '1' });
});

function getRandomValue() {
  return Math.random();
}

Sum Observer

Choose this kind of metric when collecting a sum that never decreases. The callback can be sync or async.

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

const meter = new MeterProvider().getMeter('your-meter-name');

// async callback in case you need to wait for values
meter.createSumObserver('example_metric', {
  description: 'Example of an async sum observer with callback',
}, async (observerResult) => {
  const value = await getAsyncValue();
  observerResult.observe(value, { label: '1' });
});

function getAsyncValue() {
  return new Promise((resolve) => {
    setTimeout(() => {
      resolve(Math.random());
    }, 100)
  });
}

// sync callback in case you don't need to wait for values
meter.createSumObserver('example_metric', {
  description: 'Example of a sync sum observer with callback',
}, (observerResult) => {
  const value = getRandomValue();
  observerResult.observe(value, { label: '1' });
});

function getRandomValue() {
  return Math.random();
}

Batch Observer

Choose this kind of metric when you need to update multiple observers with the results of a single async calculation.

const { MeterProvider } = require('@opentelemetry/metrics');
const { PrometheusExporter } = require('@opentelemetry/exporter-prometheus');

const exporter = new PrometheusExporter(
  {
    startServer: true,
  },
  () => {
    console.log('prometheus scrape endpoint: http://localhost:9464/metrics');
  },
);

const meter = new MeterProvider({
  exporter,
  interval: 3000,
}).getMeter('example-observer');

const cpuUsageMetric = meter.createValueObserver('cpu_usage_per_app', {
  description: 'CPU',
});

const MemUsageMetric = meter.createValueObserver('mem_usage_per_app', {
  description: 'Memory',
});

meter.createBatchObserver((observerBatchResult) => {
  getSomeAsyncMetrics().then(metrics => {
    observerBatchResult.observe({ app: 'myApp' }, [
      cpuUsageMetric.observation(metrics.value1),
      MemUsageMetric.observation(metrics.value2)
    ]);
  });
});

function getSomeAsyncMetrics() {
  return new Promise((resolve, reject) => {
    setTimeout(() => {
      resolve({
        value1: Math.random(),
        value2: Math.random(),
      });
    }, 100)
  });
}

See examples/prometheus for a short example.

Value Recorder

ValueRecorder is a non-additive synchronous instrument useful for recording any non-additive number, positive or negative. Values captured by ValueRecorder.record(value) are treated as individual events belonging to a distribution that is being summarized. ValueRecorder should be chosen either when capturing measurements that do not contribute meaningfully to a sum, or when capturing numbers that are additive in nature, but where the distribution of individual increments is considered interesting.

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

0.24.0

:boom: Breaking Change

• opentelemetry-core, opentelemetry-exporter-jaeger, opentelemetry-exporter-zipkin, opentelemetry-node, opentelemetry-resource-detector-aws, opentelemetry-resource-detector-gcp, opentelemetry-resources, opentelemetry-semantic-conventions, opentelemetry-web
  • #2345 feat: updated spec to v1.5.0 and renamed resource class (@weyert)

:rocket: (Enhancement)

• opentelemetry-exporter-collector-proto, opentelemetry-exporter-collector
  • #2337 Support gzip compression for node exporter collector (@alisabzevari)
• opentelemetry-instrumentation-http
  • #2332 feat(@opentelemetry-instrumentation-http): support adding custom attributes before a span is started (@echoontheway)
  • #2349 fix(instrumentation-http): set outgoing request attributes on start span (@blumamir)
• opentelemetry-web
  • #2343 feat(opentelemetry-web): capture decodedBodySize / http.response_content_length_uncompressed (@t2t2)
• opentelemetry-instrumentation
  • #2309 chore: add includePrerelease option to instrumentation config (@dyladan)

:bug: (Bug Fix)

• opentelemetry-exporter-collector
  • #2357 fix: headers are appended to existing one (open-telemetry#2335) (@niko-achilles)
• opentelemetry-exporter-collector-grpc
  • #2322 fix(@opentelemetry/exporter-collector-grpc) regression from #2130 when host specified without protocol (@lizthegrey)
• opentelemetry-exporter-collector-proto
  • #2331 Change default HTTP exporter port to 55681 (@NathanielRN)

:books: (Refine Doc)

• Other
  • #2344 Additional website docs updates (@svrnm)
  • #2365 docs: add quickstart code example (@vreynolds)
  • #2358 examples opentelemetry-api version fix (@CptSchnitz)
  • #2308 chore: use typedoc to build sdk reference (@dyladan)
  • #2324 fix: update and make website docs work (@svrnm)
  • #2328 chore: updating compatibility matrix (@obecny)
  • #2326 chore: fix tracer-web example webpack config (@jonchurch)
• opentelemetry-resource-detector-aws
  • #2379 fix: fixup aws detector readme (@legendecas)
• opentelemetry-propagator-b3
  • #2342 docs: updates README.md for @opentelemetry/propagator-b3 (@OmkarKirpan)
• opentelemetry-exporter-collector-grpc
  • #2266 fix(exporter-collector-grpc): incorrect URL format on docs after 0.20.0 update (@brunoluiz)

:house: (Internal)

• Other
  • #2366 chore: adding Rauno56 to js approvers (@obecny)
  • #2350 chore: ignore backcompat in renovate (@dyladan)
  • #2352 replaced word plugin with instrumentation (@niko-achilles)
  • #2311 chore: ignore @types/node in backcompat (@dyladan)
• opentelemetry-exporter-collector-grpc, opentelemetry-exporter-jaeger, opentelemetry-instrumentation, opentelemetry-node, opentelemetry-sdk-node, opentelemetry-shim-opentracing, opentelemetry-tracing, opentelemetry-web
  • #2351 style: use single quotes everywhere and add a rule to eslint (@blumamir)
• template
  • #2319 chore: update package template engines version (@jonchurch)

Committers: 18

• (Eliseo) Nathaniel Ruiz Nowell (@NathanielRN)
• Ali Sabzevari (@alisabzevari)
• Amir Blum (@blumamir)
• Bartlomiej Obecny (@obecny)
• Bruno Luiz Silva (@brunoluiz)
• Daniel Dyla (@dyladan)
• Gerhard Stöbich (@Flarna)
• Jonathan Church (@jonchurch)
• Liz Fong-Jones (@lizthegrey)
• Niko Achilles Kokkinos (@niko-achilles)
• Ofer Adelstein (@CptSchnitz)
• Omkar Kirpan (@OmkarKirpan)
• Severin Neumann (@svrnm)
• Vera Reynolds (@vreynolds)
• Weyert de Boer (@weyert)
• @echoontheway
• legendecas (@legendecas)
• t2t2 (@t2t2)