| 1 |
package metrics |
| 2 |
|
| 3 |
// Histograms calculate distribution statistics from a series of int64 values. |
| 4 |
type 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. |
| 22 |
func 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. |
| 30 |
func 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. |
| 39 |
func 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. |
| 49 |
type HistogramSnapshot struct { |
| 50 |
sample *SampleSnapshot |
| 51 |
} |
| 52 |
|
| 53 |
// Clear panics. |
| 54 |
func (*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. |
| 60 |
func (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. |
| 64 |
func (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. |
| 68 |
func (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. |
| 72 |
func (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. |
| 76 |
func (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. |
| 82 |
func (h *HistogramSnapshot) Percentiles(ps []float64) []float64 { |
| 83 |
return h.sample.Percentiles(ps) |
| 84 |
} |
| 85 |
|
| 86 |
// Sample returns the Sample underlying the histogram. |
| 87 |
func (h *HistogramSnapshot) Sample() Sample { return h.sample } |
| 88 |
|
| 89 |
// Snapshot returns the snapshot. |
| 90 |
func (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. |
| 94 |
func (h *HistogramSnapshot) StdDev() float64 { return h.sample.StdDev() } |
| 95 |
|
| 96 |
// Sum returns the sum in the sample at the time the snapshot was taken. |
| 97 |
func (h *HistogramSnapshot) Sum() int64 { return h.sample.Sum() } |
| 98 |
|
| 99 |
// Update panics. |
| 100 |
func (*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. |
| 105 |
func (h *HistogramSnapshot) Variance() float64 { return h.sample.Variance() } |
| 106 |
|
| 107 |
// NilHistogram is a no-op Histogram. |
| 108 |
type NilHistogram struct{} |
| 109 |
|
| 110 |
// Clear is a no-op. |
| 111 |
func (NilHistogram) Clear() {} |
| 112 |
|
| 113 |
// Count is a no-op. |
| 114 |
func (NilHistogram) Count() int64 { return 0 } |
| 115 |
|
| 116 |
// Max is a no-op. |
| 117 |
func (NilHistogram) Max() int64 { return 0 } |
| 118 |
|
| 119 |
// Mean is a no-op. |
| 120 |
func (NilHistogram) Mean() float64 { return 0.0 } |
| 121 |
|
| 122 |
// Min is a no-op. |
| 123 |
func (NilHistogram) Min() int64 { return 0 } |
| 124 |
|
| 125 |
// Percentile is a no-op. |
| 126 |
func (NilHistogram) Percentile(p float64) float64 { return 0.0 } |
| 127 |
|
| 128 |
// Percentiles is a no-op. |
| 129 |
func (NilHistogram) Percentiles(ps []float64) []float64 { |
| 130 |
return make([]float64, len(ps)) |
| 131 |
} |
| 132 |
|
| 133 |
// Sample is a no-op. |
| 134 |
func (NilHistogram) Sample() Sample { return NilSample{} } |
| 135 |
|
| 136 |
// Snapshot is a no-op. |
| 137 |
func (NilHistogram) Snapshot() Histogram { return NilHistogram{} } |
| 138 |
|
| 139 |
// StdDev is a no-op. |
| 140 |
func (NilHistogram) StdDev() float64 { return 0.0 } |
| 141 |
|
| 142 |
// Sum is a no-op. |
| 143 |
func (NilHistogram) Sum() int64 { return 0 } |
| 144 |
|
| 145 |
// Update is a no-op. |
| 146 |
func (NilHistogram) Update(v int64) {} |
| 147 |
|
| 148 |
// Variance is a no-op. |
| 149 |
func (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. |
| 153 |
type StandardHistogram struct { |
| 154 |
sample Sample |
| 155 |
} |
| 156 |
|
| 157 |
// Clear clears the histogram and its sample. |
| 158 |
func (h *StandardHistogram) Clear() { h.sample.Clear() } |
| 159 |
|
| 160 |
// Count returns the number of samples recorded since the histogram was last |
| 161 |
// cleared. |
| 162 |
func (h *StandardHistogram) Count() int64 { return h.sample.Count() } |
| 163 |
|
| 164 |
// Max returns the maximum value in the sample. |
| 165 |
func (h *StandardHistogram) Max() int64 { return h.sample.Max() } |
| 166 |
|
| 167 |
// Mean returns the mean of the values in the sample. |
| 168 |
func (h *StandardHistogram) Mean() float64 { return h.sample.Mean() } |
| 169 |
|
| 170 |
// Min returns the minimum value in the sample. |
| 171 |
func (h *StandardHistogram) Min() int64 { return h.sample.Min() } |
| 172 |
|
| 173 |
// Percentile returns an arbitrary percentile of the values in the sample. |
| 174 |
func (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. |
| 180 |
func (h *StandardHistogram) Percentiles(ps []float64) []float64 { |
| 181 |
return h.sample.Percentiles(ps) |
| 182 |
} |
| 183 |
|
| 184 |
// Sample returns the Sample underlying the histogram. |
| 185 |
func (h *StandardHistogram) Sample() Sample { return h.sample } |
| 186 |
|
| 187 |
// Snapshot returns a read-only copy of the histogram. |
| 188 |
func (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. |
| 193 |
func (h *StandardHistogram) StdDev() float64 { return h.sample.StdDev() } |
| 194 |
|
| 195 |
// Sum returns the sum in the sample. |
| 196 |
func (h *StandardHistogram) Sum() int64 { return h.sample.Sum() } |
| 197 |
|
| 198 |
// Update samples a new value. |
| 199 |
func (h *StandardHistogram) Update(v int64) { h.sample.Update(v) } |
| 200 |
|
| 201 |
// Variance returns the variance of the values in the sample. |
| 202 |
func (h *StandardHistogram) Variance() float64 { return h.sample.Variance() } |