hdrhistogram

README

hdrhistogram

A pure Go implementation of the HDR Histogram.

A Histogram that supports recording and analyzing sampled data value counts across a configurable integer value range with configurable value precision within the range. Value precision is expressed as the number of significant digits in the value recording, and provides control over value quantization behavior across the value range and the subsequent value resolution at any given level.

For documentation, check godoc.

Documentation

Overview

Package hdrhistogram provides an implementation of Gil Tene's HDR Histogram data structure. The HDR Histogram allows for fast and accurate analysis of the extreme ranges of data with non-normal distributions, like latency.

Index

• type Bar
  • func (b Bar) String() string
• type Bracket
• type Histogram
  • func Import(s *Snapshot) *Histogram
  • func New(minValue, maxValue int64, sigfigs int) *Histogram
  • func (h *Histogram) ByteSize() int
  • func (h *Histogram) CumulativeDistribution() []Bracket
  • func (h *Histogram) Distribution() (result []Bar)
  • func (h *Histogram) Equals(other *Histogram) bool
  • func (h *Histogram) Export() *Snapshot
  • func (h *Histogram) HighestTrackableValue() int64
  • func (h *Histogram) LowestTrackableValue() int64
  • func (h *Histogram) Max() int64
  • func (h *Histogram) Mean() float64
  • func (h *Histogram) Merge(from *Histogram) (dropped int64)
  • func (h *Histogram) Min() int64
  • func (h *Histogram) RecordCorrectedValue(v, expectedInterval int64) error
  • func (h *Histogram) RecordValue(v int64) error
  • func (h *Histogram) RecordValues(v, n int64) error
  • func (h *Histogram) Reset()
  • func (h *Histogram) SignificantFigures() int64
  • func (h *Histogram) StdDev() float64
  • func (h *Histogram) TotalCount() int64
  • func (h *Histogram) ValueAtQuantile(q float64) int64
• type Snapshot
• type WindowedHistogram
  • func NewWindowed(n int, minValue, maxValue int64, sigfigs int) *WindowedHistogram
  • func (w *WindowedHistogram) Merge() *Histogram
  • func (w *WindowedHistogram) Rotate()

Types

type Bar

type Bar struct {
	From, To, Count int64
}

Histogram bar for plotting

func (Bar) String

func (b Bar) String() string

Pretty print as csv for easy plotting

type Bracket

type Bracket struct {
	Quantile       float64
	Count, ValueAt int64
}

A Bracket is a part of a cumulative distribution.

type Histogram

type Histogram struct {
	// contains filtered or unexported fields
}

A Histogram is a lossy data structure used to record the distribution of non-normally distributed data (like latency) with a high degree of accuracy and a bounded degree of precision.

func Import

func Import(s *Snapshot) *Histogram

Import returns a new Histogram populated from the Snapshot data (which the caller must stop accessing).

func New

func New(minValue, maxValue int64, sigfigs int) *Histogram

New returns a new Histogram instance capable of tracking values in the given range and with the given amount of precision.

func (*Histogram) ByteSize

func (h *Histogram) ByteSize() int

ByteSize returns an estimate of the amount of memory allocated to the histogram in bytes.

N.B.: This does not take into account the overhead for slices, which are small, constant, and specific to the compiler version.

func (*Histogram) CumulativeDistribution

func (h *Histogram) CumulativeDistribution() []Bracket

CumulativeDistribution returns an ordered list of brackets of the distribution of recorded values.

func (*Histogram) Distribution

func (h *Histogram) Distribution() (result []Bar)

Distribution returns an ordered list of bars of the distribution of recorded values, counts can be normalized to a probability

func (*Histogram) Equals

func (h *Histogram) Equals(other *Histogram) bool

Equals returns true if the two Histograms are equivalent, false if not.

func (*Histogram) Export

func (h *Histogram) Export() *Snapshot

Export returns a snapshot view of the Histogram. This can be later passed to Import to construct a new Histogram with the same state.

func (*Histogram) HighestTrackableValue

func (h *Histogram) HighestTrackableValue() int64

HighestTrackableValue returns the upper bound on values that will be added to the histogram

func (*Histogram) LowestTrackableValue

func (h *Histogram) LowestTrackableValue() int64

LowestTrackableValue returns the lower bound on values that will be added to the histogram

func (*Histogram) Max

func (h *Histogram) Max() int64

Max returns the approximate maximum recorded value.

func (*Histogram) Mean

func (h *Histogram) Mean() float64

Mean returns the approximate arithmetic mean of the recorded values.

func (*Histogram) Merge

func (h *Histogram) Merge(from *Histogram) (dropped int64)

Merge merges the data stored in the given histogram with the receiver, returning the number of recorded values which had to be dropped.

func (*Histogram) Min

func (h *Histogram) Min() int64

Min returns the approximate minimum recorded value.

func (*Histogram) RecordCorrectedValue

func (h *Histogram) RecordCorrectedValue(v, expectedInterval int64) error

RecordCorrectedValue records the given value, correcting for stalls in the recording process. This only works for processes which are recording values at an expected interval (e.g., doing jitter analysis). Processes which are recording ad-hoc values (e.g., latency for incoming requests) can't take advantage of this.

func (*Histogram) RecordValue

func (h *Histogram) RecordValue(v int64) error

RecordValue records the given value, returning an error if the value is out of range.

func (*Histogram) RecordValues

func (h *Histogram) RecordValues(v, n int64) error

RecordValues records n occurrences of the given value, returning an error if the value is out of range.

func (*Histogram) Reset

func (h *Histogram) Reset()

Reset deletes all recorded values and restores the histogram to its original state.

func (*Histogram) SignificantFigures

func (h *Histogram) SignificantFigures() int64

SignificantFigures returns the significant figures used to create the histogram

func (*Histogram) StdDev

func (h *Histogram) StdDev() float64

StdDev returns the approximate standard deviation of the recorded values.

func (*Histogram) TotalCount

func (h *Histogram) TotalCount() int64

TotalCount returns total number of values recorded.

func (*Histogram) ValueAtQuantile

func (h *Histogram) ValueAtQuantile(q float64) int64

ValueAtQuantile returns the recorded value at the given quantile (0..100).

type Snapshot

type Snapshot struct {
	LowestTrackableValue  int64
	HighestTrackableValue int64
	SignificantFigures    int64
	Counts                []int64
}

A Snapshot is an exported view of a Histogram, useful for serializing them. A Histogram can be constructed from it by passing it to Import.

type WindowedHistogram

type WindowedHistogram struct {
	Current *Histogram
	// contains filtered or unexported fields
}

A WindowedHistogram combines histograms to provide windowed statistics.

func NewWindowed

func NewWindowed(n int, minValue, maxValue int64, sigfigs int) *WindowedHistogram

NewWindowed creates a new WindowedHistogram with N underlying histograms with the given parameters.

func (*WindowedHistogram) Merge

func (w *WindowedHistogram) Merge() *Histogram

Merge returns a histogram which includes the recorded values from all the sections of the window.

func (*WindowedHistogram) Rotate

func (w *WindowedHistogram) Rotate()

Rotate resets the oldest histogram and rotates it to be used as the current histogram.