/histogram.go

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