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 /* 16 Package metric provides the OpenTelemetry API used to measure metrics about 17 source code operation. 18 19 This API is separate from its implementation so the instrumentation built from 20 it is reusable. See [go.opentelemetry.io/otel/sdk/metric] for the official 21 OpenTelemetry implementation of this API. 22 23 All measurements made with this package are made via instruments. These 24 instruments are created by a [Meter] which itself is created by a 25 [MeterProvider]. Applications need to accept a [MeterProvider] implementation 26 as a starting point when instrumenting. This can be done directly, or by using 27 the OpenTelemetry global MeterProvider via [GetMeterProvider]. Using an 28 appropriately named [Meter] from the accepted [MeterProvider], instrumentation 29 can then be built from the [Meter]'s instruments. 30 31 # Instruments 32 33 Each instrument is designed to make measurements of a particular type. Broadly, 34 all instruments fall into two overlapping logical categories: asynchronous or 35 synchronous, and int64 or float64. 36 37 All synchronous instruments ([Int64Counter], [Int64UpDownCounter], 38 [Int64Histogram], [Float64Counter], [Float64UpDownCounter], and 39 [Float64Histogram]) are used to measure the operation and performance of source 40 code during the source code execution. These instruments only make measurements 41 when the source code they instrument is run. 42 43 All asynchronous instruments ([Int64ObservableCounter], 44 [Int64ObservableUpDownCounter], [Int64ObservableGauge], 45 [Float64ObservableCounter], [Float64ObservableUpDownCounter], and 46 [Float64ObservableGauge]) are used to measure metrics outside of the execution 47 of source code. They are said to make "observations" via a callback function 48 called once every measurement collection cycle. 49 50 Each instrument is also grouped by the value type it measures. Either int64 or 51 float64. The value being measured will dictate which instrument in these 52 categories to use. 53 54 Outside of these two broad categories, instruments are described by the 55 function they are designed to serve. All Counters ([Int64Counter], 56 [Float64Counter], [Int64ObservableCounter], and [Float64ObservableCounter]) are 57 designed to measure values that never decrease in value, but instead only 58 incrementally increase in value. UpDownCounters ([Int64UpDownCounter], 59 [Float64UpDownCounter], [Int64ObservableUpDownCounter], and 60 [Float64ObservableUpDownCounter]) on the other hand, are designed to measure 61 values that can increase and decrease. When more information needs to be 62 conveyed about all the synchronous measurements made during a collection cycle, 63 a Histogram ([Int64Histogram] and [Float64Histogram]) should be used. Finally, 64 when just the most recent measurement needs to be conveyed about an 65 asynchronous measurement, a Gauge ([Int64ObservableGauge] and 66 [Float64ObservableGauge]) should be used. 67 68 See the [OpenTelemetry documentation] for more information about instruments 69 and their intended use. 70 71 # Measurements 72 73 Measurements are made by recording values and information about the values with 74 an instrument. How these measurements are recorded depends on the instrument. 75 76 Measurements for synchronous instruments ([Int64Counter], [Int64UpDownCounter], 77 [Int64Histogram], [Float64Counter], [Float64UpDownCounter], and 78 [Float64Histogram]) are recorded using the instrument methods directly. All 79 counter instruments have an Add method that is used to measure an increment 80 value, and all histogram instruments have a Record method to measure a data 81 point. 82 83 Asynchronous instruments ([Int64ObservableCounter], 84 [Int64ObservableUpDownCounter], [Int64ObservableGauge], 85 [Float64ObservableCounter], [Float64ObservableUpDownCounter], and 86 [Float64ObservableGauge]) record measurements within a callback function. The 87 callback is registered with the Meter which ensures the callback is called once 88 per collection cycle. A callback can be registered two ways: during the 89 instrument's creation using an option, or later using the RegisterCallback 90 method of the [Meter] that created the instrument. 91 92 If the following criteria are met, an option ([WithInt64Callback] or 93 [WithFloat64Callback]) can be used during the asynchronous instrument's 94 creation to register a callback ([Int64Callback] or [Float64Callback], 95 respectively): 96 97 - The measurement process is known when the instrument is created 98 - Only that instrument will make a measurement within the callback 99 - The callback never needs to be unregistered 100 101 If the criteria are not met, use the RegisterCallback method of the [Meter] that 102 created the instrument to register a [Callback]. 103 104 # API Implementations 105 106 This package does not conform to the standard Go versioning policy, all of its 107 interfaces may have methods added to them without a package major version bump. 108 This non-standard API evolution could surprise an uninformed implementation 109 author. They could unknowingly build their implementation in a way that would 110 result in a runtime panic for their users that update to the new API. 111 112 The API is designed to help inform an instrumentation author about this 113 non-standard API evolution. It requires them to choose a default behavior for 114 unimplemented interface methods. There are three behavior choices they can 115 make: 116 117 - Compilation failure 118 - Panic 119 - Default to another implementation 120 121 All interfaces in this API embed a corresponding interface from 122 [go.opentelemetry.io/otel/metric/embedded]. If an author wants the default 123 behavior of their implementations to be a compilation failure, signaling to 124 their users they need to update to the latest version of that implementation, 125 they need to embed the corresponding interface from 126 [go.opentelemetry.io/otel/metric/embedded] in their implementation. For 127 example, 128 129 import "go.opentelemetry.io/otel/metric/embedded" 130 131 type MeterProvider struct { 132 embedded.MeterProvider 133 // ... 134 } 135 136 If an author wants the default behavior of their implementations to a panic, 137 they need to embed the API interface directly. 138 139 import "go.opentelemetry.io/otel/metric" 140 141 type MeterProvider struct { 142 metric.MeterProvider 143 // ... 144 } 145 146 This is not a recommended behavior as it could lead to publishing packages that 147 contain runtime panics when users update other package that use newer versions 148 of [go.opentelemetry.io/otel/metric]. 149 150 Finally, an author can embed another implementation in theirs. The embedded 151 implementation will be used for methods not defined by the author. For example, 152 an author who wants to default to silently dropping the call can use 153 [go.opentelemetry.io/otel/metric/noop]: 154 155 import "go.opentelemetry.io/otel/metric/noop" 156 157 type MeterProvider struct { 158 noop.MeterProvider 159 // ... 160 } 161 162 It is strongly recommended that authors only embed 163 [go.opentelemetry.io/otel/metric/noop] if they choose this default behavior. 164 That implementation is the only one OpenTelemetry authors can guarantee will 165 fully implement all the API interfaces when a user updates their API. 166 167 [OpenTelemetry documentation]: https://opentelemetry.io/docs/concepts/signals/metrics/ 168 [GetMeterProvider]: https://pkg.go.dev/go.opentelemetry.io/otel#GetMeterProvider 169 */ 170 package metric // import "go.opentelemetry.io/otel/metric" 171