OpenTelemetry Host Metrics Instrumentation for Node.js

This module provides automatic collection of host metrics for the Node.js process and operating system, including CPU, memory, and network. It is included in the @opentelemetry/auto-instrumentations-node bundle (disabled by default; enable via OTEL_NODE_ENABLED_INSTRUMENTATIONS).

Compatible with OpenTelemetry JS API and SDK 1.0+.

Installation

npm install --save @opentelemetry/instrumentation-host-metrics

Supported Versions

• Node.js ^18.19.0 || >=20.6.0

Usage

const { NodeSDK } = require('@opentelemetry/sdk-node');
const { HostMetricsInstrumentation } = require('@opentelemetry/instrumentation-host-metrics');

const sdk = new NodeSDK({
  instrumentations: [new HostMetricsInstrumentation()],
});

sdk.start();

Host Metrics Instrumentation Options

| Option | Type | Description | |----------------|------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | metricGroups | string[] | Optionally restrict collection to one or more metric groups (see Semantic Conventions). When unset, all metrics are collected. For example, metricGroups: ['process.cpu', 'process.memory'] limits collection to those metrics only. |

Semantic Conventions

Metrics collected:

| Metric | Short Description | |---------------------------------|-----------------------------------------------------------| | Group system.cpu | | | system.cpu.time | Seconds each logical CPU spent on each mode | | system.cpu.utilization | CPU usage (0-1) | | Group system.memory | | | system.memory.usage | Reports memory in use by state | | system.memory.utilization | Memory usage (0-1) | | Group system.network | | | system.network.packet.dropped | Count of packets dropped | | system.network.errors | Count of network errors detected | | system.network.io | Bytes transmitted and received | | Group process.cpu | | | process.cpu.time | Total CPU seconds | | process.cpu.utilization | Difference in process.cpu.time since the last measurement | | Group process.memory | | | process.memory.usage | The amount of physical memory in use |

The "Group" names are the values accepted by the metricGroups configuration option.

Attributes collected:

| Attribute | Short Description | |------------------------|------------------------------------| | cpu.logical_number | The logical CPU number | | cpu.mode | The mode of the CPU | | system.memory.state | The memory state | | system.device | The device identifier | | network.io.direction | The network IO operation direction |

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.