Debian Codegraph @

histogram.go

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