Debian Codegraph @

metric/meter.go

raw
1 // Copyright The OpenTelemetry Authors
2 // SPDX-License-Identifier: Apache-2.0
3
4 package metric // import "go.opentelemetry.io/otel/metric"
5
6 import (
7 "context"
8
9 "go.opentelemetry.io/otel/metric/embedded"
10 )
11
12 // MeterProvider provides access to named Meter instances, for instrumenting
13 // an application or package.
14 //
15 // Warning: Methods may be added to this interface in minor releases. See
16 // package documentation on API implementation for information on how to set
17 // default behavior for unimplemented methods.
18 type MeterProvider interface {
19 // Users of the interface can ignore this. This embedded type is only used
20 // by implementations of this interface. See the "API Implementations"
21 // section of the package documentation for more information.
22 embedded.MeterProvider
23
24 // Meter returns a new Meter with the provided name and configuration.
25 //
26 // A Meter should be scoped at most to a single package. The name needs to
27 // be unique so it does not collide with other names used by
28 // an application, nor other applications. To achieve this, the import path
29 // of the instrumentation package is recommended to be used as name.
30 //
31 // If the name is empty, then an implementation defined default name will
32 // be used instead.
33 //
34 // Implementations of this method need to be safe for a user to call
35 // concurrently.
36 Meter(name string, opts ...MeterOption) Meter
37 }
38
39 // Meter provides access to instrument instances for recording metrics.
40 //
41 // Warning: Methods may be added to this interface in minor releases. See
42 // package documentation on API implementation for information on how to set
43 // default behavior for unimplemented methods.
44 type Meter interface {
45 // Users of the interface can ignore this. This embedded type is only used
46 // by implementations of this interface. See the "API Implementations"
47 // section of the package documentation for more information.
48 embedded.Meter
49
50 // Int64Counter returns a new Int64Counter instrument identified by name
51 // and configured with options. The instrument is used to synchronously
52 // record increasing int64 measurements during a computational operation.
53 //
54 // The name needs to conform to the OpenTelemetry instrument name syntax.
55 // See the Instrument Name section of the package documentation for more
56 // information.
57 //
58 // Implementations of this method need to be safe for a user to call
59 // concurrently.
60 Int64Counter(name string, options ...Int64CounterOption) (Int64Counter, error)
61
62 // Int64UpDownCounter returns a new Int64UpDownCounter instrument
63 // identified by name and configured with options. The instrument is used
64 // to synchronously record int64 measurements during a computational
65 // operation.
66 //
67 // The name needs to conform to the OpenTelemetry instrument name syntax.
68 // See the Instrument Name section of the package documentation for more
69 // information.
70 //
71 // Implementations of this method need to be safe for a user to call
72 // concurrently.
73 Int64UpDownCounter(name string, options ...Int64UpDownCounterOption) (Int64UpDownCounter, error)
74
75 // Int64Histogram returns a new Int64Histogram instrument identified by
76 // name and configured with options. The instrument is used to
77 // synchronously record the distribution of int64 measurements during a
78 // computational operation.
79 //
80 // The name needs to conform to the OpenTelemetry instrument name syntax.
81 // See the Instrument Name section of the package documentation for more
82 // information.
83 //
84 // Implementations of this method need to be safe for a user to call
85 // concurrently.
86 Int64Histogram(name string, options ...Int64HistogramOption) (Int64Histogram, error)
87
88 // Int64Gauge returns a new Int64Gauge instrument identified by name and
89 // configured with options. The instrument is used to synchronously record
90 // instantaneous int64 measurements during a computational operation.
91 //
92 // The name needs to conform to the OpenTelemetry instrument name syntax.
93 // See the Instrument Name section of the package documentation for more
94 // information.
95 //
96 // Implementations of this method need to be safe for a user to call
97 // concurrently.
98 Int64Gauge(name string, options ...Int64GaugeOption) (Int64Gauge, error)
99
100 // Int64ObservableCounter returns a new Int64ObservableCounter identified
101 // by name and configured with options. The instrument is used to
102 // asynchronously record increasing int64 measurements once per a
103 // measurement collection cycle.
104 //
105 // Measurements for the returned instrument are made via a callback. Use
106 // the WithInt64Callback option to register the callback here, or use the
107 // RegisterCallback method of this Meter to register one later. See the
108 // Measurements section of the package documentation for more information.
109 //
110 // The name needs to conform to the OpenTelemetry instrument name syntax.
111 // See the Instrument Name section of the package documentation for more
112 // information.
113 //
114 // Implementations of this method need to be safe for a user to call
115 // concurrently.
116 Int64ObservableCounter(name string, options ...Int64ObservableCounterOption) (Int64ObservableCounter, error)
117
118 // Int64ObservableUpDownCounter returns a new Int64ObservableUpDownCounter
119 // instrument identified by name and configured with options. The
120 // instrument is used to asynchronously record int64 measurements once per
121 // a measurement collection cycle.
122 //
123 // Measurements for the returned instrument are made via a callback. Use
124 // the WithInt64Callback option to register the callback here, or use the
125 // RegisterCallback method of this Meter to register one later. See the
126 // Measurements section of the package documentation for more information.
127 //
128 // The name needs to conform to the OpenTelemetry instrument name syntax.
129 // See the Instrument Name section of the package documentation for more
130 // information.
131 //
132 // Implementations of this method need to be safe for a user to call
133 // concurrently.
134 Int64ObservableUpDownCounter(
135 name string,
136 options ...Int64ObservableUpDownCounterOption,
137 ) (Int64ObservableUpDownCounter, error)
138
139 // Int64ObservableGauge returns a new Int64ObservableGauge instrument
140 // identified by name and configured with options. The instrument is used
141 // to asynchronously record instantaneous int64 measurements once per a
142 // measurement collection cycle.
143 //
144 // Measurements for the returned instrument are made via a callback. Use
145 // the WithInt64Callback option to register the callback here, or use the
146 // RegisterCallback method of this Meter to register one later. See the
147 // Measurements section of the package documentation for more information.
148 //
149 // The name needs to conform to the OpenTelemetry instrument name syntax.
150 // See the Instrument Name section of the package documentation for more
151 // information.
152 //
153 // Implementations of this method need to be safe for a user to call
154 // concurrently.
155 Int64ObservableGauge(name string, options ...Int64ObservableGaugeOption) (Int64ObservableGauge, error)
156
157 // Float64Counter returns a new Float64Counter instrument identified by
158 // name and configured with options. The instrument is used to
159 // synchronously record increasing float64 measurements during a
160 // computational operation.
161 //
162 // The name needs to conform to the OpenTelemetry instrument name syntax.
163 // See the Instrument Name section of the package documentation for more
164 // information.
165 Float64Counter(name string, options ...Float64CounterOption) (Float64Counter, error)
166
167 // Float64UpDownCounter returns a new Float64UpDownCounter instrument
168 // identified by name and configured with options. The instrument is used
169 // to synchronously record float64 measurements during a computational
170 // operation.
171 //
172 // The name needs to conform to the OpenTelemetry instrument name syntax.
173 // See the Instrument Name section of the package documentation for more
174 // information.
175 //
176 // Implementations of this method need to be safe for a user to call
177 // concurrently.
178 Float64UpDownCounter(name string, options ...Float64UpDownCounterOption) (Float64UpDownCounter, error)
179
180 // Float64Histogram returns a new Float64Histogram instrument identified by
181 // name and configured with options. The instrument is used to
182 // synchronously record the distribution of float64 measurements during a
183 // computational operation.
184 //
185 // The name needs to conform to the OpenTelemetry instrument name syntax.
186 // See the Instrument Name section of the package documentation for more
187 // information.
188 //
189 // Implementations of this method need to be safe for a user to call
190 // concurrently.
191 Float64Histogram(name string, options ...Float64HistogramOption) (Float64Histogram, error)
192
193 // Float64Gauge returns a new Float64Gauge instrument identified by name and
194 // configured with options. The instrument is used to synchronously record
195 // instantaneous float64 measurements during a computational operation.
196 //
197 // The name needs to conform to the OpenTelemetry instrument name syntax.
198 // See the Instrument Name section of the package documentation for more
199 // information.
200 //
201 // Implementations of this method need to be safe for a user to call
202 // concurrently.
203 Float64Gauge(name string, options ...Float64GaugeOption) (Float64Gauge, error)
204
205 // Float64ObservableCounter returns a new Float64ObservableCounter
206 // instrument identified by name and configured with options. The
207 // instrument is used to asynchronously record increasing float64
208 // measurements once per a measurement collection cycle.
209 //
210 // Measurements for the returned instrument are made via a callback. Use
211 // the WithFloat64Callback option to register the callback here, or use the
212 // RegisterCallback method of this Meter to register one later. See the
213 // Measurements section of the package documentation for more information.
214 //
215 // The name needs to conform to the OpenTelemetry instrument name syntax.
216 // See the Instrument Name section of the package documentation for more
217 // information.
218 //
219 // Implementations of this method need to be safe for a user to call
220 // concurrently.
221 Float64ObservableCounter(name string, options ...Float64ObservableCounterOption) (Float64ObservableCounter, error)
222
223 // Float64ObservableUpDownCounter returns a new
224 // Float64ObservableUpDownCounter instrument identified by name and
225 // configured with options. The instrument is used to asynchronously record
226 // float64 measurements once per a measurement collection cycle.
227 //
228 // Measurements for the returned instrument are made via a callback. Use
229 // the WithFloat64Callback option to register the callback here, or use the
230 // RegisterCallback method of this Meter to register one later. See the
231 // Measurements section of the package documentation for more information.
232 //
233 // The name needs to conform to the OpenTelemetry instrument name syntax.
234 // See the Instrument Name section of the package documentation for more
235 // information.
236 //
237 // Implementations of this method need to be safe for a user to call
238 // concurrently.
239 Float64ObservableUpDownCounter(
240 name string,
241 options ...Float64ObservableUpDownCounterOption,
242 ) (Float64ObservableUpDownCounter, error)
243
244 // Float64ObservableGauge returns a new Float64ObservableGauge instrument
245 // identified by name and configured with options. The instrument is used
246 // to asynchronously record instantaneous float64 measurements once per a
247 // measurement collection cycle.
248 //
249 // Measurements for the returned instrument are made via a callback. Use
250 // the WithFloat64Callback option to register the callback here, or use the
251 // RegisterCallback method of this Meter to register one later. See the
252 // Measurements section of the package documentation for more information.
253 //
254 // The name needs to conform to the OpenTelemetry instrument name syntax.
255 // See the Instrument Name section of the package documentation for more
256 // information.
257 //
258 // Implementations of this method need to be safe for a user to call
259 // concurrently.
260 Float64ObservableGauge(name string, options ...Float64ObservableGaugeOption) (Float64ObservableGauge, error)
261
262 // RegisterCallback registers f to be called during the collection of a
263 // measurement cycle.
264 //
265 // If Unregister of the returned Registration is called, f needs to be
266 // unregistered and not called during collection.
267 //
268 // The instruments f is registered with are the only instruments that f may
269 // observe values for.
270 //
271 // If no instruments are passed, f should not be registered nor called
272 // during collection.
273 //
274 // Implementations of this method need to be safe for a user to call
275 // concurrently.
276 //
277 // The function f needs to be concurrent safe.
278 RegisterCallback(f Callback, instruments ...Observable) (Registration, error)
279 }
280
281 // Callback is a function registered with a Meter that makes observations for
282 // the set of instruments it is registered with. The Observer parameter is used
283 // to record measurement observations for these instruments.
284 //
285 // The function needs to complete in a finite amount of time and the deadline
286 // of the passed context is expected to be honored.
287 //
288 // The function needs to make unique observations across all registered
289 // Callbacks. Meaning, it should not report measurements for an instrument with
290 // the same attributes as another Callback will report.
291 //
292 // The function needs to be reentrant and concurrent safe.
293 //
294 // Note that Go's mutexes are not reentrant, and locking a mutex takes
295 // an indefinite amount of time. It is therefore advised to avoid
296 // using mutexes inside callbacks.
297 type Callback func(context.Context, Observer) error
298
299 // Observer records measurements for multiple instruments in a Callback.
300 //
301 // Warning: Methods may be added to this interface in minor releases. See
302 // package documentation on API implementation for information on how to set
303 // default behavior for unimplemented methods.
304 type Observer interface {
305 // Users of the interface can ignore this. This embedded type is only used
306 // by implementations of this interface. See the "API Implementations"
307 // section of the package documentation for more information.
308 embedded.Observer
309
310 // ObserveFloat64 records the float64 value for obsrv.
311 //
312 // Implementations of this method need to be safe for a user to call
313 // concurrently.
314 ObserveFloat64(obsrv Float64Observable, value float64, opts ...ObserveOption)
315
316 // ObserveInt64 records the int64 value for obsrv.
317 //
318 // Implementations of this method need to be safe for a user to call
319 // concurrently.
320 ObserveInt64(obsrv Int64Observable, value int64, opts ...ObserveOption)
321 }
322
323 // Registration is an token representing the unique registration of a callback
324 // for a set of instruments with a Meter.
325 //
326 // Warning: Methods may be added to this interface in minor releases. See
327 // package documentation on API implementation for information on how to set
328 // default behavior for unimplemented methods.
329 type Registration interface {
330 // Users of the interface can ignore this. This embedded type is only used
331 // by implementations of this interface. See the "API Implementations"
332 // section of the package documentation for more information.
333 embedded.Registration
334
335 // Unregister removes the callback registration from a Meter.
336 //
337 // Implementations of this method need to be idempotent and safe for a user
338 // to call concurrently.
339 Unregister() error
340 }