metrics-os v1.0.1

OS Metrics

Utility to get system metrics.

Installation

For use in Node.js,

$ npm install metrics-os

Usage

The module exports a single method, which returns an object containing uptime, load, mem, and cpu metrics. To use the utility,

var getMetrics = require( 'metrics-os' ),
	metrics = getMetrics();

The following is an example metrics output...

{
	"uptime": 218091000,
	"load": {
		"1m": 1.443359375,
		"5m": 1.58203125,
		"15m": 1.93359375
	},
	"mem": {
		"memTotal": 8589934.592,
		"memFree": 230801.408,
		"ramUtilization": 0.9731311798095703
	},
	"cpu": [
		{
			"user": 16288640,
			"nice": 0,
			"system": 7832180,
			"idle": 98866460,
			"irq": 0
		},
		{
			"user": 7631040,
			"nice": 0,
			"system": 2386640,
			"idle": 112967740,
			"irq": 0
		},
		{
			"user": 14059800,
			"nice": 0,
			"system": 5183440,
			"idle": 103742200,
			"irq": 0
		},
		{
			"user": 7632010,
			"nice": 0,
			"system": 2324990,
			"idle": 113028390,
			"irq": 0
		},
		{
			"userAverage": 11402872.5,
			"niceAverage": 0, 
			"systemAverage": 4431812.5,
			"idleAverage": 107151197.5,
			"irqAverage": 0
		}
	]
}

Metrics

The following metrics are reported...

uptime

The number of milliseconds since the last system reboot. In contrast to os.uptime(), the uptime reported by this utility is in milliseconds so as to match the units for CPU metrics (idle, user, system, nice, iqr).

load.1m

The average number of jobs in the run queue (state R) or waiting for disk I/O (state D) over the past minute.

load.5m

The average number of jobs in the run queue (state R) or waiting for disk I/O (state D) over the past 5 minutes.

load.15m

The average number of jobs in the run queue (state R) or waiting for disk I/O (state D) over the past 15 minutes.

mem.memTotal

The total amount of usable RAM. This metric is reported in kilobytes.

mem.memFree

The total mount of free RAM. This metric is reported in kilobytes.

mem.ramUtilization

The decimal percentage of RAM being used.

cpu.user

Number of milliseconds a CPU has spent in user mode.

cpu.system

Number of milliseconds a CPU has spent in kernel mode.

cpu.idle

Number of milliseconds a CPU has spent idle.

cpu.nice

Number of milliseconds a CPU has spent in user mode and had a positive nice value (executed tasks with low priority).

cpu.iqr

Number of milliseconds spent addressing hardware interrupts.

cpu.<metric>Average

All metrics with the suffix Average are the mean values calculated across all CPUs.

Examples

var getMetrics = require( 'metrics-os' );

for ( var i = 0; i < 10; i++ ) {
	setTimeout( onTimeout, 1000*i );
}

function onTimeout() {
	JSON.stringify( getMetrics() );
}

To run an example from the top-level application directory,

$ node ./examples/index.js

Notes

1. As stated in the Node.js [documentation](http://nodejs.org/api/os.html#os_os_loadavg), `loadavg` is __not__ supported on Windows platforms.

2. Note that the length of the CPU metric `array` is __one more than__ the number of CPUs.

3. The metric naming scheme follows the conventions set forth in [doc-metrix](https://github.com/doc-metrix).

Tests

Unit

Unit tests use the Mocha test framework with Chai assertions. To run the tests, execute the following command in the top-level application directory:

$ make test

All new feature development should have corresponding unit tests to validate correct functionality.

Test Coverage

This repository uses Istanbul as its code coverage tool. To generate a test coverage report, execute the following command in the top-level application directory:

$ make test-cov

Istanbul creates a ./reports/coverage directory. To access an HTML version of the report,

$ make view-cov

License

MIT license.

Copyright

Copyright © 2014. Athan Reines.