metric: clarify sync vs observable Gauge in package godoc

The Measurements description in the metric package godoc stated that a
Gauge is used when "the most recent measurement needs to be conveyed
about an asynchronous measurement" and only referenced Int64ObservableGauge
and Float64ObservableGauge. Synchronous Gauge types (Int64Gauge,
Float64Gauge) were added to the API but not reflected here.

Update the sentence to list all four Gauge types and briefly note when
to use a synchronous variant vs an observable one.

Fixes #4801

Signed-off-by: Ali <alliasgher123@gmail.com>

Author: alliasgher

CHANGELOG.md

@@ -30,6 +30,7 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 - `ErrorType` in `go.opentelemetry.io/otel/semconv` now unwraps errors created with `fmt.Errorf` when deriving the `error.type` attribute. (#8133)
 - `go.opentelemetry.io/otel/sdk/log` now unwraps error chains created with `fmt.Errorf` when deriving the `error.type` attribute from errors on log records. (#8133)
 - `Set.MarshalLog` method in `go.opentelemetry.io/otel/attribute` now uses `Value.String` formatting following the [OpenTelemetry AnyValue representation for non-OTLP protocols](https://opentelemetry.io/docs/specs/otel/common/#anyvalue). (#8169)
+- Clarify in the `go.opentelemetry.io/otel/metric` package godoc that Gauge instruments exist in both synchronous (`Int64Gauge`, `Float64Gauge`) and observable forms, and describe when to use each. (#XXXX)
 
 ### Deprecated
 

metric/doc.go

@@ -50,9 +50,11 @@ incrementally increase in value. UpDownCounters ([Int64UpDownCounter],
 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.
+when just the most recent measurement needs to be conveyed, a Gauge
+([Int64Gauge], [Float64Gauge], [Int64ObservableGauge], and
+[Float64ObservableGauge]) should be used: the synchronous variants record an
+instantaneous value at a specific point in code, while the observable variants
+sample the value via a callback once per collection cycle.
 
 See the [OpenTelemetry documentation] for more information about instruments
 and their intended use.