@opentelemetry/instrumentation-runtime-node

OpenTelemetry Node.js Runtime Metrics Instrumentation

This module provides automatic metric instrumentation that exposes measurements from the Performance measurement APIs (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

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

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 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 will output metrics collected by registered instrumentation on a /metrics endpoint.

Go to localhost:9464/metrics, and you should see:

# 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	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	bool	-	false	Whether to emit a LogRecord for uncaught exceptions (severity FATAL). Uses the uncaughtExceptionMonitor process event.
applyCustomExceptionAttributes	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

License

Apache 2.0 - See LICENSE for more information.