blob: dbc837fe4d9541f5a3d93f1a4aab00a433edf163 [file] [log] [blame]
Takahiro Suzukid7bf8202020-12-17 20:21:59 +09001package 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() }