| 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 |
} |