blob: d1749136f0816c534bf99a2cd5ce59e6403bca89 [file] [log] [blame]
Joey Armstronga6af1522023-01-17 16:06:16 -05001// Copyright The OpenTelemetry Authors
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7// http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15package metric
16
17import (
18 "context"
19
20 "go.opentelemetry.io/otel/label"
21)
22
23// The file is organized as follows:
24//
25// - MeterProvider interface
26// - Meter struct
27// - RecordBatch
28// - BatchObserver
29// - Synchronous instrument constructors (2 x int64,float64)
30// - Asynchronous instrument constructors (1 x int64,float64)
31// - Batch asynchronous constructors (1 x int64,float64)
32// - Internals
33
34// MeterProvider supports named Meter instances.
35type MeterProvider interface {
36 // Meter creates an implementation of the Meter interface.
37 // The instrumentationName must be the name of the library providing
38 // instrumentation. This name may be the same as the instrumented code
39 // only if that code provides built-in instrumentation. If the
40 // instrumentationName is empty, then a implementation defined default
41 // name will be used instead.
42 Meter(instrumentationName string, opts ...MeterOption) Meter
43}
44
45// Meter is the OpenTelemetry metric API, based on a `MeterImpl`
46// implementation and the `Meter` library name.
47//
48// An uninitialized Meter is a no-op implementation.
49type Meter struct {
50 impl MeterImpl
51 name, version string
52}
53
54// RecordBatch atomically records a batch of measurements.
55func (m Meter) RecordBatch(ctx context.Context, ls []label.KeyValue, ms ...Measurement) {
56 if m.impl == nil {
57 return
58 }
59 m.impl.RecordBatch(ctx, ls, ms...)
60}
61
62// NewBatchObserver creates a new BatchObserver that supports
63// making batches of observations for multiple instruments.
64func (m Meter) NewBatchObserver(callback BatchObserverFunc) BatchObserver {
65 return BatchObserver{
66 meter: m,
67 runner: newBatchAsyncRunner(callback),
68 }
69}
70
71// NewInt64Counter creates a new integer Counter instrument with the
72// given name, customized with options. May return an error if the
73// name is invalid (e.g., empty) or improperly registered (e.g.,
74// duplicate registration).
75func (m Meter) NewInt64Counter(name string, options ...InstrumentOption) (Int64Counter, error) {
76 return wrapInt64CounterInstrument(
77 m.newSync(name, CounterKind, Int64NumberKind, options))
78}
79
80// NewFloat64Counter creates a new floating point Counter with the
81// given name, customized with options. May return an error if the
82// name is invalid (e.g., empty) or improperly registered (e.g.,
83// duplicate registration).
84func (m Meter) NewFloat64Counter(name string, options ...InstrumentOption) (Float64Counter, error) {
85 return wrapFloat64CounterInstrument(
86 m.newSync(name, CounterKind, Float64NumberKind, options))
87}
88
89// NewInt64UpDownCounter creates a new integer UpDownCounter instrument with the
90// given name, customized with options. May return an error if the
91// name is invalid (e.g., empty) or improperly registered (e.g.,
92// duplicate registration).
93func (m Meter) NewInt64UpDownCounter(name string, options ...InstrumentOption) (Int64UpDownCounter, error) {
94 return wrapInt64UpDownCounterInstrument(
95 m.newSync(name, UpDownCounterKind, Int64NumberKind, options))
96}
97
98// NewFloat64UpDownCounter creates a new floating point UpDownCounter with the
99// given name, customized with options. May return an error if the
100// name is invalid (e.g., empty) or improperly registered (e.g.,
101// duplicate registration).
102func (m Meter) NewFloat64UpDownCounter(name string, options ...InstrumentOption) (Float64UpDownCounter, error) {
103 return wrapFloat64UpDownCounterInstrument(
104 m.newSync(name, UpDownCounterKind, Float64NumberKind, options))
105}
106
107// NewInt64ValueRecorder creates a new integer ValueRecorder instrument with the
108// given name, customized with options. May return an error if the
109// name is invalid (e.g., empty) or improperly registered (e.g.,
110// duplicate registration).
111func (m Meter) NewInt64ValueRecorder(name string, opts ...InstrumentOption) (Int64ValueRecorder, error) {
112 return wrapInt64ValueRecorderInstrument(
113 m.newSync(name, ValueRecorderKind, Int64NumberKind, opts))
114}
115
116// NewFloat64ValueRecorder creates a new floating point ValueRecorder with the
117// given name, customized with options. May return an error if the
118// name is invalid (e.g., empty) or improperly registered (e.g.,
119// duplicate registration).
120func (m Meter) NewFloat64ValueRecorder(name string, opts ...InstrumentOption) (Float64ValueRecorder, error) {
121 return wrapFloat64ValueRecorderInstrument(
122 m.newSync(name, ValueRecorderKind, Float64NumberKind, opts))
123}
124
125// NewInt64ValueObserver creates a new integer ValueObserver instrument
126// with the given name, running a given callback, and customized with
127// options. May return an error if the name is invalid (e.g., empty)
128// or improperly registered (e.g., duplicate registration).
129func (m Meter) NewInt64ValueObserver(name string, callback Int64ObserverFunc, opts ...InstrumentOption) (Int64ValueObserver, error) {
130 if callback == nil {
131 return wrapInt64ValueObserverInstrument(NoopAsync{}, nil)
132 }
133 return wrapInt64ValueObserverInstrument(
134 m.newAsync(name, ValueObserverKind, Int64NumberKind, opts,
135 newInt64AsyncRunner(callback)))
136}
137
138// NewFloat64ValueObserver creates a new floating point ValueObserver with
139// the given name, running a given callback, and customized with
140// options. May return an error if the name is invalid (e.g., empty)
141// or improperly registered (e.g., duplicate registration).
142func (m Meter) NewFloat64ValueObserver(name string, callback Float64ObserverFunc, opts ...InstrumentOption) (Float64ValueObserver, error) {
143 if callback == nil {
144 return wrapFloat64ValueObserverInstrument(NoopAsync{}, nil)
145 }
146 return wrapFloat64ValueObserverInstrument(
147 m.newAsync(name, ValueObserverKind, Float64NumberKind, opts,
148 newFloat64AsyncRunner(callback)))
149}
150
151// NewInt64SumObserver creates a new integer SumObserver instrument
152// with the given name, running a given callback, and customized with
153// options. May return an error if the name is invalid (e.g., empty)
154// or improperly registered (e.g., duplicate registration).
155func (m Meter) NewInt64SumObserver(name string, callback Int64ObserverFunc, opts ...InstrumentOption) (Int64SumObserver, error) {
156 if callback == nil {
157 return wrapInt64SumObserverInstrument(NoopAsync{}, nil)
158 }
159 return wrapInt64SumObserverInstrument(
160 m.newAsync(name, SumObserverKind, Int64NumberKind, opts,
161 newInt64AsyncRunner(callback)))
162}
163
164// NewFloat64SumObserver creates a new floating point SumObserver with
165// the given name, running a given callback, and customized with
166// options. May return an error if the name is invalid (e.g., empty)
167// or improperly registered (e.g., duplicate registration).
168func (m Meter) NewFloat64SumObserver(name string, callback Float64ObserverFunc, opts ...InstrumentOption) (Float64SumObserver, error) {
169 if callback == nil {
170 return wrapFloat64SumObserverInstrument(NoopAsync{}, nil)
171 }
172 return wrapFloat64SumObserverInstrument(
173 m.newAsync(name, SumObserverKind, Float64NumberKind, opts,
174 newFloat64AsyncRunner(callback)))
175}
176
177// NewInt64UpDownSumObserver creates a new integer UpDownSumObserver instrument
178// with the given name, running a given callback, and customized with
179// options. May return an error if the name is invalid (e.g., empty)
180// or improperly registered (e.g., duplicate registration).
181func (m Meter) NewInt64UpDownSumObserver(name string, callback Int64ObserverFunc, opts ...InstrumentOption) (Int64UpDownSumObserver, error) {
182 if callback == nil {
183 return wrapInt64UpDownSumObserverInstrument(NoopAsync{}, nil)
184 }
185 return wrapInt64UpDownSumObserverInstrument(
186 m.newAsync(name, UpDownSumObserverKind, Int64NumberKind, opts,
187 newInt64AsyncRunner(callback)))
188}
189
190// NewFloat64UpDownSumObserver creates a new floating point UpDownSumObserver with
191// the given name, running a given callback, and customized with
192// options. May return an error if the name is invalid (e.g., empty)
193// or improperly registered (e.g., duplicate registration).
194func (m Meter) NewFloat64UpDownSumObserver(name string, callback Float64ObserverFunc, opts ...InstrumentOption) (Float64UpDownSumObserver, error) {
195 if callback == nil {
196 return wrapFloat64UpDownSumObserverInstrument(NoopAsync{}, nil)
197 }
198 return wrapFloat64UpDownSumObserverInstrument(
199 m.newAsync(name, UpDownSumObserverKind, Float64NumberKind, opts,
200 newFloat64AsyncRunner(callback)))
201}
202
203// NewInt64ValueObserver creates a new integer ValueObserver instrument
204// with the given name, running in a batch callback, and customized with
205// options. May return an error if the name is invalid (e.g., empty)
206// or improperly registered (e.g., duplicate registration).
207func (b BatchObserver) NewInt64ValueObserver(name string, opts ...InstrumentOption) (Int64ValueObserver, error) {
208 if b.runner == nil {
209 return wrapInt64ValueObserverInstrument(NoopAsync{}, nil)
210 }
211 return wrapInt64ValueObserverInstrument(
212 b.meter.newAsync(name, ValueObserverKind, Int64NumberKind, opts, b.runner))
213}
214
215// NewFloat64ValueObserver creates a new floating point ValueObserver with
216// the given name, running in a batch callback, and customized with
217// options. May return an error if the name is invalid (e.g., empty)
218// or improperly registered (e.g., duplicate registration).
219func (b BatchObserver) NewFloat64ValueObserver(name string, opts ...InstrumentOption) (Float64ValueObserver, error) {
220 if b.runner == nil {
221 return wrapFloat64ValueObserverInstrument(NoopAsync{}, nil)
222 }
223 return wrapFloat64ValueObserverInstrument(
224 b.meter.newAsync(name, ValueObserverKind, Float64NumberKind, opts,
225 b.runner))
226}
227
228// NewInt64SumObserver creates a new integer SumObserver instrument
229// with the given name, running in a batch callback, and customized with
230// options. May return an error if the name is invalid (e.g., empty)
231// or improperly registered (e.g., duplicate registration).
232func (b BatchObserver) NewInt64SumObserver(name string, opts ...InstrumentOption) (Int64SumObserver, error) {
233 if b.runner == nil {
234 return wrapInt64SumObserverInstrument(NoopAsync{}, nil)
235 }
236 return wrapInt64SumObserverInstrument(
237 b.meter.newAsync(name, SumObserverKind, Int64NumberKind, opts, b.runner))
238}
239
240// NewFloat64SumObserver creates a new floating point SumObserver with
241// the given name, running in a batch callback, and customized with
242// options. May return an error if the name is invalid (e.g., empty)
243// or improperly registered (e.g., duplicate registration).
244func (b BatchObserver) NewFloat64SumObserver(name string, opts ...InstrumentOption) (Float64SumObserver, error) {
245 if b.runner == nil {
246 return wrapFloat64SumObserverInstrument(NoopAsync{}, nil)
247 }
248 return wrapFloat64SumObserverInstrument(
249 b.meter.newAsync(name, SumObserverKind, Float64NumberKind, opts,
250 b.runner))
251}
252
253// NewInt64UpDownSumObserver creates a new integer UpDownSumObserver instrument
254// with the given name, running in a batch callback, and customized with
255// options. May return an error if the name is invalid (e.g., empty)
256// or improperly registered (e.g., duplicate registration).
257func (b BatchObserver) NewInt64UpDownSumObserver(name string, opts ...InstrumentOption) (Int64UpDownSumObserver, error) {
258 if b.runner == nil {
259 return wrapInt64UpDownSumObserverInstrument(NoopAsync{}, nil)
260 }
261 return wrapInt64UpDownSumObserverInstrument(
262 b.meter.newAsync(name, UpDownSumObserverKind, Int64NumberKind, opts, b.runner))
263}
264
265// NewFloat64UpDownSumObserver creates a new floating point UpDownSumObserver with
266// the given name, running in a batch callback, and customized with
267// options. May return an error if the name is invalid (e.g., empty)
268// or improperly registered (e.g., duplicate registration).
269func (b BatchObserver) NewFloat64UpDownSumObserver(name string, opts ...InstrumentOption) (Float64UpDownSumObserver, error) {
270 if b.runner == nil {
271 return wrapFloat64UpDownSumObserverInstrument(NoopAsync{}, nil)
272 }
273 return wrapFloat64UpDownSumObserverInstrument(
274 b.meter.newAsync(name, UpDownSumObserverKind, Float64NumberKind, opts,
275 b.runner))
276}
277
278// MeterImpl returns the underlying MeterImpl of this Meter.
279func (m Meter) MeterImpl() MeterImpl {
280 return m.impl
281}
282
283// newAsync constructs one new asynchronous instrument.
284func (m Meter) newAsync(
285 name string,
286 mkind Kind,
287 nkind NumberKind,
288 opts []InstrumentOption,
289 runner AsyncRunner,
290) (
291 AsyncImpl,
292 error,
293) {
294 if m.impl == nil {
295 return NoopAsync{}, nil
296 }
297 desc := NewDescriptor(name, mkind, nkind, opts...)
298 desc.config.InstrumentationName = m.name
299 desc.config.InstrumentationVersion = m.version
300 return m.impl.NewAsyncInstrument(desc, runner)
301}
302
303// newSync constructs one new synchronous instrument.
304func (m Meter) newSync(
305 name string,
306 metricKind Kind,
307 numberKind NumberKind,
308 opts []InstrumentOption,
309) (
310 SyncImpl,
311 error,
312) {
313 if m.impl == nil {
314 return NoopSync{}, nil
315 }
316 desc := NewDescriptor(name, metricKind, numberKind, opts...)
317 desc.config.InstrumentationName = m.name
318 desc.config.InstrumentationVersion = m.version
319 return m.impl.NewSyncInstrument(desc)
320}