Debian Codegraph @

sdk/metric/metricdata/data.go

raw
1 // Copyright The OpenTelemetry Authors
2 // SPDX-License-Identifier: Apache-2.0
3
4 // Package metricdata provides types for the metric SDK data model.
5 package metricdata // import "go.opentelemetry.io/otel/sdk/metric/metricdata"
6
7 import (
8 "encoding/json"
9 "time"
10
11 "go.opentelemetry.io/otel/attribute"
12 "go.opentelemetry.io/otel/sdk/instrumentation"
13 "go.opentelemetry.io/otel/sdk/resource"
14 )
15
16 // ResourceMetrics is a collection of ScopeMetrics and the associated Resource
17 // that created them.
18 type ResourceMetrics struct {
19 // Resource represents the entity that collected the metrics.
20 Resource *resource.Resource
21 // ScopeMetrics are the collection of metrics with unique Scopes.
22 ScopeMetrics []ScopeMetrics
23 }
24
25 // ScopeMetrics is a collection of Metrics Produces by a Meter.
26 type ScopeMetrics struct {
27 // Scope is the Scope that the Meter was created with.
28 Scope instrumentation.Scope
29 // Metrics are a list of aggregations created by the Meter.
30 Metrics []Metrics
31 }
32
33 // Metrics is a collection of one or more aggregated timeseries from an Instrument.
34 type Metrics struct {
35 // Name is the name of the Instrument that created this data.
36 Name string
37 // Description is the description of the Instrument, which can be used in documentation.
38 Description string
39 // Unit is the unit in which the Instrument reports.
40 Unit string
41 // Data is the aggregated data from an Instrument.
42 Data Aggregation
43 }
44
45 // Aggregation is the store of data reported by an Instrument.
46 // It will be one of: Gauge, Sum, Histogram.
47 type Aggregation interface {
48 privateAggregation()
49 }
50
51 // Gauge represents a measurement of the current value of an instrument.
52 type Gauge[N int64 | float64] struct {
53 // DataPoints are the individual aggregated measurements with unique
54 // Attributes.
55 DataPoints []DataPoint[N]
56 }
57
58 func (Gauge[N]) privateAggregation() {}
59
60 // Sum represents the sum of all measurements of values from an instrument.
61 type Sum[N int64 | float64] struct {
62 // DataPoints are the individual aggregated measurements with unique
63 // Attributes.
64 DataPoints []DataPoint[N]
65 // Temporality describes if the aggregation is reported as the change from the
66 // last report time, or the cumulative changes since a fixed start time.
67 Temporality Temporality
68 // IsMonotonic represents if this aggregation only increases or decreases.
69 IsMonotonic bool
70 }
71
72 func (Sum[N]) privateAggregation() {}
73
74 // DataPoint is a single data point in a timeseries.
75 type DataPoint[N int64 | float64] struct {
76 // Attributes is the set of key value pairs that uniquely identify the
77 // timeseries.
78 Attributes attribute.Set
79 // StartTime is when the timeseries was started. (optional)
80 StartTime time.Time `json:",omitempty"`
81 // Time is the time when the timeseries was recorded. (optional)
82 Time time.Time `json:",omitempty"`
83 // Value is the value of this data point.
84 Value N
85
86 // Exemplars is the sampled Exemplars collected during the timeseries.
87 Exemplars []Exemplar[N] `json:",omitempty"`
88 }
89
90 // Histogram represents the histogram of all measurements of values from an instrument.
91 type Histogram[N int64 | float64] struct {
92 // DataPoints are the individual aggregated measurements with unique
93 // Attributes.
94 DataPoints []HistogramDataPoint[N]
95 // Temporality describes if the aggregation is reported as the change from the
96 // last report time, or the cumulative changes since a fixed start time.
97 Temporality Temporality
98 }
99
100 func (Histogram[N]) privateAggregation() {}
101
102 // HistogramDataPoint is a single histogram data point in a timeseries.
103 type HistogramDataPoint[N int64 | float64] struct {
104 // Attributes is the set of key value pairs that uniquely identify the
105 // timeseries.
106 Attributes attribute.Set
107 // StartTime is when the timeseries was started.
108 StartTime time.Time
109 // Time is the time when the timeseries was recorded.
110 Time time.Time
111
112 // Count is the number of updates this histogram has been calculated with.
113 Count uint64
114 // Bounds are the upper bounds of the buckets of the histogram. Because the
115 // last boundary is +infinity this one is implied.
116 Bounds []float64
117 // BucketCounts is the count of each of the buckets.
118 BucketCounts []uint64
119
120 // Min is the minimum value recorded. (optional)
121 Min Extrema[N]
122 // Max is the maximum value recorded. (optional)
123 Max Extrema[N]
124 // Sum is the sum of the values recorded.
125 Sum N
126
127 // Exemplars is the sampled Exemplars collected during the timeseries.
128 Exemplars []Exemplar[N] `json:",omitempty"`
129 }
130
131 // ExponentialHistogram represents the histogram of all measurements of values from an instrument.
132 type ExponentialHistogram[N int64 | float64] struct {
133 // DataPoints are the individual aggregated measurements with unique
134 // attributes.
135 DataPoints []ExponentialHistogramDataPoint[N]
136 // Temporality describes if the aggregation is reported as the change from the
137 // last report time, or the cumulative changes since a fixed start time.
138 Temporality Temporality
139 }
140
141 func (ExponentialHistogram[N]) privateAggregation() {}
142
143 // ExponentialHistogramDataPoint is a single exponential histogram data point in a timeseries.
144 type ExponentialHistogramDataPoint[N int64 | float64] struct {
145 // Attributes is the set of key value pairs that uniquely identify the
146 // timeseries.
147 Attributes attribute.Set
148 // StartTime is when the timeseries was started.
149 StartTime time.Time
150 // Time is the time when the timeseries was recorded.
151 Time time.Time
152
153 // Count is the number of updates this histogram has been calculated with.
154 Count uint64
155 // Min is the minimum value recorded. (optional)
156 Min Extrema[N]
157 // Max is the maximum value recorded. (optional)
158 Max Extrema[N]
159 // Sum is the sum of the values recorded.
160 Sum N
161
162 // Scale describes the resolution of the histogram. Boundaries are
163 // located at powers of the base, where:
164 //
165 // base = 2 ^ (2 ^ -Scale)
166 Scale int32
167 // ZeroCount is the number of values whose absolute value
168 // is less than or equal to [ZeroThreshold].
169 // When ZeroThreshold is 0, this is the number of values that
170 // cannot be expressed using the standard exponential formula
171 // as well as values that have been rounded to zero.
172 // ZeroCount represents the special zero count bucket.
173 ZeroCount uint64
174
175 // PositiveBucket is range of positive value bucket counts.
176 PositiveBucket ExponentialBucket
177 // NegativeBucket is range of negative value bucket counts.
178 NegativeBucket ExponentialBucket
179
180 // ZeroThreshold is the width of the zero region. Where the zero region is
181 // defined as the closed interval [-ZeroThreshold, ZeroThreshold].
182 ZeroThreshold float64
183
184 // Exemplars is the sampled Exemplars collected during the timeseries.
185 Exemplars []Exemplar[N] `json:",omitempty"`
186 }
187
188 // ExponentialBucket are a set of bucket counts, encoded in a contiguous array
189 // of counts.
190 type ExponentialBucket struct {
191 // Offset is the bucket index of the first entry in the Counts slice.
192 Offset int32
193 // Counts is an slice where Counts[i] carries the count of the bucket at
194 // index (Offset+i). Counts[i] is the count of values greater than
195 // base^(Offset+i) and less than or equal to base^(Offset+i+1).
196 Counts []uint64
197 }
198
199 // Extrema is the minimum or maximum value of a dataset.
200 type Extrema[N int64 | float64] struct {
201 value N
202 valid bool
203 }
204
205 // MarshalText converts the Extrema value to text.
206 func (e Extrema[N]) MarshalText() ([]byte, error) {
207 if !e.valid {
208 return json.Marshal(nil)
209 }
210 return json.Marshal(e.value)
211 }
212
213 // MarshalJSON converts the Extrema value to JSON number.
214 func (e *Extrema[N]) MarshalJSON() ([]byte, error) {
215 return e.MarshalText()
216 }
217
218 // NewExtrema returns an Extrema set to v.
219 func NewExtrema[N int64 | float64](v N) Extrema[N] {
220 return Extrema[N]{value: v, valid: true}
221 }
222
223 // Value returns the Extrema value and true if the Extrema is defined.
224 // Otherwise, if the Extrema is its zero-value, defined will be false.
225 func (e Extrema[N]) Value() (v N, defined bool) {
226 return e.value, e.valid
227 }
228
229 // Exemplar is a measurement sampled from a timeseries providing a typical
230 // example.
231 type Exemplar[N int64 | float64] struct {
232 // FilteredAttributes are the attributes recorded with the measurement but
233 // filtered out of the timeseries' aggregated data.
234 FilteredAttributes []attribute.KeyValue
235 // Time is the time when the measurement was recorded.
236 Time time.Time
237 // Value is the measured value.
238 Value N
239 // SpanID is the ID of the span that was active during the measurement. If
240 // no span was active or the span was not sampled this will be empty.
241 SpanID []byte `json:",omitempty"`
242 // TraceID is the ID of the trace the active span belonged to during the
243 // measurement. If no span was active or the span was not sampled this will
244 // be empty.
245 TraceID []byte `json:",omitempty"`
246 }
247
248 // Summary metric data are used to convey quantile summaries,
249 // a Prometheus (see: https://prometheus.io/docs/concepts/metric_types/#summary)
250 // data type.
251 //
252 // These data points cannot always be merged in a meaningful way. The Summary
253 // type is only used by bridges from other metrics libraries, and cannot be
254 // produced using OpenTelemetry instrumentation.
255 type Summary struct {
256 // DataPoints are the individual aggregated measurements with unique
257 // attributes.
258 DataPoints []SummaryDataPoint
259 }
260
261 func (Summary) privateAggregation() {}
262
263 // SummaryDataPoint is a single data point in a timeseries that describes the
264 // time-varying values of a Summary metric.
265 type SummaryDataPoint struct {
266 // Attributes is the set of key value pairs that uniquely identify the
267 // timeseries.
268 Attributes attribute.Set
269
270 // StartTime is when the timeseries was started.
271 StartTime time.Time
272 // Time is the time when the timeseries was recorded.
273 Time time.Time
274
275 // Count is the number of updates this summary has been calculated with.
276 Count uint64
277
278 // Sum is the sum of the values recorded.
279 Sum float64
280
281 // (Optional) list of values at different quantiles of the distribution calculated
282 // from the current snapshot. The quantiles must be strictly increasing.
283 QuantileValues []QuantileValue
284 }
285
286 // QuantileValue is the value at a given quantile of a summary.
287 type QuantileValue struct {
288 // Quantile is the quantile of this value.
289 //
290 // Must be in the interval [0.0, 1.0].
291 Quantile float64
292
293 // Value is the value at the given quantile of a summary.
294 //
295 // Quantile values must NOT be negative.
296 Value float64
297 }