native-hdr-histogram

node.js bindings for hdr histogram C implementation(version 0.9.10).

HDR Histogram is designed for recoding histograms of value measurements in latency and performance sensitive applications. Measurements show value recording times as low as 3-6 nanoseconds on modern (circa 2014) Intel CPUs. A Histogram's memory footprint is constant, with no allocation operations involved in recording data values or in iterating through them.

from hdr histogram website

This library is blazingly fast, and you can use it to record histograms with no overhead. Linux, Mac OS X and Windows are all supported.

Installation
Example
API
Licence & copyright

Install

npm i native-hdr-histogram --save

If you see any errors, you might need to configure your system to compile native addons: follow the instructions at node-gyp.

Example

'use strict'

const Histogram = require('native-hdr-histogram')
const max = 1000000
const key = 'record*' + max
const histogram = new Histogram(1, 100)

console.time(key)
for (let i = 0; i < max; i++) {
  histogram.record(Math.floor((Math.random() * 42 + 1)))
}
console.timeEnd(key)

console.log('80 percentile is', histogram.percentile(80))
console.log('99 percentile is', histogram.percentile(99))

console.log(histogram.percentiles())

Histogram(lowest, max, figures)

Create a new histogram with:

lowest: is the lowest possible number that can be recorded (default 1).
max: is the maximum number that can be recorded (default 100).
figures: the number of figures in a decimal number that will be maintained, must be between 1 and 5 (inclusive) (default 3).

histogram.record(value)

Record value in the histogram. Returns true if the recording was successful, false otherwise.

histogram.min()

Return the minimum value recorded in the histogram.

histogram.max()

Return the maximum value recorded in the histogram.

histogram.mean()

Return the mean of the histogram.

histogram.stddev()

Return the standard deviation of the histogram.

histogram.percentile(percentile)

Returns the value at the given percentile. percentile must be > 0 and <= 100, otherwise it will throw.

histogram.percentiles()

Returns all the percentiles.

Sample output:

[ { percentile: 0, value: 1 },
  { percentile: 50, value: 22 },
  { percentile: 75, value: 32 },
  { percentile: 87.5, value: 37 },
  { percentile: 93.75, value: 40 },
  { percentile: 96.875, value: 41 },
  { percentile: 98.4375, value: 42 },
  { percentile: 100, value: 42 } ]

histogram.encode()

Returns a Buffer containing a serialized version of the histogram

histogram.decode(buf)

Reads a Buffer and deserialize an histogram.

histogram.reset()

Resets the histogram so it can be reused.

Acknowledgements

This project was kindly sponsored by nearForm.

The pre-compilation work of this project is only possible because of mapbox's amazing work on node-pre-gyp. A lot of the functionality enabled is following the example set by their node-sqlite3 library.

License

This library is licensed as MIT

HdrHistogram_c is licensed as BSD license

zlib is licensed as zlib License

The scripts used in the scripts folder are modified BSD licensed scripts from the node-sqlite3 libary.

ccollie / native-hdr-histogram Goto Github PK