node.js bindings for hdr histogram C implementation
npm install native-hdr-histogramnode.js bindings for [hdr histogram][hdr] [C implementation][cimpl] (version 0.11.1)
!Test
!Prebuild Binaries
> 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][hdr] 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
``bash`
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][node-gyp].
`js
'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
* histogram#record()
* histogram#recordCorrectedValue()
* histogram#min()
* histogram#max()
* histogram#mean()
* histogram#stddev()
* histogram#percentile()
* histogram#percentiles()
* histogram#linearcounts()
* histogram#logcounts()
* histogram#recordedcounts()
* histogram#encode()
* histogram#decode()
* histogram#lowestEquivalentValue()
* histogram#highestEquivalentValue()
* histogram#nextNonEquivalentValue()
* histogram#areValuesEquivalent()
* histogram#add()
* histogram#reset()
#### Properties
* histogram#lowestTrackableValue
* histogram#highestTrackableValue
* histogram#significantFigures
* histogram#totalCount
* histogram#memorySize
-------------------------------------------------------
Create a new histogram with:
* lowest: is the lowest possible number that can be recorded (defaultmax
1).
* : 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).
-------------------------------------------------------
Record value in the histogram with a count of count. Returns true if the recording wasfalse
successful, otherwise.
-------------------------------------------------------
Record value in the histogram with a count of count and backfill based on a expectedInterval.value
This is specifically used for recording latency. If is larger than the expectedInterval
then the latency recording system has experienced coordinated omission. This method fills in the
values that would have occurred had the client providing the load not been blocked.
Returns true if the recording was successful, false otherwise.
-------------------------------------------------------
Return the minimum value recorded in the histogram.
-------------------------------------------------------
Return the maximum value recorded in the histogram.
-------------------------------------------------------
Return the mean of the histogram.
-------------------------------------------------------
Return the standard deviation of the histogram.
-------------------------------------------------------
Returns the value at the given percentile. percentile must be >
0 and <= 100, otherwise it will throw.
-------------------------------------------------------
Returns all the percentiles.
Sample output:
`js`
[ { 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 } ]
-------------------------------------------------------
Returns the recorded counts in "buckets" using valueUnitsPerBucket as the bucket size.
Sample output:
`js`
[
{ count: 10000, value: 99968 },
{ count: 0, value: 199936 },
{ count: 0, value: 299776 },
{ count: 0, value: 399872 },
{ count: 0, value: 499968 },
{ count: 0, value: 599552 },
{ count: 0, value: 699904 },
{ count: 0, value: 799744 },
{ count: 0, value: 899584 },
{ count: 0, value: 999936 },
... 990 more items
]
-------------------------------------------------------
Returns the recorded counts according to a logarithmic distribution using valueUnitsFirstBucket
for the first value and increasing exponentially according to .
Sample output:
`js`
[
{ count: 10000, value: 10000 },
{ count: 0, value: 20000 },
{ count: 0, value: 40000 },
{ count: 0, value: 80000 },
{ count: 0, value: 160000 },
{ count: 0, value: 320000 },
{ count: 0, value: 640000 },
{ count: 0, value: 1280000 },
{ count: 0, value: 2560000 },
{ count: 0, value: 5120000 },
{ count: 0, value: 10240000 },
{ count: 0, value: 20480000 },
{ count: 0, value: 40960000 },
{ count: 0, value: 81920000 },
{ count: 1, value: 163840000 }
]
-------------------------------------------------------
Returns all the values recorded in the histogram.
Sample output:
`js`
[
{ count: 10000, value: 1000 },
{ count: 1, value: 99942400 }
]
-------------------------------------------------------
Returns a Buffer containing a serialized version of the histogram
-------------------------------------------------------
Reads a Buffer and deserialize an histogram.
-------------------------------------------------------
Get the lowest value that is equivalent to the given value within the
histogram's resolution, where "equivalent" means that value samples
recorded for any two equivalent values are counted in a common total count.
------------------------------------------------------
Get the highest value that is equivalent to the given value within the
histogram's resolution, where "equivalent" means that value samples
recorded for any two equivalent values are counted in a common total count.
------------------------------------------------------
Get the next value that is not equivalent to the given value within the histogram's resolution.
------------------------------------------------------
Determine if two values are equivalent within the histogram's resolution
where "equivalent" means that value samples recorded for any two
equivalent values are counted in a common total count.
-------------------------------------------------------
Adds all of the values from other to 'this' histogram. Will return thehistogram.lowestTrackableValue
number of values that are dropped when copying. Values will be dropped
if they around outside of andhistogram.highestTrackableValue.
If expectedIntervalBetweenValueSamples is specified, values are expectedIntervalBetweenValueSamples
backfilled with values that would have occurred had the client providing the load
not been blocked. The values added will include an auto-generated additional series of
decreasingly-smaller (down to the ) value records for each count foundexpectedIntervalBetweenValueSamples`.
in the current histogram that is larger than the
Returns the number of values dropped while copying.
-------------------------------------------------------
Resets the histogram so it can be reused.
-------------------------------------------------------
Get the configured lowestTrackableValue
-------------------------------------------------------
Get the configured highestTrackableValue
-------------------------------------------------------
Get the configured number of significant value digits
-------------------------------------------------------
Gets the total number of recorded values.
-------------------------------------------------------
Get the memory size of the Histogram.
-------------------------------------------------------
This project was kindly sponsored by nearForm.
This library is licensed as MIT
HdrHistogram_c is licensed as [BSD license][HdrHistogram_c-license]
zlib is licensed as [zlib License][zlib-license]
[hdr]: http://hdrhistogram.org/
[cimpl]: https://github.com/HdrHistogram/HdrHistogram_c
[node-gyp]: https://github.com/nodejs/node-gyp#installation
[mapbox]: http://mapbox.com
[node-pre-gyp]: https://github.com/mapbox/node-pre-gyp
[sqlite3]: https://github.com/mapbox/node-sqlite3
[HdrHistogram_c-license]: https://github.com/HdrHistogram/HdrHistogram_c/blob/master/LICENSE.txt
[sqlite3-scripts-license]: https://github.com/mapbox/node-sqlite3/blob/master/LICENSE
[zlib-license]: http://www.zlib.net/zlib_license.html