native-hdr-histogram

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

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

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:

[ { 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:

[
  { 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:

[
  { 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:

[ 
  { 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.

License

This library is licensed as MIT

HdrHistogram_c is licensed as BSD license

zlib is licensed as zlib License