Add measurement docs to metric API

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

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