ghistogram

README

ghistogram

Simple histogram for golang that avoids runtime memory allocations.

Documentation

Index

• type Histogram
  • func NewHistogram(numBins int, binFirst uint64, binGrowthFactor float64) *Histogram
  • func NewNamedHistogram(name string, numBins int, binFirst uint64, binGrowthFactor float64) *Histogram
  • func (gh *Histogram) Add(dataPoint uint64, count uint64)
  • func (gh *Histogram) AddAll(src *Histogram)
  • func (gh *Histogram) CallSync(f func())
  • func (gh *Histogram) CallSyncEx(f func(HistogramMutator))
  • func (gh *Histogram) CloneEmpty() *Histogram
  • func (gh *Histogram) EmitGraph(prefix []byte, out *bytes.Buffer) *bytes.Buffer
• type HistogramMutator
• type Histograms
  • func (hmap Histograms) AddAll(srcmap Histograms) error
  • func (hmap Histograms) Fprint(w io.Writer) (int, error)
  • func (hmap Histograms) String() string

Types

type Histogram

type Histogram struct {
	// Histogram name.
	Name string

	// Ranges holds the lower domain bounds of bins, so bin i has data
	// point domain of "[Ranges[i], Ranges[i+1])".  Related,
	// Ranges[0] == 0 and Ranges[1] == binFirst.
	Ranges []uint64

	// Counts holds the event counts for bins.
	Counts []uint64

	// TotCount is the sum of all counts.
	TotCount uint64

	TotDataPoint uint64 // TotDataPoint is the sum of all data points.
	MinDataPoint uint64 // MinDataPoint is the smallest data point seen.
	MaxDataPoint uint64 // MaxDataPoint is the largest data point seen.
	// contains filtered or unexported fields
}

Histogram is a simple uint64 histogram implementation that avoids heap allocations during its processing of incoming data points.

It was motivated for tracking simple performance timings.

The histogram bins are split across the two arrays of Ranges and Counts, where len(Ranges) == len(Counts). These arrays are public in case users wish to use reflection or JSON marhsaling.

An optional growth factor for bin sizes is supported - see NewHistogram() binGrowthFactor parameter.

The histogram is concurrent safe.

func NewHistogram

func NewHistogram(
	numBins int,
	binFirst uint64,
	binGrowthFactor float64) *Histogram

Creates a new Histogram whose name is "histogram"

func NewNamedHistogram

func NewNamedHistogram(
	name string,
	numBins int,
	binFirst uint64,
	binGrowthFactor float64) *Histogram

NewNamedHistogram creates a new, ready to use Histogram. The numBins must be >= 2. The binFirst is the width of the first bin. The binGrowthFactor must be > 1.0 or 0.0.

A special case of binGrowthFactor of 0.0 means the the allocated bins will have constant, non-growing size or "width".

func (*Histogram) Add

func (gh *Histogram) Add(dataPoint uint64, count uint64)

Add increases the count in the bin for the given dataPoint in a concurrent-safe manner.

func (*Histogram) AddAll

func (gh *Histogram) AddAll(src *Histogram)

AddAll adds all the Counts from the src histogram into this histogram. The src and this histogram must either have the same exact creation parameters.

func (*Histogram) CallSync

func (gh *Histogram) CallSync(f func())

CallSync invokes the callback func while the histogram is locked.

func (*Histogram) CallSyncEx

func (gh *Histogram) CallSyncEx(f func(HistogramMutator))

CallSyncEx invokes the callback func with a HistogramMutator while the histogram is locked. This allows apps to perform multiple updates to a histogram without incurring locking costs on each update.

func (*Histogram) CloneEmpty

func (gh *Histogram) CloneEmpty() *Histogram

Creates a new Histogram whose name and ranges are identical to the one provided. Note that the entries are not copied.

func (*Histogram) EmitGraph

func (gh *Histogram) EmitGraph(prefix []byte,
	out *bytes.Buffer) *bytes.Buffer

EmitGraph emits an ascii graph to the optional out buffer, allocating an out buffer if none was supplied. Returns the out buffer. Each line emitted may have an optional prefix.

For example:

TestGraph (48 Total)
[0 - 10]        4.17%    4.17% ### (2)
[10 - 20]      41.67%   45.83% ############################## (20)
[20 - 40]      20.83%   66.67% ############### (10)
[40 - inf]     33.33%  100.00% ####################### (16)

type HistogramMutator

type HistogramMutator interface {
	Add(dataPoint uint64, count uint64)
}

HistogramMutator represents the subset of Histogram methods related to mutation operations.

type Histograms

type Histograms map[string]*Histogram

Histograms represents a map of histograms identified by unique names (string).

func (Histograms) AddAll

func (hmap Histograms) AddAll(srcmap Histograms) error

Adds all entries/records from all histograms within the given map, to all histograms in the current map. If a histogram from the source doesn't exist in the destination map, it will be created first.

func (Histograms) Fprint

func (hmap Histograms) Fprint(w io.Writer) (int, error)

Emits the ASCII graphs of all histograms held within the map through the provided writer.

func (Histograms) String

func (hmap Histograms) String() string

API that converts the contents of all histograms within the map into a string and returns the string to caller.