# @opentelemetry/instrumentation-runtime-node

> OpenTelemetry instrumentation for Node.js Performance measurement API

Latest version **0.35.0** (published 2026-08-31) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @opentelemetry/instrumentation-runtime-node
pnpm add @opentelemetry/instrumentation-runtime-node
yarn add @opentelemetry/instrumentation-runtime-node
bun add @opentelemetry/instrumentation-runtime-node
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads; no esm support; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.35.0 |
| Published | 2026-08-31 |
| First published | 2024-02-29 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | ^18.19.0 \|\| >=20.6.0 |
| Dependencies | 3 |
| Unpacked size | 108.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 924 |
| Author | OpenTelemetry Authors |
| Maintainers | dyladan, pichlermarc, overbalance, npmjs-account, trentm, martinkuba |
| Keywords | perf_hooks, instrumentation, nodejs, opentelemetry |

## Links

- npm: https://www.npmjs.com/package/@opentelemetry/instrumentation-runtime-node
- Repository: https://github.com/open-telemetry/opentelemetry-js-contrib
- Homepage: https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/packages/instrumentation-runtime-node#readme
- Issues: https://github.com/open-telemetry/opentelemetry-js-contrib/issues
- npm.io page: https://npm.io/package/@opentelemetry/instrumentation-runtime-node

## Dependencies (3)

- [@opentelemetry/core](https://npm.io/package/@opentelemetry/core.md) ^2.0.0
- [@opentelemetry/api-logs](https://npm.io/package/@opentelemetry/api-logs.md) ^0.222.0
- [@opentelemetry/instrumentation](https://npm.io/package/@opentelemetry/instrumentation.md) ^0.222.0

## Recent versions

- 0.35.0 (latest) — 2026-08-31
- 0.34.0 — 2026-07-23
- 0.33.0 — 2026-07-03
- 0.32.0 — 2026-06-11
- 0.31.0 — 2026-05-13
- 0.30.0 — 2026-05-06
- 0.29.0 — 2026-04-29
- 0.28.0 — 2026-04-17
- 0.27.0 — 2026-03-26
- 0.26.0 — 2026-03-04
- 0.25.0 — 2026-02-17
- 0.24.0 — 2026-01-22
- 0.23.0 — 2026-01-15
- 0.22.0 — 2025-11-06
- 0.21.0 — 2025-10-21
- … 26 more at https://npm.io/package/@opentelemetry/instrumentation-runtime-node/versions

## README

# OpenTelemetry Node.js Runtime Metrics Instrumentation

[![NPM Published Version][npm-img]][npm-url]
[![Apache License][license-image]][license-image]

This module provides automatic metric instrumentation that exposes measurements from the [Performance measurement APIs](https://nodejs.org/api/perf_hooks.html) (i.e. `perf_hooks`).
It can also emit OpenTelemetry logs for uncaught exceptions.
When a configured logger provider exposes `forceFlush()` (for example, the SDK
`LoggerProvider`), this instrumentation calls it immediately after emitting the
uncaught-exception log record as a best-effort attempt to reduce log loss on
process termination.

## Supported Versions

- Node.js `^18.19.0 || >=20.6.0`

## Example

```bash
npm install --save @opentelemetry/sdk-node @opentelemetry/exporter-prometheus
npm install --save @opentelemetry/instrumentation-runtime-node
```

```js
import { NodeSDK } from '@opentelemetry/sdk-node';
import { PrometheusExporter } from '@opentelemetry/exporter-prometheus';
import { RuntimeNodeInstrumentation } from '@opentelemetry/instrumentation-runtime-node';

const prometheusExporter = new PrometheusExporter({
  port: 9464,
  startServer: true
});

const sdk = new NodeSDK({
  metricReader: prometheusExporter,
  instrumentations: [new RuntimeNodeInstrumentation({
    monitoringPrecision: 5000,
  })],
});

sdk.start()
```

[`NodeSDK`](https://www.npmjs.com/package/@opentelemetry/sdk-node) is the full OpenTelemetry SDK for Node.js that is a layer of abstraction on top of the `@opentelemetry/sdk-metrics` and `@opentelemetry/sdk-trace-*` packages. By specifying `metricReader`, it will initialize the metrics SDK and creates a `MeterProvider`. [`@opentelemetry/exporter-prometheus`](https://www.npmjs.com/package/@opentelemetry/exporter-prometheus) will output metrics collected by registered instrumentation on a `/metrics` endpoint.

Go to [`localhost:9464/metrics`](http://localhost:9464/metrics), and you should see:

```txt
# HELP nodejs_performance_event_loop_utilization Event loop utilization
# UNIT nodejs_performance_event_loop_utilization 1
# TYPE nodejs_performance_event_loop_utilization gauge
nodejs_performance_event_loop_utilization 0.010140079547955264
```

> On the very first metrics collection the event loop utilization and time metrics may report zero or near-zero values while the instrumentation establishes a baseline.

### Options

`RuntimeNodeInstrumentation`'s constructor accepts the following options:

| name                                        | type  | unit        | default | description                                                                                                                                                                                                                                                                                     |
|---------------------------------------------|-------|-------------|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`monitoringPrecision`](./src/types.ts) | `int` | millisecond | `10`    | The resolution in milliseconds for the event loop delay histogram (`perf_hooks.monitorEventLoopDelay`). A smaller value gives finer-grained delay samples at the cost of more overhead. Has no effect on event loop utilization or time metrics. |
| [`captureUncaughtException`](./src/types.ts) | `bool` | - | `false` | Whether to emit a `LogRecord` for uncaught exceptions (severity `FATAL`). Uses the `uncaughtExceptionMonitor` process event. |
| [`applyCustomExceptionAttributes`](./src/types.ts) | `function` | - | `undefined` | Optional callback to attach custom attributes to emitted exception log records. |

## Semantic Conventions

This instrumentation emits metrics defined in the experimental `@opentelemetry/semantic-conventions` (`^1.29.0`) for the `nodejs` and `v8js` runtime namespaces.

### Metrics collected

| Metric | Short Description |
|---|---|
| `nodejs.eventloop.time` | Cumulative duration the event loop has been in each state |
| `nodejs.eventloop.utilization` | Event loop utilization ratio (0.0–1.0) |
| `nodejs.eventloop.delay.min` | Minimum event loop delay |
| `nodejs.eventloop.delay.max` | Maximum event loop delay |
| `nodejs.eventloop.delay.mean` | Mean event loop delay |
| `nodejs.eventloop.delay.stddev` | Standard deviation of event loop delay |
| `nodejs.eventloop.delay.p50` | 50th-percentile event loop delay |
| `nodejs.eventloop.delay.p90` | 90th-percentile event loop delay |
| `nodejs.eventloop.delay.p99` | 99th-percentile event loop delay |
| `v8js.gc.duration` | Garbage Collection pause duration by type |
| `v8js.memory.heap.space.size` | Total pre-allocated size of a heap space |
| `v8js.memory.heap.used` | Used heap memory in a heap space |
| `v8js.memory.heap.space.available_size` | Available size in a heap space |
| `v8js.memory.heap.space.physical_size` | Committed (physical) size of a heap space |
| `v8js.resource.active` | Count of active resources keeping the event loop alive |

### Attributes collected

| Attribute | Short Description |
|---|---|
| `nodejs.eventloop.state` | State of the event loop (`active`, `idle`) |
| `v8js.gc.type` | Type of Garbage Collection (`major`, `minor`, `incremental`, `weakcb`) |
| `v8js.heap.space.name` | Name of the V8 heap space |
| `v8js.resource.type` | Type of active resource |

## 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][discussions-url]

## License

Apache 2.0 - See [LICENSE][license-url] for more information.

[discussions-url]: https://github.com/open-telemetry/opentelemetry-js/discussions
[license-url]: https://github.com/open-telemetry/opentelemetry-js-contrib/blob/main/LICENSE
[license-image]: https://img.shields.io/badge/license-Apache_2.0-green.svg?style=flat
[npm-url]: https://www.npmjs.com/package/@opentelemetry/instrumentation-runtime-node
[npm-img]: https://badge.fury.io/js/%40opentelemetry%2Finstrumentation-runtime-node.svg

---
_Source: https://npm.io/package/@opentelemetry/instrumentation-runtime-node · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._