{"id":13718,"library":"opentelemetry-node-metrics","title":"OpenTelemetry Node.js Process Metrics","description":"opentelemetry-node-metrics is a Node.js library that adapts the widely used `prom-client` metric set to the OpenTelemetry ecosystem, specifically for capturing process-level metrics. It currently stands at version 3.0.0, which dropped support for `@opentelemetry/api-metrics` older than v0.33, continuing a pattern of major version releases aligning with significant OpenTelemetry API updates. This library provides a direct translation of common system and runtime metrics (like CPU usage, memory, event loop lag, garbage collection statistics, and network/file descriptor usage) into OpenTelemetry-compatible instruments. Its primary differentiator is leveraging the `prom-client`'s established metric definitions, which can ease migration for projects already familiar with Prometheus-style monitoring, while integrating seamlessly into an OpenTelemetry-based observability pipeline. Notably, it does not offer Node.js cluster support, a limitation inherited from the underlying OpenTelemetry metrics API. The release cadence is directly tied to the evolution of the OpenTelemetry JavaScript SDK, leading to breaking changes primarily driven by API shifts.","status":"active","version":"3.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/marcbachmann/opentelemetry-node-metrics","tags":["javascript","opentelemetry","process","tracing","metrics","prom-client"],"install":[{"cmd":"npm install opentelemetry-node-metrics","lang":"bash","label":"npm"},{"cmd":"yarn add opentelemetry-node-metrics","lang":"bash","label":"yarn"},{"cmd":"pnpm add opentelemetry-node-metrics","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides the `MeterProvider` necessary for metric collection and processing. This is a core component for using OpenTelemetry metrics.","package":"@opentelemetry/sdk-metrics","optional":false},{"reason":"Core OpenTelemetry metrics API that this library builds upon. Version compatibility is crucial for this package to function correctly.","package":"@opentelemetry/api-metrics","optional":false},{"reason":"A commonly used exporter to expose collected metrics via a Prometheus-compatible HTTP endpoint. Essential for Prometheus integration.","package":"@opentelemetry/exporter-prometheus","optional":true},{"reason":"This 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.","package":"prom-client","optional":true}],"imports":[{"note":"The package exports a default function for registering process metrics with a `MeterProvider`.","wrong":"import { registerProcessMetrics } from 'opentelemetry-node-metrics';","symbol":"registerProcessMetrics","correct":"import registerProcessMetrics from 'opentelemetry-node-metrics';"},{"note":"CommonJS `require` is used for the main export, which is a function.","symbol":"registerProcessMetrics","correct":"const registerProcessMetrics = require('opentelemetry-node-metrics');"},{"note":"The `MeterProvider` is typically imported from `@opentelemetry/sdk-metrics` (the SDK implementation), not directly from the `@opentelemetry/api-metrics` (the API interface).","wrong":"import { MeterProvider } from '@opentelemetry/metrics';","symbol":"MeterProvider","correct":"import { MeterProvider } from '@opentelemetry/sdk-metrics';"},{"note":"The Prometheus exporter is a separate package and should be imported from its dedicated module.","wrong":"const { PrometheusExporter } = require('@opentelemetry/metrics');","symbol":"PrometheusExporter","correct":"import { PrometheusExporter } from '@opentelemetry/exporter-prometheus';"}],"quickstart":{"code":"const { MeterProvider } = require('@opentelemetry/sdk-metrics');\nconst { PrometheusExporter } = require('@opentelemetry/exporter-prometheus');\n\n// Configure the Prometheus exporter\nconst exporter = new PrometheusExporter(\n  { startServer: true }, // Starts an HTTP server for Prometheus to scrape\n  () => {\n    console.log(\n      `Prometheus scrape endpoint: http://localhost:${PrometheusExporter.DEFAULT_OPTIONS.port}${PrometheusExporter.DEFAULT_OPTIONS.endpoint}`,\n    );\n  },\n);\n\n// Configure the MeterProvider\nconst meterProvider = new MeterProvider({\n  readers: [exporter], // Use `readers` for SDK v1.0+ instead of `exporter`\n  interval: 2000,\n});\n\n// Register process metrics\nconst registerProcessMetrics = require('opentelemetry-node-metrics');\nregisterProcessMetrics(meterProvider);\n\n// Ensure graceful shutdown (optional but recommended)\nprocess.on('SIGTERM', () => {\n  meterProvider.shutdown().then(() => console.log('Metrics shutdown complete.'));\n});\nprocess.on('SIGINT', () => {\n  meterProvider.shutdown().then(() => console.log('Metrics shutdown complete.'));\n});","lang":"javascript","description":"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."},"warnings":[{"fix":"Upgrade 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.","message":"`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.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Ensure your OpenTelemetry SDK and API packages are at least v0.27.0. For `v3.0.0`, even newer versions are required.","message":"`opentelemetry-node-metrics` v2.0.0 drops support for `opentelemetry` versions older than v0.27.0.","severity":"breaking","affected_versions":">=2.0.0 <3.0.0"},{"fix":"For 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.","message":"This 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For `@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.","message":"The `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.","severity":"gotcha","affected_versions":">=1.0.0 of @opentelemetry/sdk-metrics"}],"env_vars":null,"search_vec":"'3.0.0':39 'adapt':14 'align':55 'alreadi':111 'api':59,144,166 'base':125 'break':161 'cadenc':147 'captur':29 'chang':162 'client':20,100,175 'cluster':134 'collect':81 'common':68 'compat':90 'continu':48 'cpu':74 'current':35 'definit':104 'descriptor':85 'differenti':94 'direct':65,149 'driven':164 'drop':41 'eas':107 'ecosystem':26 'establish':102 'event':77 'evolut':153 'familiar':112 'garbag':80 'inherit':138 'instrument':91 'integr':119 'javascript':157,168 'lag':79 'lead':159 'level':32 'leverag':96 'librari':12,62 'like':73 'limit':137 'loop':78 'major':52 'memori':76 'metric':4,8,21,33,72,103,143,172 'migrat':108 'monitor':117 'network/file':84 'node':7 'node.js':2,11,133 'notabl':128 'observ':126 'offer':132 'older':45 'opentelemetri':1,6,25,58,89,124,142,156,169 'opentelemetry-bas':123 'opentelemetry-compat':88 'opentelemetry-node-metr':5 'opentelemetry/api-metrics':44 'pattern':50 'pipelin':127 'primari':93 'primarili':163 'process':3,31,170 'process-level':30 'project':110 'prom':19,99,174 'prom-client':18,98,173 'prometheus':115 'prometheus-styl':114 'provid':63 'releas':54,146 'runtim':71 'sdk':158 'seamless':120 'set':22 'shift':167 'signific':57 'specif':27 'stand':36 'statist':82 'style':116 'support':42,135 'system':69 'tie':150 'trace':171 'translat':66 'under':141 'updat':60 'usag':75,86 'use':17 'v0.33':47 'version':38,53 'wide':16","created_at":"2026-04-20T01:55:57.451456+00:00","updated_at":"2026-04-20T01:55:57.451456+00:00","problems":[{"fix":"Ensure 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.","cause":"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.","error":"TypeError: Cannot read properties of undefined (reading 'observe')"},{"fix":"Ensure 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] })`.","cause":"The `MeterProvider` was initialized without a `MetricReader` (e.g., an exporter) or the `readers` array was empty, preventing metrics from being collected or exported.","error":"Error: MetricReader must be provided"},{"fix":"Ensure 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.","cause":"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.","error":"Error: listen EADDRINUSE: address already in use :::9464"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/marcbachmann/opentelemetry-node-metrics","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/opentelemetry-node-metrics","openapi_spec":null,"status_page":null,"smithery":null,"categories":["observability","http-networking"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}