From 5c5184827197b365b846209f73afa540a5918ef1 Mon Sep 17 00:00:00 2001 From: Tyler Yahn Date: Fri, 5 May 2023 12:29:54 -0700 Subject: [PATCH 1/6] Add measurement docs to metric API Based on user feedback, how measurements are made with observable instruments is not immediately clear to new users. This adds documentation intended to help guide these users. --- metric/doc.go | 31 +++++++++++++ metric/meter.go | 117 +++++++++++++++++++++++++++++++----------------- 2 files changed, 108 insertions(+), 40 deletions(-) diff --git a/metric/doc.go b/metric/doc.go index bda14e10aa6..cffa78af9b6 100644 --- a/metric/doc.go +++ b/metric/doc.go @@ -68,6 +68,37 @@ asynchronous measurement, a Gauge ([Int64ObservableGauge], 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], [Float64Histogram]) +are made 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], +[Float64ObservableGauge]) make 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 its +creation using an option; the RegisterCallback method of the Meter that created +the instrument. + +If the following criteria are meet, an option (i.e. [WithInt64Callback], +[WithFloat64Callback]) can be used during the asynchronous instrument's +creation to register a callback ([Int64Callback], [Float64Callback]): + + - 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 not, 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 1d60cf57a4d..97a750e1814 100644 --- a/metric/meter.go +++ b/metric/meter.go @@ -49,58 +49,95 @@ type MeterProvider interface { type Meter interface { 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 From 8d0857954d41bf8f7a381791497b936274c04b74 Mon Sep 17 00:00:00 2001 From: Tyler Yahn Date: Fri, 5 May 2023 16:38:11 -0700 Subject: [PATCH 2/6] Apply feedback --- metric/doc.go | 52 ++++++++++++++++++++++++++------------------------- 1 file changed, 27 insertions(+), 25 deletions(-) diff --git a/metric/doc.go b/metric/doc.go index cffa78af9b6..86a37718e23 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,16 +53,16 @@ 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 @@ -74,30 +74,32 @@ 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], [Float64Histogram]) -are made 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. +[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], -[Float64ObservableGauge]) make measurements within a callback function. The +[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 its -creation using an option; the RegisterCallback method of the Meter that created -the instrument. +per collection cycle. A callback can be registered two ways: during the +creation of an instrument using an option; using the RegisterCallback method of +the Meter that created the instrument. -If the following criteria are meet, an option (i.e. [WithInt64Callback], +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], [Float64Callback]): +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 not, use the RegisterCallback method of the Meter that created the -instrument to register a [Callback]. +If the criteria are not met, use the RegisterCallback method of the Meter that +created the instrument to register a [Callback]. # API Implementations From 11d520dc1343feb9f79086db3cb0d68c4fe53dda Mon Sep 17 00:00:00 2001 From: Tyler Yahn Date: Fri, 5 May 2023 16:40:14 -0700 Subject: [PATCH 3/6] Apply feedback --- metric/doc.go | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/metric/doc.go b/metric/doc.go index 86a37718e23..9a0e6c53dbc 100644 --- a/metric/doc.go +++ b/metric/doc.go @@ -86,8 +86,8 @@ Asynchronous instruments ([Int64ObservableCounter], [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 -creation of an instrument using an option; using the RegisterCallback method of -the Meter that created the instrument. +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 From 87892cefb8eec5712808dde4c33caffb3a35e3ac Mon Sep 17 00:00:00 2001 From: Tyler Yahn Date: Sun, 7 May 2023 09:39:47 -0700 Subject: [PATCH 4/6] Remove backticks --- metric/doc.go | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/metric/doc.go b/metric/doc.go index 9a0e6c53dbc..17cf0d893a2 100644 --- a/metric/doc.go +++ b/metric/doc.go @@ -76,8 +76,8 @@ 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 +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], From fff14fff3a1b11cdc477d197ed7148b6d4b5f8e4 Mon Sep 17 00:00:00 2001 From: Tyler Yahn Date: Mon, 8 May 2023 08:28:07 -0700 Subject: [PATCH 5/6] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Robert Pająk --- metric/doc.go | 4 ++-- metric/meter.go | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/metric/doc.go b/metric/doc.go index 17cf0d893a2..ae24e448d91 100644 --- a/metric/doc.go +++ b/metric/doc.go @@ -87,7 +87,7 @@ Asynchronous instruments ([Int64ObservableCounter], 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. +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 @@ -98,7 +98,7 @@ respectively): - 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 +If the criteria are not met, use the RegisterCallback method of the [Meter] that created the instrument to register a [Callback]. # API Implementations diff --git a/metric/meter.go b/metric/meter.go index 97a750e1814..364e56f9a8c 100644 --- a/metric/meter.go +++ b/metric/meter.go @@ -58,7 +58,7 @@ type Meter interface { // to synchronously record int64 measurements during a computational // operation. Int64UpDownCounter(name string, options ...Int64UpDownCounterOption) (Int64UpDownCounter, error) - // Int64Histogram returns a new Int64Histogram instrument identified by + // 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. From 0c38f23eae2925e63f5a33a61cb5c0e010ffe549 Mon Sep 17 00:00:00 2001 From: Tyler Yahn Date: Mon, 8 May 2023 09:06:00 -0700 Subject: [PATCH 6/6] Update metric/meter.go MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Robert Pająk --- metric/meter.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/metric/meter.go b/metric/meter.go index 07bbdab7e51..8e1917c3214 100644 --- a/metric/meter.go +++ b/metric/meter.go @@ -64,7 +64,7 @@ type Meter interface { // to synchronously record int64 measurements during a computational // operation. Int64UpDownCounter(name string, options ...Int64UpDownCounterOption) (Int64UpDownCounter, error) - // Int64Histogram returns a new [Int64Histogram] instrument identified by + // 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.