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