1// Copyright The OpenTelemetry Authors
  2// SPDX-License-Identifier: Apache-2.0
  3
  4package metric // import "go.opentelemetry.io/otel/metric"
  5
  6import (
  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.
 18type 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.
 41type 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(name string, options ...Int64ObservableUpDownCounterOption) (Int64ObservableUpDownCounter, error)
114
115	// Int64ObservableGauge returns a new Int64ObservableGauge instrument
116	// identified by name and configured with options. The instrument is used
117	// to asynchronously record instantaneous int64 measurements once per a
118	// measurement collection cycle.
119	//
120	// Measurements for the returned instrument are made via a callback. Use
121	// the WithInt64Callback option to register the callback here, or use the
122	// RegisterCallback method of this Meter to register one later. See the
123	// Measurements section of the package documentation for more information.
124	//
125	// The name needs to conform to the OpenTelemetry instrument name syntax.
126	// See the Instrument Name section of the package documentation for more
127	// information.
128	Int64ObservableGauge(name string, options ...Int64ObservableGaugeOption) (Int64ObservableGauge, error)
129
130	// Float64Counter returns a new Float64Counter instrument identified by
131	// name and configured with options. The instrument is used to
132	// synchronously record increasing float64 measurements during a
133	// computational operation.
134	//
135	// The name needs to conform to the OpenTelemetry instrument name syntax.
136	// See the Instrument Name section of the package documentation for more
137	// information.
138	Float64Counter(name string, options ...Float64CounterOption) (Float64Counter, error)
139
140	// Float64UpDownCounter returns a new Float64UpDownCounter instrument
141	// identified by name and configured with options. The instrument is used
142	// to synchronously record float64 measurements during a computational
143	// operation.
144	//
145	// The name needs to conform to the OpenTelemetry instrument name syntax.
146	// See the Instrument Name section of the package documentation for more
147	// information.
148	Float64UpDownCounter(name string, options ...Float64UpDownCounterOption) (Float64UpDownCounter, error)
149
150	// Float64Histogram returns a new Float64Histogram instrument identified by
151	// name and configured with options. The instrument is used to
152	// synchronously record the distribution of float64 measurements during a
153	// computational operation.
154	//
155	// The name needs to conform to the OpenTelemetry instrument name syntax.
156	// See the Instrument Name section of the package documentation for more
157	// information.
158	Float64Histogram(name string, options ...Float64HistogramOption) (Float64Histogram, error)
159
160	// Float64Gauge returns a new Float64Gauge instrument identified by name and
161	// configured with options. The instrument is used to synchronously record
162	// instantaneous float64 measurements during a computational operation.
163	//
164	// The name needs to conform to the OpenTelemetry instrument name syntax.
165	// See the Instrument Name section of the package documentation for more
166	// information.
167	Float64Gauge(name string, options ...Float64GaugeOption) (Float64Gauge, error)
168
169	// Float64ObservableCounter returns a new Float64ObservableCounter
170	// instrument identified by name and configured with options. The
171	// instrument is used to asynchronously record increasing float64
172	// measurements once per a measurement collection cycle.
173	//
174	// Measurements for the returned instrument are made via a callback. Use
175	// the WithFloat64Callback option to register the callback here, or use the
176	// RegisterCallback method of this Meter to register one later. See the
177	// Measurements section of the package documentation for more information.
178	//
179	// The name needs to conform to the OpenTelemetry instrument name syntax.
180	// See the Instrument Name section of the package documentation for more
181	// information.
182	Float64ObservableCounter(name string, options ...Float64ObservableCounterOption) (Float64ObservableCounter, error)
183
184	// Float64ObservableUpDownCounter returns a new
185	// Float64ObservableUpDownCounter instrument identified by name and
186	// configured with options. The instrument is used to asynchronously record
187	// float64 measurements once per a measurement collection cycle.
188	//
189	// Measurements for the returned instrument are made via a callback. Use
190	// the WithFloat64Callback option to register the callback here, or use the
191	// RegisterCallback method of this Meter to register one later. See the
192	// Measurements section of the package documentation for more information.
193	//
194	// The name needs to conform to the OpenTelemetry instrument name syntax.
195	// See the Instrument Name section of the package documentation for more
196	// information.
197	Float64ObservableUpDownCounter(name string, options ...Float64ObservableUpDownCounterOption) (Float64ObservableUpDownCounter, error)
198
199	// Float64ObservableGauge returns a new Float64ObservableGauge instrument
200	// identified by name and configured with options. The instrument is used
201	// to asynchronously record instantaneous float64 measurements once per a
202	// measurement collection cycle.
203	//
204	// Measurements for the returned instrument are made via a callback. Use
205	// the WithFloat64Callback option to register the callback here, or use the
206	// RegisterCallback method of this Meter to register one later. See the
207	// Measurements section of the package documentation for more information.
208	//
209	// The name needs to conform to the OpenTelemetry instrument name syntax.
210	// See the Instrument Name section of the package documentation for more
211	// information.
212	Float64ObservableGauge(name string, options ...Float64ObservableGaugeOption) (Float64ObservableGauge, error)
213
214	// RegisterCallback registers f to be called during the collection of a
215	// measurement cycle.
216	//
217	// If Unregister of the returned Registration is called, f needs to be
218	// unregistered and not called during collection.
219	//
220	// The instruments f is registered with are the only instruments that f may
221	// observe values for.
222	//
223	// If no instruments are passed, f should not be registered nor called
224	// during collection.
225	//
226	// The function f needs to be concurrent safe.
227	RegisterCallback(f Callback, instruments ...Observable) (Registration, error)
228}
229
230// Callback is a function registered with a Meter that makes observations for
231// the set of instruments it is registered with. The Observer parameter is used
232// to record measurement observations for these instruments.
233//
234// The function needs to complete in a finite amount of time and the deadline
235// of the passed context is expected to be honored.
236//
237// The function needs to make unique observations across all registered
238// Callbacks. Meaning, it should not report measurements for an instrument with
239// the same attributes as another Callback will report.
240//
241// The function needs to be concurrent safe.
242type Callback func(context.Context, Observer) error
243
244// Observer records measurements for multiple instruments in a Callback.
245//
246// Warning: Methods may be added to this interface in minor releases. See
247// package documentation on API implementation for information on how to set
248// default behavior for unimplemented methods.
249type Observer interface {
250	// Users of the interface can ignore this. This embedded type is only used
251	// by implementations of this interface. See the "API Implementations"
252	// section of the package documentation for more information.
253	embedded.Observer
254
255	// ObserveFloat64 records the float64 value for obsrv.
256	ObserveFloat64(obsrv Float64Observable, value float64, opts ...ObserveOption)
257
258	// ObserveInt64 records the int64 value for obsrv.
259	ObserveInt64(obsrv Int64Observable, value int64, opts ...ObserveOption)
260}
261
262// Registration is an token representing the unique registration of a callback
263// for a set of instruments with a Meter.
264//
265// Warning: Methods may be added to this interface in minor releases. See
266// package documentation on API implementation for information on how to set
267// default behavior for unimplemented methods.
268type Registration interface {
269	// Users of the interface can ignore this. This embedded type is only used
270	// by implementations of this interface. See the "API Implementations"
271	// section of the package documentation for more information.
272	embedded.Registration
273
274	// Unregister removes the callback registration from a Meter.
275	//
276	// This method needs to be idempotent and concurrent safe.
277	Unregister() error
278}