Registry /
observability / opentelemetry-node-metrics
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
registerProcessMetrics
✓ import registerProcessMetrics from 'opentelemetry-node-metrics';
✗ import { registerProcessMetrics } from 'opentelemetry-node-metrics';
The package exports a default function for registering process metrics with a `MeterProvider`.
registerProcessMetrics
✓ const registerProcessMetrics = require('opentelemetry-node-metrics');
CommonJS `require` is used for the main export, which is a function.
MeterProvider
✓ import { MeterProvider } from '@opentelemetry/sdk-metrics';
✗ import { MeterProvider } from '@opentelemetry/metrics';
The `MeterProvider` is typically imported from `@opentelemetry/sdk-metrics` (the SDK implementation), not directly from the `@opentelemetry/api-metrics` (the API interface).
PrometheusExporter
✓ import { PrometheusExporter } from '@opentelemetry/exporter-prometheus';
✗ const { PrometheusExporter } = require('@opentelemetry/metrics');
The Prometheus exporter is a separate package and should be imported from its dedicated module.
Initializes OpenTelemetry metrics for the Node.js process and exposes them via a Prometheus-compatible HTTP endpoint. This example sets up a `MeterProvider` with a `PrometheusExporter` and registers the `opentelemetry-node-metrics` plugin.
const { MeterProvider } = require('@opentelemetry/sdk-metrics');
const { PrometheusExporter } = require('@opentelemetry/exporter-prometheus');
// Configure the Prometheus exporter
const exporter = new PrometheusExporter(
{ startServer: true }, // Starts an HTTP server for Prometheus to scrape
() => {
console.log(
`Prometheus scrape endpoint: http://localhost:${PrometheusExporter.DEFAULT_OPTIONS.port}${PrometheusExporter.DEFAULT_OPTIONS.endpoint}`,
);
},
);
// Configure the MeterProvider
const meterProvider = new MeterProvider({
readers: [exporter], // Use `readers` for SDK v1.0+ instead of `exporter`
interval: 2000,
});
// Register process metrics
const registerProcessMetrics = require('opentelemetry-node-metrics');
registerProcessMetrics(meterProvider);
// Ensure graceful shutdown (optional but recommended)
process.on('SIGTERM', () => {
meterProvider.shutdown().then(() => console.log('Metrics shutdown complete.'));
});
process.on('SIGINT', () => {
meterProvider.shutdown().then(() => console.log('Metrics shutdown complete.'));
});
Debug
Known issues
breaking`opentelemetry-node-metrics` v3.0.0 drops support for `@opentelemetry/api-metrics` versions older than v0.33. Ensure your OpenTelemetry API packages are updated for compatibility.fixUpgrade all `@opentelemetry/*` packages, especially `@opentelemetry/api-metrics`, to v0.33 or newer. For full SDK compatibility, it's best to align all OpenTelemetry packages to their latest stable releases.
affects: >=3.0.0
breaking`opentelemetry-node-metrics` v2.0.0 drops support for `opentelemetry` versions older than v0.27.0.fixEnsure your OpenTelemetry SDK and API packages are at least v0.27.0. For `v3.0.0`, even newer versions are required.
affects: >=2.0.0 <3.0.0
gotchaThis module does not support Node.js cluster mode. OpenTelemetry's standard metrics API does not inherently provide cluster support for aggregated metrics across worker processes.fixFor applications using Node.js clusters, a custom aggregation layer in the master process or an external collector (e.g., OpenTelemetry Collector) is required to consolidate metrics from individual worker processes.
affects: >=1.0.0
gotchaThe `MeterProvider` configuration has evolved. Older OpenTelemetry SDK versions might use an `exporter` option directly, while newer SDKs (v1.0.0+) require `readers`. The quickstart uses `readers` for modern compatibility.fixFor `@opentelemetry/sdk-metrics` v1.0.0 and above, configure your `MeterProvider` using the `readers` array property: `readers: [exporter]`. If using an older SDK, you might need to use `exporter` directly: `exporter: exporter`. Refer to your specific OpenTelemetry SDK version documentation.
affects: >=1.0.0 of @opentelemetry/sdk-metrics
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'observe')
This error often indicates a version mismatch where `opentelemetry-node-metrics` is trying to use an OpenTelemetry API method (e.g., from `api-metrics`) that is not available or has changed in the installed `@opentelemetry/api-metrics` package.
fixEnsure all `@opentelemetry/*` packages in your project, including `opentelemetry-node-metrics` and its dependencies, are aligned to compatible versions. For `opentelemetry-node-metrics v3.x`, you must use `@opentelemetry/api-metrics v0.33` or newer. Upgrade your OpenTelemetry core and SDK packages.
Error: MetricReader must be provided
The `MeterProvider` was initialized without a `MetricReader` (e.g., an exporter) or the `readers` array was empty, preventing metrics from being collected or exported.
fixEnsure your `MeterProvider` is configured with at least one `MetricReader`. For example, pass a `PrometheusExporter` instance within the `readers` array when instantiating `MeterProvider`: `new MeterProvider({ readers: [exporter] })`. Error: listen EADDRINUSE: address already in use :::9464
This typically happens when the `PrometheusExporter` attempts to start a server on a port that is already in use, often because multiple instances of the exporter are being initialized in the same process or on the same machine without proper port configuration.
fixEnsure the `PrometheusExporter` is initialized only once per process. If running multiple instances of your application on the same machine, configure each `PrometheusExporter` with a unique `port` option. For cluster modes, consider aggregating metrics via a single exporter in the master process or using an external collector.
Audit
Dependencies
@opentelemetry/sdk-metricsrequiredProvides the `MeterProvider` necessary for metric collection and processing. This is a core component for using OpenTelemetry metrics.
@opentelemetry/api-metricsrequiredCore OpenTelemetry metrics API that this library builds upon. Version compatibility is crucial for this package to function correctly.
@opentelemetry/exporter-prometheusoptionalA commonly used exporter to expose collected metrics via a Prometheus-compatible HTTP endpoint. Essential for Prometheus integration.
prom-clientoptionalThis module is an adoption of the metric set of `prom-client`. While `prom-client` is not a direct runtime dependency, its metric definitions are the basis for this library.