sdk/metric: Add experimental Enabled method to synchronous instruments

CHANGELOG.md

@@ -11,6 +11,10 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 ### Added
 
 - Add `Reset` method to `SpanRecorder` in `go.opentelemetry.io/otel/sdk/trace/tracetest`. (#5994)
+- Add `EnabledInstrument` interface in `go.opentelemetry.io/otel/sdk/metric/internal/x`.
+  This is an experimental interface that is implemented by synchronous instruments provided by `go.opentelemetry.io/otel/sdk/metric`.
+  Users can use it to avoid performing computationally expensive operations when recording measurements.
+  It does not fall within the scope of the OpenTelemetry Go versioning and stability [policy](./VERSIONING.md) and it may be changed in backwards incompatible ways or removed in feature releases. (#6016)
 
 ### Changed
 

sdk/metric/instrument.go

@@ -16,6 +16,7 @@ import (
 	"go.opentelemetry.io/otel/metric/embedded"
 	"go.opentelemetry.io/otel/sdk/instrumentation"
 	"go.opentelemetry.io/otel/sdk/metric/internal/aggregate"
+	"go.opentelemetry.io/otel/sdk/metric/internal/x"
 )
 
 var zeroScope instrumentation.Scope
@@ -190,6 +191,7 @@ var (
 	_ metric.Int64UpDownCounter = (*int64Inst)(nil)
 	_ metric.Int64Histogram     = (*int64Inst)(nil)
 	_ metric.Int64Gauge         = (*int64Inst)(nil)
+	_ x.EnabledInstrument       = (*int64Inst)(nil)
 )
 
 func (i *int64Inst) Add(ctx context.Context, val int64, opts ...metric.AddOption) {
@@ -202,6 +204,10 @@ func (i *int64Inst) Record(ctx context.Context, val int64, opts ...metric.Record
 	i.aggregate(ctx, val, c.Attributes())
 }
 
+func (i *int64Inst) Enabled(_ context.Context) bool {
+	return len(i.measures) != 0
+}
+
 func (i *int64Inst) aggregate(ctx context.Context, val int64, s attribute.Set) { // nolint:revive  // okay to shadow pkg with method.
 	for _, in := range i.measures {
 		in(ctx, val, s)
@@ -222,6 +228,7 @@ var (
 	_ metric.Float64UpDownCounter = (*float64Inst)(nil)
 	_ metric.Float64Histogram     = (*float64Inst)(nil)
 	_ metric.Float64Gauge         = (*float64Inst)(nil)
+	_ x.EnabledInstrument         = (*float64Inst)(nil)
 )
 
 func (i *float64Inst) Add(ctx context.Context, val float64, opts ...metric.AddOption) {
@@ -234,6 +241,10 @@ func (i *float64Inst) Record(ctx context.Context, val float64, opts ...metric.Re
 	i.aggregate(ctx, val, c.Attributes())
 }
 
+func (i *float64Inst) Enabled(_ context.Context) bool {
+	return len(i.measures) != 0
+}
+
 func (i *float64Inst) aggregate(ctx context.Context, val float64, s attribute.Set) {
 	for _, in := range i.measures {
 		in(ctx, val, s)

sdk/metric/internal/x/README.md

@@ -10,6 +10,7 @@ See the [Compatibility and Stability](#compatibility-and-stability) section for
 
 - [Cardinality Limit](#cardinality-limit)
 - [Exemplars](#exemplars)
+- [Instrument Enabled](#instrument-enabled)
 
 ### Cardinality Limit
 
@@ -102,6 +103,24 @@ Revert to the default exemplar filter (`"trace_based"`)
 unset OTEL_METRICS_EXEMPLAR_FILTER
 ```
 
+### Instrument Enabled
+
+To help users avoid performing computationally expensive operations when recording measurements, synchronous instruments provide an `Enabled` method.
+
+#### Examples
+
+The following code shows an example of how to check if an instrument implements the `EnabledInstrument` interface before using the `Enabled` function to avoid doing an expensive computation:
+
+```go
+type enabledInstrument interface { Enabled(context.Context) bool }
+
+ctr, err := m.Int64Counter("expensive-counter")
+c, ok := ctr.(enabledInstrument)
+if !ok || c.Enabled(context.Background()) {
+    c.Add(expensiveComputation())
+}
+```
+
 ## Compatibility and Stability
 
 Experimental features do not fall within the scope of the OpenTelemetry Go versioning and stability [policy](../../../../VERSIONING.md).

sdk/metric/internal/x/x.go

@@ -8,6 +8,7 @@
 package x // import "go.opentelemetry.io/otel/sdk/metric/internal/x"
 
 import (
+	"context"
 	"os"
 	"strconv"
 )
@@ -67,3 +68,14 @@ func (f Feature[T]) Enabled() bool {
 	_, ok := f.Lookup()
 	return ok
 }
+
+// EnabledInstrument informs whether the instrument is enabled.
+//
+// EnabledInstrument interface is implemented by synchronous instruments.
+type EnabledInstrument interface {
+	// Enabled returns whether the instrument will process measurements for the given context.
+	//
+	// This function can be used in places where measuring an instrument
+	// would result in computationally expensive operations.
+	Enabled(context.Context) bool
+}

sdk/metric/meter_test.go

@@ -24,6 +24,7 @@ import (
 	"go.opentelemetry.io/otel/metric"
 	"go.opentelemetry.io/otel/sdk/instrumentation"
 	"go.opentelemetry.io/otel/sdk/metric/exemplar"
+	"go.opentelemetry.io/otel/sdk/metric/internal/x"
 	"go.opentelemetry.io/otel/sdk/metric/metricdata"
 	"go.opentelemetry.io/otel/sdk/metric/metricdata/metricdatatest"
 	"go.opentelemetry.io/otel/sdk/resource"
@@ -388,6 +389,9 @@ func TestMeterCreatesInstruments(t *testing.T) {
 				ctr, err := m.Int64Counter("sint")
 				assert.NoError(t, err)
 
+				c, ok := ctr.(x.EnabledInstrument)
+				require.True(t, ok)
+				assert.True(t, c.Enabled(context.Background()))
 				ctr.Add(ctx, 3)
 			},
 			want: metricdata.Metrics{
@@ -407,6 +411,9 @@ func TestMeterCreatesInstruments(t *testing.T) {
 				ctr, err := m.Int64UpDownCounter("sint")
 				assert.NoError(t, err)
 
+				c, ok := ctr.(x.EnabledInstrument)
+				require.True(t, ok)
+				assert.True(t, c.Enabled(context.Background()))
 				ctr.Add(ctx, 11)
 			},
 			want: metricdata.Metrics{
@@ -452,6 +459,9 @@ func TestMeterCreatesInstruments(t *testing.T) {
 				ctr, err := m.Float64Counter("sfloat")
 				assert.NoError(t, err)
 
+				c, ok := ctr.(x.EnabledInstrument)
+				require.True(t, ok)
+				assert.True(t, c.Enabled(context.Background()))
 				ctr.Add(ctx, 3)
 			},
 			want: metricdata.Metrics{
@@ -471,6 +481,9 @@ func TestMeterCreatesInstruments(t *testing.T) {
 				ctr, err := m.Float64UpDownCounter("sfloat")
 				assert.NoError(t, err)
 
+				c, ok := ctr.(x.EnabledInstrument)
+				require.True(t, ok)
+				assert.True(t, c.Enabled(context.Background()))
 				ctr.Add(ctx, 11)
 			},
 			want: metricdata.Metrics{
@@ -532,6 +545,106 @@ func TestMeterCreatesInstruments(t *testing.T) {
 	}
 }
 
+func TestMeterWithDropView(t *testing.T) {
+	testCases := []struct {
+		name string
+		fn   func(*testing.T, metric.Meter)
+	}{
+		{
+			name: "SyncInt64Count",
+			fn: func(t *testing.T, m metric.Meter) {
+				ctr, err := m.Int64Counter("sint")
+				assert.NoError(t, err)
+				c, ok := ctr.(x.EnabledInstrument)
+				require.True(t, ok)
+				assert.False(t, c.Enabled(context.Background()))
+			},
+		},
+		{
+			name: "SyncInt64UpDownCount",
+			fn: func(t *testing.T, m metric.Meter) {
+				ctr, err := m.Int64UpDownCounter("sint")
+				assert.NoError(t, err)
+				c, ok := ctr.(x.EnabledInstrument)
+				require.True(t, ok)
+				assert.False(t, c.Enabled(context.Background()))
+			},
+		},
+		{
+			name: "SyncInt64Gauge",
+			fn: func(t *testing.T, m metric.Meter) {
+				gauge, err := m.Int64Gauge("sint")
+				assert.NoError(t, err)
+				g, ok := gauge.(x.EnabledInstrument)
+				require.True(t, ok)
+				assert.False(t, g.Enabled(context.Background()))
+			},
+		},
+		{
+			name: "SyncInt64Histogram",
+			fn: func(t *testing.T, m metric.Meter) {
+				histo, err := m.Int64Histogram("histogram")
+				assert.NoError(t, err)
+				h, ok := histo.(x.EnabledInstrument)
+				require.True(t, ok)
+				assert.False(t, h.Enabled(context.Background()))
+			},
+		},
+		{
+			name: "SyncFloat64Count",
+			fn: func(t *testing.T, m metric.Meter) {
+				ctr, err := m.Float64Counter("sfloat")
+				assert.NoError(t, err)
+				c, ok := ctr.(x.EnabledInstrument)
+				require.True(t, ok)
+				assert.False(t, c.Enabled(context.Background()))
+			},
+		},
+		{
+			name: "SyncFloat64UpDownCount",
+			fn: func(t *testing.T, m metric.Meter) {
+				ctr, err := m.Float64UpDownCounter("sfloat")
+				assert.NoError(t, err)
+				c, ok := ctr.(x.EnabledInstrument)
+				require.True(t, ok)
+				assert.False(t, c.Enabled(context.Background()))
+			},
+		},
+		{
+			name: "SyncFloat64Gauge",
+			fn: func(t *testing.T, m metric.Meter) {
+				gauge, err := m.Float64Gauge("sfloat")
+				assert.NoError(t, err)
+				g, ok := gauge.(x.EnabledInstrument)
+				require.True(t, ok)
+				assert.False(t, g.Enabled(context.Background()))
+			},
+		},
+		{
+			name: "SyncFloat64Histogram",
+			fn: func(t *testing.T, m metric.Meter) {
+				histo, err := m.Float64Histogram("histogram")
+				assert.NoError(t, err)
+				h, ok := histo.(x.EnabledInstrument)
+				require.True(t, ok)
+				assert.False(t, h.Enabled(context.Background()))
+			},
+		},
+	}
+
+	for _, tt := range testCases {
+		t.Run(tt.name, func(t *testing.T) {
+			rdr := NewManualReader()
+			dropView := NewView(
+				Instrument{Name: "*"},
+				Stream{Aggregation: AggregationDrop{}},
+			)
+			m := NewMeterProvider(WithReader(rdr), WithView(dropView)).Meter("testInstruments")
+			tt.fn(t, m)
+		})
+	}
+}
+
 func TestMeterCreatesInstrumentsValidations(t *testing.T) {
 	testCases := []struct {
 		name string