Add measurement docs to metric API (#4053)

* 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. * Apply feedback * Apply feedback * Remove backticks * Apply suggestions from code review Co-authored-by: Robert Pająk <[email protected]> * Update metric/meter.go Co-authored-by: Robert Pająk <[email protected]> --------- Co-authored-by: Robert Pająk <[email protected]> Co-authored-by: Chester Cheung <[email protected]>
open-telemetry · May 10, 2023 · 0b61641 · 0b61641
1 parent 4d473d1
commit 0b61641
Show file tree

Hide file tree

Showing 2 changed files with 122 additions and 52 deletions.
diff --git 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
@@ -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