Merge branch 'main' into msg/fix-type-alias

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

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