# native-hdr-histogram
node.js bindings for [hdr histogram][hdr] [C implementation][cimpl] (version 0.11.1)
[](https://nodejs.org/dist/latest/docs/api/n-api.html#n_api_n_api)
> 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
## Install
```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].
## Example
```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())
```
## API
* 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
-------------------------------------------------------
### 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, count = 1)
Record `value` in the histogram with a count of `count`. Returns `true` if the recording was
successful, `false` otherwise.
-------------------------------------------------------
### histogram.recordCorrectedValue(value, expectedInterval, count = 1)
Record `value` in the histogram with a count of `count` and backfill based on a `expectedInterval`.
This is specifically used for recording latency. If `value` 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.
-------------------------------------------------------
### 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:
```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 } ]
```
-------------------------------------------------------
### histogram.linearcounts(valueUnitsPerBucket)
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
]
```
-------------------------------------------------------
### histogram.logcounts(valueUnitsFirstBucket, logBase)
Returns the recorded counts according to a logarithmic distribution using `valueUnitsFirstBucket`
for the first value and increasing exponentially according to `logBase`.
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 }
]
```
-------------------------------------------------------
### histogram.recordedcounts()
Returns all the values recorded in the histogram.
Sample output:
```js
[
{ count: 10000, value: 1000 },
{ count: 1, value: 99942400 }
]
```
-------------------------------------------------------
### histogram.encode()
Returns a `Buffer` containing a serialized version of the histogram
-------------------------------------------------------
### histogram.decode(buf)
Reads a `Buffer` and deserialize an histogram.
-------------------------------------------------------
### histogram.lowestEquivalentValue(value)
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.
------------------------------------------------------
### histogram.highestEquivalentValue(value)
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.
------------------------------------------------------
### histogram.nextNonEquivalentValue(value)
Get the next value that is not equivalent to the given value within the histogram's resolution.
------------------------------------------------------
### histogram.areValueEquivalent(value1, value2)
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.
-------------------------------------------------------
### histogram.add(other[, expectedIntervalBetweenValueSamples])
Adds all of the values from `other` to 'this' histogram. Will return the
number of values that are dropped when copying. Values will be dropped
if they around outside of `histogram.lowestTrackableValue` and
`histogram.highestTrackableValue`.
If `expectedIntervalBetweenValueSamples` is specified, values are
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 `expectedIntervalBetweenValueSamples`) value records for each count found
in the current histogram that is larger than the `expectedIntervalBetweenValueSamples`.
Returns the number of values dropped while copying.
-------------------------------------------------------
### histogram.reset()
Resets the histogram so it can be reused.
-------------------------------------------------------
## Properties
### histogram.lowestTrackableValue
Get the configured lowestTrackableValue
-------------------------------------------------------
### histogram.highestTrackableValue
Get the configured highestTrackableValue
-------------------------------------------------------
### histogram.significantFigures
Get the configured number of significant value digits
-------------------------------------------------------
### histogram.totalCount
Gets the total number of recorded values.
-------------------------------------------------------
### histogram.memorySize
Get the memory size of the Histogram.
-------------------------------------------------------
## Acknowledgements
This project was kindly sponsored by [nearForm](http://nearform.com).
## License
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