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 Meter(name string, opts ...MeterOption) Meter
34 }
35 36 // Meter provides access to instrument instances for recording metrics.
37 //
38 // Warning: Methods may be added to this interface in minor releases. See
39 // package documentation on API implementation for information on how to set
40 // default behavior for unimplemented methods.
41 type Meter interface {
42 // Users of the interface can ignore this. This embedded type is only used
43 // by implementations of this interface. See the "API Implementations"
44 // section of the package documentation for more information.
45 embedded.Meter
46 47 // Int64Counter returns a new Int64Counter instrument identified by name
48 // and configured with options. The instrument is used to synchronously
49 // record increasing int64 measurements during a computational operation.
50 //
51 // The name needs to conform to the OpenTelemetry instrument name syntax.
52 // See the Instrument Name section of the package documentation for more
53 // information.
54 Int64Counter(name string, options ...Int64CounterOption) (Int64Counter, error)
55 56 // Int64UpDownCounter returns a new Int64UpDownCounter instrument
57 // identified by name and configured with options. The instrument is used
58 // to synchronously record int64 measurements during a computational
59 // operation.
60 //
61 // The name needs to conform to the OpenTelemetry instrument name syntax.
62 // See the Instrument Name section of the package documentation for more
63 // information.
64 Int64UpDownCounter(name string, options ...Int64UpDownCounterOption) (Int64UpDownCounter, error)
65 66 // Int64Histogram returns a new Int64Histogram instrument identified by
67 // name and configured with options. The instrument is used to
68 // synchronously record the distribution of int64 measurements during a
69 // computational operation.
70 //
71 // The name needs to conform to the OpenTelemetry instrument name syntax.
72 // See the Instrument Name section of the package documentation for more
73 // information.
74 Int64Histogram(name string, options ...Int64HistogramOption) (Int64Histogram, error)
75 76 // Int64Gauge returns a new Int64Gauge instrument identified by name and
77 // configured with options. The instrument is used to synchronously record
78 // instantaneous int64 measurements during a 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 Int64Gauge(name string, options ...Int64GaugeOption) (Int64Gauge, error)
84 85 // Int64ObservableCounter returns a new Int64ObservableCounter identified
86 // by name and configured with options. The instrument is used to
87 // asynchronously record increasing int64 measurements once per a
88 // measurement collection cycle.
89 //
90 // Measurements for the returned instrument are made via a callback. Use
91 // the WithInt64Callback option to register the callback here, or use the
92 // RegisterCallback method of this Meter to register one later. See the
93 // Measurements section of the package documentation for more information.
94 //
95 // The name needs to conform to the OpenTelemetry instrument name syntax.
96 // See the Instrument Name section of the package documentation for more
97 // information.
98 Int64ObservableCounter(name string, options ...Int64ObservableCounterOption) (Int64ObservableCounter, error)
99 100 // Int64ObservableUpDownCounter returns a new Int64ObservableUpDownCounter
101 // instrument identified by name and configured with options. The
102 // instrument is used to asynchronously record int64 measurements once per
103 // a 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 Int64ObservableUpDownCounter(
114 name string,
115 options ...Int64ObservableUpDownCounterOption,
116 ) (Int64ObservableUpDownCounter, error)
117 118 // Int64ObservableGauge returns a new Int64ObservableGauge instrument
119 // identified by name and configured with options. The instrument is used
120 // to asynchronously record instantaneous int64 measurements once per a
121 // 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 Int64ObservableGauge(name string, options ...Int64ObservableGaugeOption) (Int64ObservableGauge, error)
132 133 // Float64Counter returns a new Float64Counter instrument identified by
134 // name and configured with options. The instrument is used to
135 // synchronously record increasing float64 measurements during a
136 // computational operation.
137 //
138 // The name needs to conform to the OpenTelemetry instrument name syntax.
139 // See the Instrument Name section of the package documentation for more
140 // information.
141 Float64Counter(name string, options ...Float64CounterOption) (Float64Counter, error)
142 143 // Float64UpDownCounter returns a new Float64UpDownCounter instrument
144 // identified by name and configured with options. The instrument is used
145 // to synchronously record float64 measurements during a computational
146 // operation.
147 //
148 // The name needs to conform to the OpenTelemetry instrument name syntax.
149 // See the Instrument Name section of the package documentation for more
150 // information.
151 Float64UpDownCounter(name string, options ...Float64UpDownCounterOption) (Float64UpDownCounter, error)
152 153 // Float64Histogram returns a new Float64Histogram instrument identified by
154 // name and configured with options. The instrument is used to
155 // synchronously record the distribution of float64 measurements during a
156 // computational operation.
157 //
158 // The name needs to conform to the OpenTelemetry instrument name syntax.
159 // See the Instrument Name section of the package documentation for more
160 // information.
161 Float64Histogram(name string, options ...Float64HistogramOption) (Float64Histogram, error)
162 163 // Float64Gauge returns a new Float64Gauge instrument identified by name and
164 // configured with options. The instrument is used to synchronously record
165 // instantaneous float64 measurements during a computational operation.
166 //
167 // The name needs to conform to the OpenTelemetry instrument name syntax.
168 // See the Instrument Name section of the package documentation for more
169 // information.
170 Float64Gauge(name string, options ...Float64GaugeOption) (Float64Gauge, error)
171 172 // Float64ObservableCounter returns a new Float64ObservableCounter
173 // instrument identified by name and configured with options. The
174 // instrument is used to asynchronously record increasing float64
175 // measurements once per a measurement collection cycle.
176 //
177 // Measurements for the returned instrument are made via a callback. Use
178 // the WithFloat64Callback option to register the callback here, or use the
179 // RegisterCallback method of this Meter to register one later. See the
180 // Measurements section of the package documentation for more information.
181 //
182 // The name needs to conform to the OpenTelemetry instrument name syntax.
183 // See the Instrument Name section of the package documentation for more
184 // information.
185 Float64ObservableCounter(name string, options ...Float64ObservableCounterOption) (Float64ObservableCounter, error)
186 187 // Float64ObservableUpDownCounter returns a new
188 // Float64ObservableUpDownCounter instrument identified by name and
189 // configured with options. The instrument is used to asynchronously record
190 // float64 measurements once per a measurement collection cycle.
191 //
192 // Measurements for the returned instrument are made via a callback. Use
193 // the WithFloat64Callback option to register the callback here, or use the
194 // RegisterCallback method of this Meter to register one later. See the
195 // Measurements section of the package documentation for more information.
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 Float64ObservableUpDownCounter(
201 name string,
202 options ...Float64ObservableUpDownCounterOption,
203 ) (Float64ObservableUpDownCounter, error)
204 205 // Float64ObservableGauge returns a new Float64ObservableGauge instrument
206 // identified by name and configured with options. The instrument is used
207 // to asynchronously record instantaneous float64 measurements once per a
208 // 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 Float64ObservableGauge(name string, options ...Float64ObservableGaugeOption) (Float64ObservableGauge, error)
219 220 // RegisterCallback registers f to be called during the collection of a
221 // measurement cycle.
222 //
223 // If Unregister of the returned Registration is called, f needs to be
224 // unregistered and not called during collection.
225 //
226 // The instruments f is registered with are the only instruments that f may
227 // observe values for.
228 //
229 // If no instruments are passed, f should not be registered nor called
230 // during collection.
231 //
232 // The function f needs to be concurrent safe.
233 RegisterCallback(f Callback, instruments ...Observable) (Registration, error)
234 }
235 236 // Callback is a function registered with a Meter that makes observations for
237 // the set of instruments it is registered with. The Observer parameter is used
238 // to record measurement observations for these instruments.
239 //
240 // The function needs to complete in a finite amount of time and the deadline
241 // of the passed context is expected to be honored.
242 //
243 // The function needs to make unique observations across all registered
244 // Callbacks. Meaning, it should not report measurements for an instrument with
245 // the same attributes as another Callback will report.
246 //
247 // The function needs to be concurrent safe.
248 type Callback func(context.Context, Observer) error
249 250 // Observer records measurements for multiple instruments in a Callback.
251 //
252 // Warning: Methods may be added to this interface in minor releases. See
253 // package documentation on API implementation for information on how to set
254 // default behavior for unimplemented methods.
255 type Observer interface {
256 // Users of the interface can ignore this. This embedded type is only used
257 // by implementations of this interface. See the "API Implementations"
258 // section of the package documentation for more information.
259 embedded.Observer
260 261 // ObserveFloat64 records the float64 value for obsrv.
262 ObserveFloat64(obsrv Float64Observable, value float64, opts ...ObserveOption)
263 264 // ObserveInt64 records the int64 value for obsrv.
265 ObserveInt64(obsrv Int64Observable, value int64, opts ...ObserveOption)
266 }
267 268 // Registration is an token representing the unique registration of a callback
269 // for a set of instruments with a Meter.
270 //
271 // Warning: Methods may be added to this interface in minor releases. See
272 // package documentation on API implementation for information on how to set
273 // default behavior for unimplemented methods.
274 type Registration interface {
275 // Users of the interface can ignore this. This embedded type is only used
276 // by implementations of this interface. See the "API Implementations"
277 // section of the package documentation for more information.
278 embedded.Registration
279 280 // Unregister removes the callback registration from a Meter.
281 //
282 // This method needs to be idempotent and concurrent safe.
283 Unregister() error
284 }
285