Remove the unneeded Observe method from the async instruments (#3586)

* Update RegisterCallback and Callback decls

RegisterCallback accept variadic Asynchronous instruments instead of a
slice.

Callback accept an observation result recorder to ensure instruments
that are observed by a callback.

* Update global impl

* Update noop impl

* Update SDK impl

* Fix prometheus example

* Fix metric API example_test

* Remove unused registerabler

* Rename ObservationRecorder to MultiObserver

* Update Callback documentation about MultiObserver

* Remove the Observe method from async inst

* Revert to iface for Observers

* Fix async inst docs

* Update global async delegate race test

* Restore removed observe doc

* Remove TODO

* Remove stale comment

* Update changelog

CHANGELOG.md

@@ -36,7 +36,7 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 - Add the `go.opentelemetry.io/otel/semconv/v1.16.0` package.
   The package contains semantic conventions from the `v1.16.0` version of the OpenTelemetry specification. (#3579)
 - Metric instruments were added to `go.opentelemetry.io/otel/metric/instrument`.
-  These instruments are use as replacements of the depreacted `go.opentelemetry.io/otel/metric/instrument/{asyncfloat64,asyncint64,syncfloat64,syncint64}` packages.(#3575)
+  These instruments are use as replacements of the depreacted `go.opentelemetry.io/otel/metric/instrument/{asyncfloat64,asyncint64,syncfloat64,syncint64}` packages.(#3575, #3586)
   - `Float64ObservableCounter` replaces the `asyncfloat64.Counter`
   - `Float64ObservableUpDownCounter` replaces the `asyncfloat64.UpDownCounter`
   - `Float64ObservableGauge` replaces the `asyncfloat64.Gauge`

metric/example_test.go

@@ -55,7 +55,7 @@ func ExampleMeter_asynchronous_single() {
 	_, err := meter.Int64ObservableGauge(
 		"DiskUsage",
 		instrument.WithUnit(unit.Bytes),
-		instrument.WithInt64Callback(func(ctx context.Context, inst instrument.Int64Observer) error {
+		instrument.WithInt64Callback(func(_ context.Context, obsrv instrument.Int64Observer) error {
 			// Do the real work here to get the real disk usage. For example,
 			//
 			//   usage, err := GetDiskUsage(diskID)
@@ -69,7 +69,7 @@ func ExampleMeter_asynchronous_single() {
 			//
 			// For demonstration purpose, a static value is used here.
 			usage := 75000
-			inst.Observe(ctx, int64(usage), attribute.Int("disk.id", 3))
+			obsrv.Observe(int64(usage), attribute.Int("disk.id", 3))
 			return nil
 		}),
 	)

metric/instrument/asyncfloat64.go

@@ -21,45 +21,51 @@ import (
 	"go.opentelemetry.io/otel/metric/unit"
 )
 
-// Float64Observer is a recorder of float64 measurement values.
+// Float64Observable describes a set of instruments used asynchronously to
+// record float64 measurements once per collection cycle. Observations of
+// these instruments are only made within a callback.
+//
 // Warning: methods may be added to this interface in minor releases.
-type Float64Observer interface {
+type Float64Observable interface {
 	Asynchronous
 
-	// Observe records the measurement value for a set of attributes.
-	//
-	// It is only valid to call this within a callback. If called outside of
-	// the registered callback it should have no effect on the instrument, and
-	// an error will be reported via the error handler.
-	Observe(ctx context.Context, value float64, attributes ...attribute.KeyValue)
+	float64Observable()
 }
 
 // Float64ObservableCounter is an instrument used to asynchronously record
-// increasing float64 measurements once per a measurement collection cycle. The
-// Observe method is used to record the measured state of the instrument when
-// it is called. Implementations will assume the observed value to be the
-// cumulative sum of the count.
+// increasing float64 measurements once per collection cycle. Observations are
+// only made within a callback for this instrument. The value observed is
+// assumed the to be the cumulative sum of the count.
 //
 // Warning: methods may be added to this interface in minor releases.
-type Float64ObservableCounter interface{ Float64Observer }
+type Float64ObservableCounter interface{ Float64Observable }
 
 // Float64ObservableUpDownCounter is an instrument used to asynchronously
-// record float64 measurements once per a measurement collection cycle. The
-// Observe method is used to record the measured state of the instrument when
-// it is called. Implementations will assume the observed value to be the
-// cumulative sum of the count.
+// record float64 measurements once per collection cycle. Observations are only
+// made within a callback for this instrument. The value observed is assumed
+// the to be the cumulative sum of the count.
 //
 // Warning: methods may be added to this interface in minor releases.
-type Float64ObservableUpDownCounter interface{ Float64Observer }
+type Float64ObservableUpDownCounter interface{ Float64Observable }
 
 // Float64ObservableGauge is an instrument used to asynchronously record
-// instantaneous float64 measurements once per a measurement collection cycle.
+// instantaneous float64 measurements once per collection cycle. Observations
+// are only made within a callback for this instrument.
 //
 // Warning: methods may be added to this interface in minor releases.
-type Float64ObservableGauge interface{ Float64Observer }
+type Float64ObservableGauge interface{ Float64Observable }
+
+// Float64Observer is a recorder of float64 measurements.
+//
+// Warning: methods may be added to this interface in minor releases.
+type Float64Observer interface {
+	Observe(value float64, attributes ...attribute.KeyValue)
+}
 
 // Float64Callback is a function registered with a Meter that makes
-// observations for a Float64Observer it is registered with.
+// observations for a Float64Observerable instrument it is registered with.
+// Calls to the Float64Observer record measurement values for the
+// Float64Observable.
 //
 // The function needs to complete in a finite amount of time and the deadline
 // of the passed context is expected to be honored.

metric/instrument/asyncfloat64_test.go

@@ -35,8 +35,8 @@ func TestFloat64ObserverOptions(t *testing.T) {
 	got := NewFloat64ObserverConfig(
 		WithDescription(desc),
 		WithUnit(uBytes),
-		WithFloat64Callback(func(ctx context.Context, o Float64Observer) error {
-			o.Observe(ctx, token)
+		WithFloat64Callback(func(ctx context.Context, obsrv Float64Observer) error {
+			obsrv.Observe(token)
 			return nil
 		}),
 	)
@@ -57,6 +57,6 @@ type float64Observer struct {
 	got float64
 }
 
-func (o *float64Observer) Observe(_ context.Context, v float64, _ ...attribute.KeyValue) {
+func (o *float64Observer) Observe(v float64, _ ...attribute.KeyValue) {
 	o.got = v
 }

metric/instrument/asyncint64.go

@@ -21,46 +21,51 @@ import (
 	"go.opentelemetry.io/otel/metric/unit"
 )
 
-// Int64Observer is a recorder of int64 measurement values.
+// Int64Observable describes a set of instruments used asynchronously to record
+// int64 measurements once per collection cycle. Observations of these
+// instruments are only made within a callback.
 //
 // Warning: methods may be added to this interface in minor releases.
-type Int64Observer interface {
+type Int64Observable interface {
 	Asynchronous
 
-	// Observe records the measurement value for a set of attributes.
-	//
-	// It is only valid to call this within a callback. If called outside of
-	// the registered callback it should have no effect on the instrument, and
-	// an error will be reported via the error handler.
-	Observe(ctx context.Context, value int64, attributes ...attribute.KeyValue)
+	int64Observable()
 }
 
 // Int64ObservableCounter is an instrument used to asynchronously record
-// increasing int64 measurements once per a measurement collection cycle. The
-// Observe method is used to record the measured state of the instrument when
-// it is called. Implementations will assume the observed value to be the
-// cumulative sum of the count.
+// increasing int64 measurements once per collection cycle. Observations are
+// only made within a callback for this instrument. The value observed is
+// assumed the to be the cumulative sum of the count.
 //
 // Warning: methods may be added to this interface in minor releases.
-type Int64ObservableCounter interface{ Int64Observer }
+type Int64ObservableCounter interface{ Int64Observable }
 
 // Int64ObservableUpDownCounter is an instrument used to asynchronously record
-// int64 measurements once per a measurement collection cycle. The Observe
-// method is used to record the measured state of the instrument when it is
-// called. Implementations will assume the observed value to be the cumulative
-// sum of the count.
+// int64 measurements once per collection cycle. Observations are only made
+// within a callback for this instrument. The value observed is assumed the to
+// be the cumulative sum of the count.
 //
 // Warning: methods may be added to this interface in minor releases.
-type Int64ObservableUpDownCounter interface{ Int64Observer }
+type Int64ObservableUpDownCounter interface{ Int64Observable }
 
 // Int64ObservableGauge is an instrument used to asynchronously record
-// instantaneous int64 measurements once per a measurement collection cycle.
+// instantaneous int64 measurements once per collection cycle. Observations are
+// only made within a callback for this instrument.
+//
+// Warning: methods may be added to this interface in minor releases.
+type Int64ObservableGauge interface{ Int64Observable }
+
+// Int64Observer is a recorder of int64 measurements.
 //
 // Warning: methods may be added to this interface in minor releases.
-type Int64ObservableGauge interface{ Int64Observer }
+type Int64Observer interface {
+	Observe(value int64, attributes ...attribute.KeyValue)
+}
 
 // Int64Callback is a function registered with a Meter that makes
-// observations for an Int64Observer it is registered with.
+// observations for a Int64Observerable instrument it is registered with.
+// Calls to the Int64Observer record measurement values for the
+// Int64Observable.
 //
 // The function needs to complete in a finite amount of time and the deadline
 // of the passed context is expected to be honored.

metric/instrument/asyncint64_test.go

@@ -35,8 +35,8 @@ func TestInt64ObserverOptions(t *testing.T) {
 	got := NewInt64ObserverConfig(
 		WithDescription(desc),
 		WithUnit(uBytes),
-		WithInt64Callback(func(ctx context.Context, o Int64Observer) error {
-			o.Observe(ctx, token)
+		WithInt64Callback(func(_ context.Context, obsrv Int64Observer) error {
+			obsrv.Observe(token)
 			return nil
 		}),
 	)
@@ -57,6 +57,6 @@ type int64Observer struct {
 	got int64
 }
 
-func (o *int64Observer) Observe(_ context.Context, v int64, _ ...attribute.KeyValue) {
+func (o *int64Observer) Observe(v int64, _ ...attribute.KeyValue) {
 	o.got = v
 }

metric/internal/global/instruments.go

@@ -30,12 +30,12 @@ type unwrapper interface {
 }
 
 type afCounter struct {
+	instrument.Float64Observable
+
 	name string
 	opts []instrument.Float64ObserverOption
 
 	delegate atomic.Value //instrument.Float64ObservableCounter
-
-	instrument.Asynchronous
 }
 
 var _ unwrapper = (*afCounter)(nil)
@@ -50,12 +50,6 @@ func (i *afCounter) setDelegate(m metric.Meter) {
 	i.delegate.Store(ctr)
 }
 
-func (i *afCounter) Observe(ctx context.Context, x float64, attrs ...attribute.KeyValue) {
-	if ctr := i.delegate.Load(); ctr != nil {
-		ctr.(instrument.Float64ObservableCounter).Observe(ctx, x, attrs...)
-	}
-}
-
 func (i *afCounter) Unwrap() instrument.Asynchronous {
 	if ctr := i.delegate.Load(); ctr != nil {
 		return ctr.(instrument.Float64ObservableCounter)
@@ -64,12 +58,12 @@ func (i *afCounter) Unwrap() instrument.Asynchronous {
 }
 
 type afUpDownCounter struct {
+	instrument.Float64Observable
+
 	name string
 	opts []instrument.Float64ObserverOption
 
 	delegate atomic.Value //instrument.Float64ObservableUpDownCounter
-
-	instrument.Asynchronous
 }
 
 var _ unwrapper = (*afUpDownCounter)(nil)
@@ -84,12 +78,6 @@ func (i *afUpDownCounter) setDelegate(m metric.Meter) {
 	i.delegate.Store(ctr)
 }
 
-func (i *afUpDownCounter) Observe(ctx context.Context, x float64, attrs ...attribute.KeyValue) {
-	if ctr := i.delegate.Load(); ctr != nil {
-		ctr.(instrument.Float64ObservableUpDownCounter).Observe(ctx, x, attrs...)
-	}
-}
-
 func (i *afUpDownCounter) Unwrap() instrument.Asynchronous {
 	if ctr := i.delegate.Load(); ctr != nil {
 		return ctr.(instrument.Float64ObservableUpDownCounter)
@@ -98,14 +86,17 @@ func (i *afUpDownCounter) Unwrap() instrument.Asynchronous {
 }
 
 type afGauge struct {
+	instrument.Float64Observable
+
 	name string
 	opts []instrument.Float64ObserverOption
 
 	delegate atomic.Value //instrument.Float64ObservableGauge
-
-	instrument.Asynchronous
 }
 
+var _ unwrapper = (*afGauge)(nil)
+var _ instrument.Float64ObservableGauge = (*afGauge)(nil)
+
 func (i *afGauge) setDelegate(m metric.Meter) {
 	ctr, err := m.Float64ObservableGauge(i.name, i.opts...)
 	if err != nil {
@@ -115,15 +106,6 @@ func (i *afGauge) setDelegate(m metric.Meter) {
 	i.delegate.Store(ctr)
 }
 
-var _ unwrapper = (*afGauge)(nil)
-var _ instrument.Float64ObservableGauge = (*afGauge)(nil)
-
-func (i *afGauge) Observe(ctx context.Context, x float64, attrs ...attribute.KeyValue) {
-	if ctr := i.delegate.Load(); ctr != nil {
-		ctr.(instrument.Float64ObservableGauge).Observe(ctx, x, attrs...)
-	}
-}
-
 func (i *afGauge) Unwrap() instrument.Asynchronous {
 	if ctr := i.delegate.Load(); ctr != nil {
 		return ctr.(instrument.Float64ObservableGauge)
@@ -132,12 +114,12 @@ func (i *afGauge) Unwrap() instrument.Asynchronous {
 }
 
 type aiCounter struct {
+	instrument.Int64Observable
+
 	name string
 	opts []instrument.Int64ObserverOption
 
 	delegate atomic.Value //instrument.Int64ObservableCounter
-
-	instrument.Asynchronous
 }
 
 var _ unwrapper = (*aiCounter)(nil)
@@ -152,12 +134,6 @@ func (i *aiCounter) setDelegate(m metric.Meter) {
 	i.delegate.Store(ctr)
 }
 
-func (i *aiCounter) Observe(ctx context.Context, x int64, attrs ...attribute.KeyValue) {
-	if ctr := i.delegate.Load(); ctr != nil {
-		ctr.(instrument.Int64ObservableCounter).Observe(ctx, x, attrs...)
-	}
-}
-
 func (i *aiCounter) Unwrap() instrument.Asynchronous {
 	if ctr := i.delegate.Load(); ctr != nil {
 		return ctr.(instrument.Int64ObservableCounter)
@@ -166,12 +142,12 @@ func (i *aiCounter) Unwrap() instrument.Asynchronous {
 }
 
 type aiUpDownCounter struct {
+	instrument.Int64Observable
+
 	name string
 	opts []instrument.Int64ObserverOption
 
 	delegate atomic.Value //instrument.Int64ObservableUpDownCounter
-
-	instrument.Asynchronous
 }
 
 var _ unwrapper = (*aiUpDownCounter)(nil)
@@ -186,12 +162,6 @@ func (i *aiUpDownCounter) setDelegate(m metric.Meter) {
 	i.delegate.Store(ctr)
 }
 
-func (i *aiUpDownCounter) Observe(ctx context.Context, x int64, attrs ...attribute.KeyValue) {
-	if ctr := i.delegate.Load(); ctr != nil {
-		ctr.(instrument.Int64ObservableUpDownCounter).Observe(ctx, x, attrs...)
-	}
-}
-
 func (i *aiUpDownCounter) Unwrap() instrument.Asynchronous {
 	if ctr := i.delegate.Load(); ctr != nil {
 		return ctr.(instrument.Int64ObservableUpDownCounter)
@@ -200,12 +170,12 @@ func (i *aiUpDownCounter) Unwrap() instrument.Asynchronous {
 }
 
 type aiGauge struct {
+	instrument.Int64Observable
+
 	name string
 	opts []instrument.Int64ObserverOption
 
 	delegate atomic.Value //instrument.Int64ObservableGauge
-
-	instrument.Asynchronous
 }
 
 var _ unwrapper = (*aiGauge)(nil)
@@ -220,12 +190,6 @@ func (i *aiGauge) setDelegate(m metric.Meter) {
 	i.delegate.Store(ctr)
 }
 
-func (i *aiGauge) Observe(ctx context.Context, x int64, attrs ...attribute.KeyValue) {
-	if ctr := i.delegate.Load(); ctr != nil {
-		ctr.(instrument.Int64ObservableGauge).Observe(ctx, x, attrs...)
-	}
-}
-
 func (i *aiGauge) Unwrap() instrument.Asynchronous {
 	if ctr := i.delegate.Load(); ctr != nil {
 		return ctr.(instrument.Int64ObservableGauge)