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 // Int64Observable describes a set of instruments used asynchronously to record
13 // int64 measurements once per collection cycle. Observations of these
14 // instruments are only made within a callback.
15 //
16 // Warning: Methods may be added to this interface in minor releases.
17 type Int64Observable interface {
18 Observable
19 20 int64Observable()
21 }
22 23 // Int64ObservableCounter is an instrument used to asynchronously record
24 // increasing int64 measurements once per collection cycle. Observations are
25 // only made within a callback for this instrument. The value observed is
26 // assumed the to be the cumulative sum of the count.
27 //
28 // Warning: Methods may be added to this interface in minor releases. See
29 // package documentation on API implementation for information on how to set
30 // default behavior for unimplemented methods.
31 type Int64ObservableCounter interface {
32 // Users of the interface can ignore this. This embedded type is only used
33 // by implementations of this interface. See the "API Implementations"
34 // section of the package documentation for more information.
35 embedded.Int64ObservableCounter
36 37 Int64Observable
38 }
39 40 // Int64ObservableCounterConfig contains options for asynchronous counter
41 // instruments that record int64 values.
42 type Int64ObservableCounterConfig struct {
43 description string
44 unit string
45 callbacks []Int64Callback
46 }
47 48 // NewInt64ObservableCounterConfig returns a new [Int64ObservableCounterConfig]
49 // with all opts applied.
50 func NewInt64ObservableCounterConfig(opts ...Int64ObservableCounterOption) Int64ObservableCounterConfig {
51 var config Int64ObservableCounterConfig
52 for _, o := range opts {
53 config = o.applyInt64ObservableCounter(config)
54 }
55 return config
56 }
57 58 // Description returns the configured description.
59 func (c Int64ObservableCounterConfig) Description() string {
60 return c.description
61 }
62 63 // Unit returns the configured unit.
64 func (c Int64ObservableCounterConfig) Unit() string {
65 return c.unit
66 }
67 68 // Callbacks returns the configured callbacks.
69 func (c Int64ObservableCounterConfig) Callbacks() []Int64Callback {
70 return c.callbacks
71 }
72 73 // Int64ObservableCounterOption applies options to a
74 // [Int64ObservableCounterConfig]. See [Int64ObservableOption] and
75 // [InstrumentOption] for other options that can be used as an
76 // Int64ObservableCounterOption.
77 type Int64ObservableCounterOption interface {
78 applyInt64ObservableCounter(Int64ObservableCounterConfig) Int64ObservableCounterConfig
79 }
80 81 // Int64ObservableUpDownCounter is an instrument used to asynchronously record
82 // int64 measurements once per collection cycle. Observations are only made
83 // within a callback for this instrument. The value observed is assumed the to
84 // be the cumulative sum of the count.
85 //
86 // Warning: Methods may be added to this interface in minor releases. See
87 // package documentation on API implementation for information on how to set
88 // default behavior for unimplemented methods.
89 type Int64ObservableUpDownCounter interface {
90 // Users of the interface can ignore this. This embedded type is only used
91 // by implementations of this interface. See the "API Implementations"
92 // section of the package documentation for more information.
93 embedded.Int64ObservableUpDownCounter
94 95 Int64Observable
96 }
97 98 // Int64ObservableUpDownCounterConfig contains options for asynchronous counter
99 // instruments that record int64 values.
100 type Int64ObservableUpDownCounterConfig struct {
101 description string
102 unit string
103 callbacks []Int64Callback
104 }
105 106 // NewInt64ObservableUpDownCounterConfig returns a new
107 // [Int64ObservableUpDownCounterConfig] with all opts applied.
108 func NewInt64ObservableUpDownCounterConfig(
109 opts ...Int64ObservableUpDownCounterOption,
110 ) Int64ObservableUpDownCounterConfig {
111 var config Int64ObservableUpDownCounterConfig
112 for _, o := range opts {
113 config = o.applyInt64ObservableUpDownCounter(config)
114 }
115 return config
116 }
117 118 // Description returns the configured description.
119 func (c Int64ObservableUpDownCounterConfig) Description() string {
120 return c.description
121 }
122 123 // Unit returns the configured unit.
124 func (c Int64ObservableUpDownCounterConfig) Unit() string {
125 return c.unit
126 }
127 128 // Callbacks returns the configured callbacks.
129 func (c Int64ObservableUpDownCounterConfig) Callbacks() []Int64Callback {
130 return c.callbacks
131 }
132 133 // Int64ObservableUpDownCounterOption applies options to a
134 // [Int64ObservableUpDownCounterConfig]. See [Int64ObservableOption] and
135 // [InstrumentOption] for other options that can be used as an
136 // Int64ObservableUpDownCounterOption.
137 type Int64ObservableUpDownCounterOption interface {
138 applyInt64ObservableUpDownCounter(Int64ObservableUpDownCounterConfig) Int64ObservableUpDownCounterConfig
139 }
140 141 // Int64ObservableGauge is an instrument used to asynchronously record
142 // instantaneous int64 measurements once per collection cycle. Observations are
143 // only made within a callback for this instrument.
144 //
145 // Warning: Methods may be added to this interface in minor releases. See
146 // package documentation on API implementation for information on how to set
147 // default behavior for unimplemented methods.
148 type Int64ObservableGauge interface {
149 // Users of the interface can ignore this. This embedded type is only used
150 // by implementations of this interface. See the "API Implementations"
151 // section of the package documentation for more information.
152 embedded.Int64ObservableGauge
153 154 Int64Observable
155 }
156 157 // Int64ObservableGaugeConfig contains options for asynchronous counter
158 // instruments that record int64 values.
159 type Int64ObservableGaugeConfig struct {
160 description string
161 unit string
162 callbacks []Int64Callback
163 }
164 165 // NewInt64ObservableGaugeConfig returns a new [Int64ObservableGaugeConfig]
166 // with all opts applied.
167 func NewInt64ObservableGaugeConfig(opts ...Int64ObservableGaugeOption) Int64ObservableGaugeConfig {
168 var config Int64ObservableGaugeConfig
169 for _, o := range opts {
170 config = o.applyInt64ObservableGauge(config)
171 }
172 return config
173 }
174 175 // Description returns the configured description.
176 func (c Int64ObservableGaugeConfig) Description() string {
177 return c.description
178 }
179 180 // Unit returns the configured unit.
181 func (c Int64ObservableGaugeConfig) Unit() string {
182 return c.unit
183 }
184 185 // Callbacks returns the configured callbacks.
186 func (c Int64ObservableGaugeConfig) Callbacks() []Int64Callback {
187 return c.callbacks
188 }
189 190 // Int64ObservableGaugeOption applies options to a
191 // [Int64ObservableGaugeConfig]. See [Int64ObservableOption] and
192 // [InstrumentOption] for other options that can be used as an
193 // Int64ObservableGaugeOption.
194 type Int64ObservableGaugeOption interface {
195 applyInt64ObservableGauge(Int64ObservableGaugeConfig) Int64ObservableGaugeConfig
196 }
197 198 // Int64Observer is a recorder of int64 measurements.
199 //
200 // Warning: Methods may be added to this interface in minor releases. See
201 // package documentation on API implementation for information on how to set
202 // default behavior for unimplemented methods.
203 type Int64Observer interface {
204 // Users of the interface can ignore this. This embedded type is only used
205 // by implementations of this interface. See the "API Implementations"
206 // section of the package documentation for more information.
207 embedded.Int64Observer
208 209 // Observe records the int64 value.
210 //
211 // Use the WithAttributeSet (or, if performance is not a concern,
212 // the WithAttributes) option to include measurement attributes.
213 Observe(value int64, options ...ObserveOption)
214 }
215 216 // Int64Callback is a function registered with a Meter that makes observations
217 // for an Int64Observable instrument it is registered with. Calls to the
218 // Int64Observer record measurement values for the Int64Observable.
219 //
220 // The function needs to complete in a finite amount of time and the deadline
221 // of the passed context is expected to be honored.
222 //
223 // The function needs to make unique observations across all registered
224 // Int64Callbacks. Meaning, it should not report measurements with the same
225 // attributes as another Int64Callbacks also registered for the same
226 // instrument.
227 //
228 // The function needs to be concurrent safe.
229 type Int64Callback func(context.Context, Int64Observer) error
230 231 // Int64ObservableOption applies options to int64 Observer instruments.
232 type Int64ObservableOption interface {
233 Int64ObservableCounterOption
234 Int64ObservableUpDownCounterOption
235 Int64ObservableGaugeOption
236 }
237 238 type int64CallbackOpt struct {
239 cback Int64Callback
240 }
241 242 func (o int64CallbackOpt) applyInt64ObservableCounter(cfg Int64ObservableCounterConfig) Int64ObservableCounterConfig {
243 cfg.callbacks = append(cfg.callbacks, o.cback)
244 return cfg
245 }
246 247 func (o int64CallbackOpt) applyInt64ObservableUpDownCounter(
248 cfg Int64ObservableUpDownCounterConfig,
249 ) Int64ObservableUpDownCounterConfig {
250 cfg.callbacks = append(cfg.callbacks, o.cback)
251 return cfg
252 }
253 254 func (o int64CallbackOpt) applyInt64ObservableGauge(cfg Int64ObservableGaugeConfig) Int64ObservableGaugeConfig {
255 cfg.callbacks = append(cfg.callbacks, o.cback)
256 return cfg
257 }
258 259 // WithInt64Callback adds callback to be called for an instrument.
260 func WithInt64Callback(callback Int64Callback) Int64ObservableOption {
261 return int64CallbackOpt{callback}
262 }
263