node.js bindings for hdr histogram C implementation
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
scripts
src
zlib
.gitignore
.travis.yml
LICENSE
Makefile
README.md
appveyor.yml
bench.js
binding.gyp
hdr_histogram_wrap.cc
hdr_histogram_wrap.h
histogram.cc
histogram.js
package.json
test.js

README.md

native-hdr-histogram

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

Build status Build Status

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.

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.

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())

API


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.