Scott Baker | e7144bc | 2019-10-01 14:16:47 -0700 | [diff] [blame^] | 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() } |