/histogram.go
Go | 202 lines | 98 code | 46 blank | 58 comment | 5 complexity | d76284bee710901f90fd45e4e54a8e9e MD5 | raw file
1package metrics 2 3// Histograms calculate distribution statistics from a series of int64 values. 4type Histogram interface { 5 Clear() 6 Count() int64 7 Max() int64 8 Mean() float64 9 Min() int64 10 Percentile(float64) float64 11 Percentiles([]float64) []float64 12 Sample() Sample 13 Snapshot() Histogram 14 StdDev() float64 15 Sum() int64 16 Update(int64) 17 Variance() float64 18} 19 20// GetOrRegisterHistogram returns an existing Histogram or constructs and 21// registers a new StandardHistogram. 22func GetOrRegisterHistogram(name string, r Registry, s Sample) Histogram { 23 if nil == r { 24 r = DefaultRegistry 25 } 26 return r.GetOrRegister(name, func() Histogram { return NewHistogram(s) }).(Histogram) 27} 28 29// NewHistogram constructs a new StandardHistogram from a Sample. 30func NewHistogram(s Sample) Histogram { 31 if UseNilMetrics { 32 return NilHistogram{} 33 } 34 return &StandardHistogram{sample: s} 35} 36 37// NewRegisteredHistogram constructs and registers a new StandardHistogram from 38// a Sample. 39func NewRegisteredHistogram(name string, r Registry, s Sample) Histogram { 40 c := NewHistogram(s) 41 if nil == r { 42 r = DefaultRegistry 43 } 44 r.Register(name, c) 45 return c 46} 47 48// HistogramSnapshot is a read-only copy of another Histogram. 49type HistogramSnapshot struct { 50 sample *SampleSnapshot 51} 52 53// Clear panics. 54func (*HistogramSnapshot) Clear() { 55 panic("Clear called on a HistogramSnapshot") 56} 57 58// Count returns the number of samples recorded at the time the snapshot was 59// taken. 60func (h *HistogramSnapshot) Count() int64 { return h.sample.Count() } 61 62// Max returns the maximum value in the sample at the time the snapshot was 63// taken. 64func (h *HistogramSnapshot) Max() int64 { return h.sample.Max() } 65 66// Mean returns the mean of the values in the sample at the time the snapshot 67// was taken. 68func (h *HistogramSnapshot) Mean() float64 { return h.sample.Mean() } 69 70// Min returns the minimum value in the sample at the time the snapshot was 71// taken. 72func (h *HistogramSnapshot) Min() int64 { return h.sample.Min() } 73 74// Percentile returns an arbitrary percentile of values in the sample at the 75// time the snapshot was taken. 76func (h *HistogramSnapshot) Percentile(p float64) float64 { 77 return h.sample.Percentile(p) 78} 79 80// Percentiles returns a slice of arbitrary percentiles of values in the sample 81// at the time the snapshot was taken. 82func (h *HistogramSnapshot) Percentiles(ps []float64) []float64 { 83 return h.sample.Percentiles(ps) 84} 85 86// Sample returns the Sample underlying the histogram. 87func (h *HistogramSnapshot) Sample() Sample { return h.sample } 88 89// Snapshot returns the snapshot. 90func (h *HistogramSnapshot) Snapshot() Histogram { return h } 91 92// StdDev returns the standard deviation of the values in the sample at the 93// time the snapshot was taken. 94func (h *HistogramSnapshot) StdDev() float64 { return h.sample.StdDev() } 95 96// Sum returns the sum in the sample at the time the snapshot was taken. 97func (h *HistogramSnapshot) Sum() int64 { return h.sample.Sum() } 98 99// Update panics. 100func (*HistogramSnapshot) Update(int64) { 101 panic("Update called on a HistogramSnapshot") 102} 103 104// Variance returns the variance of inputs at the time the snapshot was taken. 105func (h *HistogramSnapshot) Variance() float64 { return h.sample.Variance() } 106 107// NilHistogram is a no-op Histogram. 108type NilHistogram struct{} 109 110// Clear is a no-op. 111func (NilHistogram) Clear() {} 112 113// Count is a no-op. 114func (NilHistogram) Count() int64 { return 0 } 115 116// Max is a no-op. 117func (NilHistogram) Max() int64 { return 0 } 118 119// Mean is a no-op. 120func (NilHistogram) Mean() float64 { return 0.0 } 121 122// Min is a no-op. 123func (NilHistogram) Min() int64 { return 0 } 124 125// Percentile is a no-op. 126func (NilHistogram) Percentile(p float64) float64 { return 0.0 } 127 128// Percentiles is a no-op. 129func (NilHistogram) Percentiles(ps []float64) []float64 { 130 return make([]float64, len(ps)) 131} 132 133// Sample is a no-op. 134func (NilHistogram) Sample() Sample { return NilSample{} } 135 136// Snapshot is a no-op. 137func (NilHistogram) Snapshot() Histogram { return NilHistogram{} } 138 139// StdDev is a no-op. 140func (NilHistogram) StdDev() float64 { return 0.0 } 141 142// Sum is a no-op. 143func (NilHistogram) Sum() int64 { return 0 } 144 145// Update is a no-op. 146func (NilHistogram) Update(v int64) {} 147 148// Variance is a no-op. 149func (NilHistogram) Variance() float64 { return 0.0 } 150 151// StandardHistogram is the standard implementation of a Histogram and uses a 152// Sample to bound its memory use. 153type StandardHistogram struct { 154 sample Sample 155} 156 157// Clear clears the histogram and its sample. 158func (h *StandardHistogram) Clear() { h.sample.Clear() } 159 160// Count returns the number of samples recorded since the histogram was last 161// cleared. 162func (h *StandardHistogram) Count() int64 { return h.sample.Count() } 163 164// Max returns the maximum value in the sample. 165func (h *StandardHistogram) Max() int64 { return h.sample.Max() } 166 167// Mean returns the mean of the values in the sample. 168func (h *StandardHistogram) Mean() float64 { return h.sample.Mean() } 169 170// Min returns the minimum value in the sample. 171func (h *StandardHistogram) Min() int64 { return h.sample.Min() } 172 173// Percentile returns an arbitrary percentile of the values in the sample. 174func (h *StandardHistogram) Percentile(p float64) float64 { 175 return h.sample.Percentile(p) 176} 177 178// Percentiles returns a slice of arbitrary percentiles of the values in the 179// sample. 180func (h *StandardHistogram) Percentiles(ps []float64) []float64 { 181 return h.sample.Percentiles(ps) 182} 183 184// Sample returns the Sample underlying the histogram. 185func (h *StandardHistogram) Sample() Sample { return h.sample } 186 187// Snapshot returns a read-only copy of the histogram. 188func (h *StandardHistogram) Snapshot() Histogram { 189 return &HistogramSnapshot{sample: h.sample.Snapshot().(*SampleSnapshot)} 190} 191 192// StdDev returns the standard deviation of the values in the sample. 193func (h *StandardHistogram) StdDev() float64 { return h.sample.StdDev() } 194 195// Sum returns the sum in the sample. 196func (h *StandardHistogram) Sum() int64 { return h.sample.Sum() } 197 198// Update samples a new value. 199func (h *StandardHistogram) Update(v int64) { h.sample.Update(v) } 200 201// Variance returns the variance of the values in the sample. 202func (h *StandardHistogram) Variance() float64 { return h.sample.Variance() }