1 // 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 15 package metric // import "go.opentelemetry.io/otel/metric" 16 17 import ( 18 "context" 19 20 "go.opentelemetry.io/otel/metric/embedded" 21 ) 22 23 // MeterProvider provides access to named Meter instances, for instrumenting 24 // an application or package. 25 // 26 // Warning: Methods may be added to this interface in minor releases. See 27 // package documentation on API implementation for information on how to set 28 // default behavior for unimplemented methods. 29 type MeterProvider interface { 30 // Users of the interface can ignore this. This embedded type is only used 31 // by implementations of this interface. See the "API Implementations" 32 // section of the package documentation for more information. 33 embedded.MeterProvider 34 35 // Meter returns a new Meter with the provided name and configuration. 36 // 37 // A Meter should be scoped at most to a single package. The name needs to 38 // be unique so it does not collide with other names used by 39 // an application, nor other applications. To achieve this, the import path 40 // of the instrumentation package is recommended to be used as name. 41 // 42 // If the name is empty, then an implementation defined default name will 43 // be used instead. 44 Meter(name string, opts ...MeterOption) Meter 45 } 46 47 // Meter provides access to instrument instances for recording metrics. 48 // 49 // Warning: Methods may be added to this interface in minor releases. See 50 // package documentation on API implementation for information on how to set 51 // default behavior for unimplemented methods. 52 type Meter interface { 53 // Users of the interface can ignore this. This embedded type is only used 54 // by implementations of this interface. See the "API Implementations" 55 // section of the package documentation for more information. 56 embedded.Meter 57 58 // Int64Counter returns a new Int64Counter instrument identified by name 59 // and configured with options. The instrument is used to synchronously 60 // record increasing int64 measurements during a computational operation. 61 Int64Counter(name string, options ...Int64CounterOption) (Int64Counter, error) 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 Int64UpDownCounter(name string, options ...Int64UpDownCounterOption) (Int64UpDownCounter, error) 67 // Int64Histogram returns a new Int64Histogram instrument identified by 68 // name and configured with options. The instrument is used to 69 // synchronously record the distribution of int64 measurements during a 70 // computational operation. 71 Int64Histogram(name string, options ...Int64HistogramOption) (Int64Histogram, error) 72 // Int64ObservableCounter returns a new Int64ObservableCounter identified 73 // by name and configured with options. The instrument is used to 74 // asynchronously record increasing int64 measurements once per a 75 // measurement collection cycle. 76 // 77 // Measurements for the returned instrument are made via a callback. Use 78 // the WithInt64Callback option to register the callback here, or use the 79 // RegisterCallback method of this Meter to register one later. See the 80 // Measurements section of the package documentation for more information. 81 Int64ObservableCounter(name string, options ...Int64ObservableCounterOption) (Int64ObservableCounter, error) 82 // Int64ObservableUpDownCounter returns a new Int64ObservableUpDownCounter 83 // instrument identified by name and configured with options. The 84 // instrument is used to asynchronously record int64 measurements once per 85 // a measurement collection cycle. 86 // 87 // Measurements for the returned instrument are made via a callback. Use 88 // the WithInt64Callback option to register the callback here, or use the 89 // RegisterCallback method of this Meter to register one later. See the 90 // Measurements section of the package documentation for more information. 91 Int64ObservableUpDownCounter(name string, options ...Int64ObservableUpDownCounterOption) (Int64ObservableUpDownCounter, error) 92 // Int64ObservableGauge returns a new Int64ObservableGauge instrument 93 // identified by name and configured with options. The instrument is used 94 // to asynchronously record instantaneous int64 measurements once per a 95 // measurement collection cycle. 96 // 97 // Measurements for the returned instrument are made via a callback. Use 98 // the WithInt64Callback option to register the callback here, or use the 99 // RegisterCallback method of this Meter to register one later. See the 100 // Measurements section of the package documentation for more information. 101 Int64ObservableGauge(name string, options ...Int64ObservableGaugeOption) (Int64ObservableGauge, error) 102 103 // Float64Counter returns a new Float64Counter instrument identified by 104 // name and configured with options. The instrument is used to 105 // synchronously record increasing float64 measurements during a 106 // computational operation. 107 Float64Counter(name string, options ...Float64CounterOption) (Float64Counter, error) 108 // Float64UpDownCounter returns a new Float64UpDownCounter instrument 109 // identified by name and configured with options. The instrument is used 110 // to synchronously record float64 measurements during a computational 111 // operation. 112 Float64UpDownCounter(name string, options ...Float64UpDownCounterOption) (Float64UpDownCounter, error) 113 // Float64Histogram returns a new Float64Histogram instrument identified by 114 // name and configured with options. The instrument is used to 115 // synchronously record the distribution of float64 measurements during a 116 // computational operation. 117 Float64Histogram(name string, options ...Float64HistogramOption) (Float64Histogram, error) 118 // Float64ObservableCounter returns a new Float64ObservableCounter 119 // instrument identified by name and configured with options. The 120 // instrument is used to asynchronously record increasing float64 121 // measurements once per a measurement collection cycle. 122 // 123 // Measurements for the returned instrument are made via a callback. Use 124 // the WithFloat64Callback 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 Float64ObservableCounter(name string, options ...Float64ObservableCounterOption) (Float64ObservableCounter, error) 128 // Float64ObservableUpDownCounter returns a new 129 // Float64ObservableUpDownCounter instrument identified by name and 130 // configured with options. The instrument is used to asynchronously record 131 // float64 measurements once per a measurement collection cycle. 132 // 133 // Measurements for the returned instrument are made via a callback. Use 134 // the WithFloat64Callback option to register the callback here, or use the 135 // RegisterCallback method of this Meter to register one later. See the 136 // Measurements section of the package documentation for more information. 137 Float64ObservableUpDownCounter(name string, options ...Float64ObservableUpDownCounterOption) (Float64ObservableUpDownCounter, error) 138 // Float64ObservableGauge returns a new Float64ObservableGauge instrument 139 // identified by name and configured with options. The instrument is used 140 // to asynchronously record instantaneous float64 measurements once per a 141 // measurement collection cycle. 142 // 143 // Measurements for the returned instrument are made via a callback. Use 144 // the WithFloat64Callback option to register the callback here, or use the 145 // RegisterCallback method of this Meter to register one later. See the 146 // Measurements section of the package documentation for more information. 147 Float64ObservableGauge(name string, options ...Float64ObservableGaugeOption) (Float64ObservableGauge, error) 148 149 // RegisterCallback registers f to be called during the collection of a 150 // measurement cycle. 151 // 152 // If Unregister of the returned Registration is called, f needs to be 153 // unregistered and not called during collection. 154 // 155 // The instruments f is registered with are the only instruments that f may 156 // observe values for. 157 // 158 // If no instruments are passed, f should not be registered nor called 159 // during collection. 160 // 161 // The function f needs to be concurrent safe. 162 RegisterCallback(f Callback, instruments ...Observable) (Registration, error) 163 } 164 165 // Callback is a function registered with a Meter that makes observations for 166 // the set of instruments it is registered with. The Observer parameter is used 167 // to record measurement observations for these instruments. 168 // 169 // The function needs to complete in a finite amount of time and the deadline 170 // of the passed context is expected to be honored. 171 // 172 // The function needs to make unique observations across all registered 173 // Callbacks. Meaning, it should not report measurements for an instrument with 174 // the same attributes as another Callback will report. 175 // 176 // The function needs to be concurrent safe. 177 type Callback func(context.Context, Observer) error 178 179 // Observer records measurements for multiple instruments in a Callback. 180 // 181 // Warning: Methods may be added to this interface in minor releases. See 182 // package documentation on API implementation for information on how to set 183 // default behavior for unimplemented methods. 184 type Observer interface { 185 // Users of the interface can ignore this. This embedded type is only used 186 // by implementations of this interface. See the "API Implementations" 187 // section of the package documentation for more information. 188 embedded.Observer 189 190 // ObserveFloat64 records the float64 value for obsrv. 191 ObserveFloat64(obsrv Float64Observable, value float64, opts ...ObserveOption) 192 // ObserveInt64 records the int64 value for obsrv. 193 ObserveInt64(obsrv Int64Observable, value int64, opts ...ObserveOption) 194 } 195 196 // Registration is an token representing the unique registration of a callback 197 // for a set of instruments with a Meter. 198 // 199 // Warning: Methods may be added to this interface in minor releases. See 200 // package documentation on API implementation for information on how to set 201 // default behavior for unimplemented methods. 202 type Registration interface { 203 // Users of the interface can ignore this. This embedded type is only used 204 // by implementations of this interface. See the "API Implementations" 205 // section of the package documentation for more information. 206 embedded.Registration 207 208 // Unregister removes the callback registration from a Meter. 209 // 210 // This method needs to be idempotent and concurrent safe. 211 Unregister() error 212 } 213