diff --git a/metric/doc.go b/metric/doc.go index bda14e10aa6..ae24e448d91 100644 --- a/metric/doc.go +++ b/metric/doc.go @@ -35,14 +35,14 @@ all instruments fall into two overlapping logical categories: asynchronous or synchronous, and int64 or float64. All synchronous instruments ([Int64Counter], [Int64UpDownCounter], -[Int64Histogram], [Float64Counter], [Float64UpDownCounter], [Float64Histogram]) -are used to measure the operation and performance of source code during the -source code execution. These instruments only make measurements when the source -code they instrument is run. +[Int64Histogram], [Float64Counter], [Float64UpDownCounter], and +[Float64Histogram]) are used to measure the operation and performance of source +code during the source code execution. These instruments only make measurements +when the source code they instrument is run. All asynchronous instruments ([Int64ObservableCounter], [Int64ObservableUpDownCounter], [Int64ObservableGauge], -[Float64ObservableCounter], [Float64ObservableUpDownCounter], +[Float64ObservableCounter], [Float64ObservableUpDownCounter], and [Float64ObservableGauge]) are used to measure metrics outside of the execution of source code. They are said to make "observations" via a callback function called once every measurement collection cycle. @@ -53,21 +53,54 @@ categories to use. Outside of these two broad categories, instruments are described by the function they are designed to serve. All Counters ([Int64Counter], -[Float64Counter], [Int64ObservableCounter], [Float64ObservableCounter]) are +[Float64Counter], [Int64ObservableCounter], and [Float64ObservableCounter]) are designed to measure values that never decrease in value, but instead only incrementally increase in value. UpDownCounters ([Int64UpDownCounter], -[Float64UpDownCounter], [Int64ObservableUpDownCounter], +[Float64UpDownCounter], [Int64ObservableUpDownCounter], and [Float64ObservableUpDownCounter]) on the other hand, are designed to measure -values that can increase and decrease. When more information -needs to be conveyed about all the synchronous measurements made during a -collection cycle, a Histogram ([Int64Histogram], [Float64Histogram]) should be -used. Finally, when just the most recent measurement needs to be conveyed about an -asynchronous measurement, a Gauge ([Int64ObservableGauge], +values that can increase and decrease. When more information needs to be +conveyed about all the synchronous measurements made during a collection cycle, +a Histogram ([Int64Histogram] and [Float64Histogram]) should be used. Finally, +when just the most recent measurement needs to be conveyed about an +asynchronous measurement, a Gauge ([Int64ObservableGauge] and [Float64ObservableGauge]) should be used. See the [OpenTelemetry documentation] for more information about instruments and their intended use. +# Measurements + +Measurements are made by recording values and information about the values with +an instrument. How these measurements are recorded depends on the instrument. + +Measurements for synchronous instruments ([Int64Counter], [Int64UpDownCounter], +[Int64Histogram], [Float64Counter], [Float64UpDownCounter], and +[Float64Histogram]) are recorded using the instrument methods directly. All +counter instruments have an Add method that is used to measure an increment +value, and all histogram instruments have a Record method to measure a data +point. + +Asynchronous instruments ([Int64ObservableCounter], +[Int64ObservableUpDownCounter], [Int64ObservableGauge], +[Float64ObservableCounter], [Float64ObservableUpDownCounter], and +[Float64ObservableGauge]) record measurements within a callback function. The +callback is registered with the Meter which ensures the callback is called once +per collection cycle. A callback can be registered two ways: during the +instrument's creation using an option, or later using the RegisterCallback +method of the [Meter] that created the instrument. + +If the following criteria are met, an option ([WithInt64Callback] or +[WithFloat64Callback]) can be used during the asynchronous instrument's +creation to register a callback ([Int64Callback] or [Float64Callback], +respectively): + + - The measurement process is known when the instrument is created + - Only that instrument will make a measurement within the callback + - The callback never needs to be unregistered + +If the criteria are not met, use the RegisterCallback method of the [Meter] that +created the instrument to register a [Callback]. + # API Implementations This package does not conform to the standard Go versioning policy, all of its diff --git a/metric/meter.go b/metric/meter.go index c55d2defa6f..8e1917c3214 100644 --- a/metric/meter.go +++ b/metric/meter.go @@ -55,58 +55,95 @@ type Meter interface { // section of the package documentation for more information. embedded.Meter - // Int64Counter returns a new instrument identified by name and configured - // with options. The instrument is used to synchronously record increasing - // int64 measurements during a computational operation. + // Int64Counter returns a new Int64Counter instrument identified by name + // and configured with options. The instrument is used to synchronously + // record increasing int64 measurements during a computational operation. Int64Counter(name string, options ...Int64CounterOption) (Int64Counter, error) - // Int64UpDownCounter returns a new instrument identified by name and - // configured with options. The instrument is used to synchronously record - // int64 measurements during a computational operation. + // Int64UpDownCounter returns a new Int64UpDownCounter instrument + // identified by name and configured with options. The instrument is used + // to synchronously record int64 measurements during a computational + // operation. Int64UpDownCounter(name string, options ...Int64UpDownCounterOption) (Int64UpDownCounter, error) - // Int64Histogram returns a new instrument identified by name and - // configured with options. The instrument is used to synchronously record - // the distribution of int64 measurements during a computational operation. + // Int64Histogram returns a new Int64Histogram instrument identified by + // name and configured with options. The instrument is used to + // synchronously record the distribution of int64 measurements during a + // computational operation. Int64Histogram(name string, options ...Int64HistogramOption) (Int64Histogram, error) - // Int64ObservableCounter returns a new instrument identified by name and - // configured with options. The instrument is used to asynchronously record - // increasing int64 measurements once per a measurement collection cycle. + // Int64ObservableCounter returns a new Int64ObservableCounter identified + // by name and configured with options. The instrument is used to + // asynchronously record increasing int64 measurements once per a + // measurement collection cycle. + // + // Measurements for the returned instrument are made via a callback. Use + // the WithInt64Callback option to register the callback here, or use the + // RegisterCallback method of this Meter to register one later. See the + // Measurements section of the package documentation for more information. Int64ObservableCounter(name string, options ...Int64ObservableCounterOption) (Int64ObservableCounter, error) - // Int64ObservableUpDownCounter returns a new instrument identified by name - // and configured with options. The instrument is used to asynchronously - // record int64 measurements once per a measurement collection cycle. + // Int64ObservableUpDownCounter returns a new Int64ObservableUpDownCounter + // instrument identified by name and configured with options. The + // instrument is used to asynchronously record int64 measurements once per + // a measurement collection cycle. + // + // Measurements for the returned instrument are made via a callback. Use + // the WithInt64Callback option to register the callback here, or use the + // RegisterCallback method of this Meter to register one later. See the + // Measurements section of the package documentation for more information. Int64ObservableUpDownCounter(name string, options ...Int64ObservableUpDownCounterOption) (Int64ObservableUpDownCounter, error) - // Int64ObservableGauge returns a new instrument identified by name and - // configured with options. The instrument is used to asynchronously record - // instantaneous int64 measurements once per a measurement collection - // cycle. + // Int64ObservableGauge returns a new Int64ObservableGauge instrument + // identified by name and configured with options. The instrument is used + // to asynchronously record instantaneous int64 measurements once per a + // measurement collection cycle. + // + // Measurements for the returned instrument are made via a callback. Use + // the WithInt64Callback option to register the callback here, or use the + // RegisterCallback method of this Meter to register one later. See the + // Measurements section of the package documentation for more information. Int64ObservableGauge(name string, options ...Int64ObservableGaugeOption) (Int64ObservableGauge, error) - // Float64Counter returns a new instrument identified by name and - // configured with options. The instrument is used to synchronously record - // increasing float64 measurements during a computational operation. + // Float64Counter returns a new Float64Counter instrument identified by + // name and configured with options. The instrument is used to + // synchronously record increasing float64 measurements during a + // computational operation. Float64Counter(name string, options ...Float64CounterOption) (Float64Counter, error) - // Float64UpDownCounter returns a new instrument identified by name and - // configured with options. The instrument is used to synchronously record - // float64 measurements during a computational operation. - Float64UpDownCounter(name string, options ...Float64UpDownCounterOption) (Float64UpDownCounter, error) - // Float64Histogram returns a new instrument identified by name and - // configured with options. The instrument is used to synchronously record - // the distribution of float64 measurements during a computational + // Float64UpDownCounter returns a new Float64UpDownCounter instrument + // identified by name and configured with options. The instrument is used + // to synchronously record float64 measurements during a computational // operation. + Float64UpDownCounter(name string, options ...Float64UpDownCounterOption) (Float64UpDownCounter, error) + // Float64Histogram returns a new Float64Histogram instrument identified by + // name and configured with options. The instrument is used to + // synchronously record the distribution of float64 measurements during a + // computational operation. Float64Histogram(name string, options ...Float64HistogramOption) (Float64Histogram, error) - // Float64ObservableCounter returns a new instrument identified by name and - // configured with options. The instrument is used to asynchronously record - // increasing float64 measurements once per a measurement collection cycle. + // Float64ObservableCounter returns a new Float64ObservableCounter + // instrument identified by name and configured with options. The + // instrument is used to asynchronously record increasing float64 + // measurements once per a measurement collection cycle. + // + // Measurements for the returned instrument are made via a callback. Use + // the WithFloat64Callback option to register the callback here, or use the + // RegisterCallback method of this Meter to register one later. See the + // Measurements section of the package documentation for more information. Float64ObservableCounter(name string, options ...Float64ObservableCounterOption) (Float64ObservableCounter, error) - // Float64ObservableUpDownCounter returns a new instrument identified by - // name and configured with options. The instrument is used to - // asynchronously record float64 measurements once per a measurement - // collection cycle. - Float64ObservableUpDownCounter(name string, options ...Float64ObservableUpDownCounterOption) (Float64ObservableUpDownCounter, error) - // Float64ObservableGauge returns a new instrument identified by name and + // Float64ObservableUpDownCounter returns a new + // Float64ObservableUpDownCounter instrument identified by name and // configured with options. The instrument is used to asynchronously record - // instantaneous float64 measurements once per a measurement collection - // cycle. + // float64 measurements once per a measurement collection cycle. + // + // Measurements for the returned instrument are made via a callback. Use + // the WithFloat64Callback option to register the callback here, or use the + // RegisterCallback method of this Meter to register one later. See the + // Measurements section of the package documentation for more information. + Float64ObservableUpDownCounter(name string, options ...Float64ObservableUpDownCounterOption) (Float64ObservableUpDownCounter, error) + // Float64ObservableGauge returns a new Float64ObservableGauge instrument + // identified by name and configured with options. The instrument is used + // to asynchronously record instantaneous float64 measurements once per a + // measurement collection cycle. + // + // Measurements for the returned instrument are made via a callback. Use + // the WithFloat64Callback option to register the callback here, or use the + // RegisterCallback method of this Meter to register one later. See the + // Measurements section of the package documentation for more information. Float64ObservableGauge(name string, options ...Float64ObservableGaugeOption) (Float64ObservableGauge, error) // RegisterCallback registers f to be called during the collection of a