Debian Codegraph @

sdk/metric/aggregation.go

raw
1 // Copyright The OpenTelemetry Authors
2 // SPDX-License-Identifier: Apache-2.0
3
4 package metric // import "go.opentelemetry.io/otel/sdk/metric"
5
6 import (
7 "errors"
8 "fmt"
9 "slices"
10 )
11
12 // errAgg is wrapped by misconfigured aggregations.
13 var errAgg = errors.New("aggregation")
14
15 // Aggregation is the aggregation used to summarize recorded measurements.
16 type Aggregation interface {
17 // copy returns a deep copy of the Aggregation.
18 copy() Aggregation
19
20 // err returns an error for any misconfigured Aggregation.
21 err() error
22 }
23
24 // AggregationDrop is an Aggregation that drops all recorded data.
25 type AggregationDrop struct{} // AggregationDrop has no parameters.
26
27 var _ Aggregation = AggregationDrop{}
28
29 // copy returns a deep copy of d.
30 func (d AggregationDrop) copy() Aggregation { return d }
31
32 // err returns an error for any misconfiguration. A drop aggregation has no
33 // parameters and cannot be misconfigured, therefore this always returns nil.
34 func (AggregationDrop) err() error { return nil }
35
36 // AggregationDefault is an Aggregation that uses the default instrument kind selection
37 // mapping to select another Aggregation. A metric reader can be configured to
38 // make an aggregation selection based on instrument kind that differs from
39 // the default. This Aggregation ensures the default is used.
40 //
41 // See the [DefaultAggregationSelector] for information about the default
42 // instrument kind selection mapping.
43 type AggregationDefault struct{} // AggregationDefault has no parameters.
44
45 var _ Aggregation = AggregationDefault{}
46
47 // copy returns a deep copy of d.
48 func (d AggregationDefault) copy() Aggregation { return d }
49
50 // err returns an error for any misconfiguration. A default aggregation has no
51 // parameters and cannot be misconfigured, therefore this always returns nil.
52 func (AggregationDefault) err() error { return nil }
53
54 // AggregationSum is an Aggregation that summarizes a set of measurements as their
55 // arithmetic sum.
56 type AggregationSum struct{} // AggregationSum has no parameters.
57
58 var _ Aggregation = AggregationSum{}
59
60 // copy returns a deep copy of s.
61 func (s AggregationSum) copy() Aggregation { return s }
62
63 // err returns an error for any misconfiguration. A sum aggregation has no
64 // parameters and cannot be misconfigured, therefore this always returns nil.
65 func (AggregationSum) err() error { return nil }
66
67 // AggregationLastValue is an Aggregation that summarizes a set of measurements as the
68 // last one made.
69 type AggregationLastValue struct{} // AggregationLastValue has no parameters.
70
71 var _ Aggregation = AggregationLastValue{}
72
73 // copy returns a deep copy of l.
74 func (l AggregationLastValue) copy() Aggregation { return l }
75
76 // err returns an error for any misconfiguration. A last-value aggregation has
77 // no parameters and cannot be misconfigured, therefore this always returns
78 // nil.
79 func (AggregationLastValue) err() error { return nil }
80
81 // AggregationExplicitBucketHistogram is an Aggregation that summarizes a set of
82 // measurements as an histogram with explicitly defined buckets.
83 type AggregationExplicitBucketHistogram struct {
84 // Boundaries are the increasing bucket boundary values. Boundary values
85 // define bucket upper bounds. Buckets are exclusive of their lower
86 // boundary and inclusive of their upper bound (except at positive
87 // infinity). A measurement is defined to fall into the greatest-numbered
88 // bucket with a boundary that is greater than or equal to the
89 // measurement. As an example, boundaries defined as:
90 //
91 // []float64{0, 5, 10, 25, 50, 75, 100, 250, 500, 1000}
92 //
93 // Will define these buckets:
94 //
95 // (-∞, 0], (0, 5.0], (5.0, 10.0], (10.0, 25.0], (25.0, 50.0],
96 // (50.0, 75.0], (75.0, 100.0], (100.0, 250.0], (250.0, 500.0],
97 // (500.0, 1000.0], (1000.0, +∞)
98 Boundaries []float64
99 // NoMinMax indicates whether to not record the min and max of the
100 // distribution. By default, these extrema are recorded.
101 //
102 // Recording these extrema for cumulative data is expected to have little
103 // value, they will represent the entire life of the instrument instead of
104 // just the current collection cycle. It is recommended to set this to true
105 // for that type of data to avoid computing the low-value extrema.
106 NoMinMax bool
107 }
108
109 var _ Aggregation = AggregationExplicitBucketHistogram{}
110
111 // errHist is returned by misconfigured ExplicitBucketHistograms.
112 var errHist = fmt.Errorf("%w: explicit bucket histogram", errAgg)
113
114 // err returns an error for any misconfiguration.
115 func (h AggregationExplicitBucketHistogram) err() error {
116 if len(h.Boundaries) <= 1 {
117 return nil
118 }
119
120 // Check boundaries are monotonic.
121 i := h.Boundaries[0]
122 for _, j := range h.Boundaries[1:] {
123 if i >= j {
124 return fmt.Errorf("%w: non-monotonic boundaries: %v", errHist, h.Boundaries)
125 }
126 i = j
127 }
128
129 return nil
130 }
131
132 // copy returns a deep copy of h.
133 func (h AggregationExplicitBucketHistogram) copy() Aggregation {
134 return AggregationExplicitBucketHistogram{
135 Boundaries: slices.Clone(h.Boundaries),
136 NoMinMax: h.NoMinMax,
137 }
138 }
139
140 // AggregationBase2ExponentialHistogram is an Aggregation that summarizes a set of
141 // measurements as an histogram with bucket widths that grow exponentially.
142 type AggregationBase2ExponentialHistogram struct {
143 // MaxSize is the maximum number of buckets to use for the histogram.
144 MaxSize int32
145 // MaxScale is the maximum resolution scale to use for the histogram.
146 //
147 // MaxScale has a maximum value of 20. Using a value of 20 means the
148 // maximum number of buckets that can fit within the range of a
149 // signed 32-bit integer index could be used.
150 //
151 // MaxScale has a minimum value of -10. Using a value of -10 means only
152 // two buckets will be used.
153 MaxScale int32
154
155 // NoMinMax indicates whether to not record the min and max of the
156 // distribution. By default, these extrema are recorded.
157 //
158 // Recording these extrema for cumulative data is expected to have little
159 // value, they will represent the entire life of the instrument instead of
160 // just the current collection cycle. It is recommended to set this to true
161 // for that type of data to avoid computing the low-value extrema.
162 NoMinMax bool
163 }
164
165 var _ Aggregation = AggregationBase2ExponentialHistogram{}
166
167 // copy returns a deep copy of the Aggregation.
168 func (e AggregationBase2ExponentialHistogram) copy() Aggregation {
169 return e
170 }
171
172 const (
173 expoMaxScale = 20
174 expoMinScale = -10
175 )
176
177 // errExpoHist is returned by misconfigured Base2ExponentialBucketHistograms.
178 var errExpoHist = fmt.Errorf("%w: exponential histogram", errAgg)
179
180 // err returns an error for any misconfigured Aggregation.
181 func (e AggregationBase2ExponentialHistogram) err() error {
182 if e.MaxScale > expoMaxScale {
183 return fmt.Errorf("%w: max size %d is greater than maximum scale %d", errExpoHist, e.MaxSize, expoMaxScale)
184 }
185 if e.MaxSize <= 0 {
186 return fmt.Errorf("%w: max size %d is less than or equal to zero", errExpoHist, e.MaxSize)
187 }
188 return nil
189 }