Debian Codegraph @

sdk/metric/instrument.go

raw
1 // Copyright The OpenTelemetry Authors
2 // SPDX-License-Identifier: Apache-2.0
3
4 //go:generate stringer -type=InstrumentKind -trimprefix=InstrumentKind
5
6 package metric // import "go.opentelemetry.io/otel/sdk/metric"
7
8 import (
9 "context"
10 "errors"
11 "fmt"
12 "strings"
13
14 "go.opentelemetry.io/otel/attribute"
15 "go.opentelemetry.io/otel/metric"
16 "go.opentelemetry.io/otel/metric/embedded"
17 "go.opentelemetry.io/otel/sdk/instrumentation"
18 "go.opentelemetry.io/otel/sdk/metric/internal/aggregate"
19 )
20
21 var zeroScope instrumentation.Scope
22
23 // InstrumentKind is the identifier of a group of instruments that all
24 // performing the same function.
25 type InstrumentKind uint8
26
27 const (
28 // instrumentKindUndefined is an undefined instrument kind, it should not
29 // be used by any initialized type.
30 instrumentKindUndefined InstrumentKind = 0 // nolint:unused
31 // InstrumentKindCounter identifies a group of instruments that record
32 // increasing values synchronously with the code path they are measuring.
33 InstrumentKindCounter InstrumentKind = 1
34 // InstrumentKindUpDownCounter identifies a group of instruments that
35 // record increasing and decreasing values synchronously with the code path
36 // they are measuring.
37 InstrumentKindUpDownCounter InstrumentKind = 2
38 // InstrumentKindHistogram identifies a group of instruments that record a
39 // distribution of values synchronously with the code path they are
40 // measuring.
41 InstrumentKindHistogram InstrumentKind = 3
42 // InstrumentKindObservableCounter identifies a group of instruments that
43 // record increasing values in an asynchronous callback.
44 InstrumentKindObservableCounter InstrumentKind = 4
45 // InstrumentKindObservableUpDownCounter identifies a group of instruments
46 // that record increasing and decreasing values in an asynchronous
47 // callback.
48 InstrumentKindObservableUpDownCounter InstrumentKind = 5
49 // InstrumentKindObservableGauge identifies a group of instruments that
50 // record current values in an asynchronous callback.
51 InstrumentKindObservableGauge InstrumentKind = 6
52 // InstrumentKindGauge identifies a group of instruments that record
53 // instantaneous values synchronously with the code path they are
54 // measuring.
55 InstrumentKindGauge InstrumentKind = 7
56 )
57
58 type nonComparable [0]func() // nolint: unused // This is indeed used.
59
60 // Instrument describes properties an instrument is created with.
61 type Instrument struct {
62 // Name is the human-readable identifier of the instrument.
63 Name string
64 // Description describes the purpose of the instrument.
65 Description string
66 // Kind defines the functional group of the instrument.
67 Kind InstrumentKind
68 // Unit is the unit of measurement recorded by the instrument.
69 Unit string
70 // Scope identifies the instrumentation that created the instrument.
71 Scope instrumentation.Scope
72
73 // Ensure forward compatibility if non-comparable fields need to be added.
74 nonComparable // nolint: unused
75 }
76
77 // IsEmpty reports whether all Instrument fields are their zero-value.
78 func (i Instrument) IsEmpty() bool {
79 return i.Name == "" &&
80 i.Description == "" &&
81 i.Kind == instrumentKindUndefined &&
82 i.Unit == "" &&
83 i.Scope == zeroScope
84 }
85
86 // matches returns whether all the non-zero-value fields of i match the
87 // corresponding fields of other. If i is empty it will match all other, and
88 // true will always be returned.
89 func (i Instrument) matches(other Instrument) bool {
90 return i.matchesName(other) &&
91 i.matchesDescription(other) &&
92 i.matchesKind(other) &&
93 i.matchesUnit(other) &&
94 i.matchesScope(other)
95 }
96
97 // matchesName returns true if the Name of i is "" or it equals the Name of
98 // other, otherwise false.
99 func (i Instrument) matchesName(other Instrument) bool {
100 return i.Name == "" || i.Name == other.Name
101 }
102
103 // matchesDescription returns true if the Description of i is "" or it equals
104 // the Description of other, otherwise false.
105 func (i Instrument) matchesDescription(other Instrument) bool {
106 return i.Description == "" || i.Description == other.Description
107 }
108
109 // matchesKind returns true if the Kind of i is its zero-value or it equals the
110 // Kind of other, otherwise false.
111 func (i Instrument) matchesKind(other Instrument) bool {
112 return i.Kind == instrumentKindUndefined || i.Kind == other.Kind
113 }
114
115 // matchesUnit returns true if the Unit of i is its zero-value or it equals the
116 // Unit of other, otherwise false.
117 func (i Instrument) matchesUnit(other Instrument) bool {
118 return i.Unit == "" || i.Unit == other.Unit
119 }
120
121 // matchesScope returns true if the Scope of i is its zero-value or it equals
122 // the Scope of other, otherwise false.
123 func (i Instrument) matchesScope(other Instrument) bool {
124 return (i.Scope.Name == "" || i.Scope.Name == other.Scope.Name) &&
125 (i.Scope.Version == "" || i.Scope.Version == other.Scope.Version) &&
126 (i.Scope.SchemaURL == "" || i.Scope.SchemaURL == other.Scope.SchemaURL)
127 }
128
129 // Stream describes the stream of data an instrument produces.
130 type Stream struct {
131 // Name is the human-readable identifier of the stream.
132 Name string
133 // Description describes the purpose of the data.
134 Description string
135 // Unit is the unit of measurement recorded.
136 Unit string
137 // Aggregation the stream uses for an instrument.
138 Aggregation Aggregation
139 // AttributeFilter is an attribute Filter applied to the attributes
140 // recorded for an instrument's measurement. If the filter returns false
141 // the attribute will not be recorded, otherwise, if it returns true, it
142 // will record the attribute.
143 //
144 // Use NewAllowKeysFilter from "go.opentelemetry.io/otel/attribute" to
145 // provide an allow-list of attribute keys here.
146 AttributeFilter attribute.Filter
147 // ExemplarReservoirProvider selects the
148 // [go.opentelemetry.io/otel/sdk/metric/exemplar.ReservoirProvider] based
149 // on the [Aggregation].
150 //
151 // If unspecified, [DefaultExemplarReservoirProviderSelector] is used.
152 ExemplarReservoirProviderSelector ExemplarReservoirProviderSelector
153 }
154
155 // instID are the identifying properties of a instrument.
156 type instID struct {
157 // Name is the name of the stream.
158 Name string
159 // Description is the description of the stream.
160 Description string
161 // Kind defines the functional group of the instrument.
162 Kind InstrumentKind
163 // Unit is the unit of the stream.
164 Unit string
165 // Number is the number type of the stream.
166 Number string
167 }
168
169 // Returns a normalized copy of the instID i.
170 //
171 // Instrument names are considered case-insensitive. Standardize the instrument
172 // name to always be lowercase for the returned instID so it can be compared
173 // without the name casing affecting the comparison.
174 func (i instID) normalize() instID {
175 i.Name = strings.ToLower(i.Name)
176 return i
177 }
178
179 type int64Inst struct {
180 measures []aggregate.Measure[int64]
181
182 embedded.Int64Counter
183 embedded.Int64UpDownCounter
184 embedded.Int64Histogram
185 embedded.Int64Gauge
186 }
187
188 var (
189 _ metric.Int64Counter = (*int64Inst)(nil)
190 _ metric.Int64UpDownCounter = (*int64Inst)(nil)
191 _ metric.Int64Histogram = (*int64Inst)(nil)
192 _ metric.Int64Gauge = (*int64Inst)(nil)
193 )
194
195 func (i *int64Inst) Add(ctx context.Context, val int64, opts ...metric.AddOption) {
196 c := metric.NewAddConfig(opts)
197 i.aggregate(ctx, val, c.Attributes())
198 }
199
200 func (i *int64Inst) Record(ctx context.Context, val int64, opts ...metric.RecordOption) {
201 c := metric.NewRecordConfig(opts)
202 i.aggregate(ctx, val, c.Attributes())
203 }
204
205 func (i *int64Inst) Enabled(context.Context) bool {
206 return len(i.measures) != 0
207 }
208
209 func (i *int64Inst) aggregate(
210 ctx context.Context,
211 val int64,
212 s attribute.Set,
213 ) { // nolint:revive // okay to shadow pkg with method.
214 for _, in := range i.measures {
215 in(ctx, val, s)
216 }
217 }
218
219 type float64Inst struct {
220 measures []aggregate.Measure[float64]
221
222 embedded.Float64Counter
223 embedded.Float64UpDownCounter
224 embedded.Float64Histogram
225 embedded.Float64Gauge
226 }
227
228 var (
229 _ metric.Float64Counter = (*float64Inst)(nil)
230 _ metric.Float64UpDownCounter = (*float64Inst)(nil)
231 _ metric.Float64Histogram = (*float64Inst)(nil)
232 _ metric.Float64Gauge = (*float64Inst)(nil)
233 )
234
235 func (i *float64Inst) Add(ctx context.Context, val float64, opts ...metric.AddOption) {
236 c := metric.NewAddConfig(opts)
237 i.aggregate(ctx, val, c.Attributes())
238 }
239
240 func (i *float64Inst) Record(ctx context.Context, val float64, opts ...metric.RecordOption) {
241 c := metric.NewRecordConfig(opts)
242 i.aggregate(ctx, val, c.Attributes())
243 }
244
245 func (i *float64Inst) Enabled(context.Context) bool {
246 return len(i.measures) != 0
247 }
248
249 func (i *float64Inst) aggregate(ctx context.Context, val float64, s attribute.Set) {
250 for _, in := range i.measures {
251 in(ctx, val, s)
252 }
253 }
254
255 // observableID is a comparable unique identifier of an observable.
256 type observableID[N int64 | float64] struct {
257 name string
258 description string
259 kind InstrumentKind
260 unit string
261 scope instrumentation.Scope
262 }
263
264 type float64Observable struct {
265 metric.Float64Observable
266 *observable[float64]
267
268 embedded.Float64ObservableCounter
269 embedded.Float64ObservableUpDownCounter
270 embedded.Float64ObservableGauge
271 }
272
273 var (
274 _ metric.Float64ObservableCounter = float64Observable{}
275 _ metric.Float64ObservableUpDownCounter = float64Observable{}
276 _ metric.Float64ObservableGauge = float64Observable{}
277 )
278
279 func newFloat64Observable(m *meter, kind InstrumentKind, name, desc, u string) float64Observable {
280 return float64Observable{
281 observable: newObservable[float64](m, kind, name, desc, u),
282 }
283 }
284
285 type int64Observable struct {
286 metric.Int64Observable
287 *observable[int64]
288
289 embedded.Int64ObservableCounter
290 embedded.Int64ObservableUpDownCounter
291 embedded.Int64ObservableGauge
292 }
293
294 var (
295 _ metric.Int64ObservableCounter = int64Observable{}
296 _ metric.Int64ObservableUpDownCounter = int64Observable{}
297 _ metric.Int64ObservableGauge = int64Observable{}
298 )
299
300 func newInt64Observable(m *meter, kind InstrumentKind, name, desc, u string) int64Observable {
301 return int64Observable{
302 observable: newObservable[int64](m, kind, name, desc, u),
303 }
304 }
305
306 type observable[N int64 | float64] struct {
307 metric.Observable
308 observableID[N]
309
310 meter *meter
311 measures measures[N]
312 dropAggregation bool
313 }
314
315 func newObservable[N int64 | float64](m *meter, kind InstrumentKind, name, desc, u string) *observable[N] {
316 return &observable[N]{
317 observableID: observableID[N]{
318 name: name,
319 description: desc,
320 kind: kind,
321 unit: u,
322 scope: m.scope,
323 },
324 meter: m,
325 }
326 }
327
328 // observe records the val for the set of attrs.
329 func (o *observable[N]) observe(val N, s attribute.Set) {
330 o.measures.observe(val, s)
331 }
332
333 func (o *observable[N]) appendMeasures(meas []aggregate.Measure[N]) {
334 o.measures = append(o.measures, meas...)
335 }
336
337 type measures[N int64 | float64] []aggregate.Measure[N]
338
339 // observe records the val for the set of attrs.
340 func (m measures[N]) observe(val N, s attribute.Set) {
341 for _, in := range m {
342 in(context.Background(), val, s)
343 }
344 }
345
346 var errEmptyAgg = errors.New("no aggregators for observable instrument")
347
348 // registerable returns an error if the observable o should not be registered,
349 // and nil if it should. An errEmptyAgg error is returned if o is effectively a
350 // no-op because it does not have any aggregators. Also, an error is returned
351 // if scope defines a Meter other than the one o was created by.
352 func (o *observable[N]) registerable(m *meter) error {
353 if len(o.measures) == 0 {
354 return errEmptyAgg
355 }
356 if m != o.meter {
357 return fmt.Errorf(
358 "invalid registration: observable %q from Meter %q, registered with Meter %q",
359 o.name,
360 o.scope.Name,
361 m.scope.Name,
362 )
363 }
364 return nil
365 }