Merge branch 'main' into metrics_batching

Author: dashpole

CONTRIBUTING.md

@@ -1109,6 +1109,68 @@ func TestObservability(t *testing.T) {
 Test order should not affect results.
 Ensure that any global state (e.g. component ID counters) is reset between tests.
 
+### Experimental Features
+
+To support the development of new features in the specification, we use the following patterns to implement in-development features without adding new public artifacts in stable modules.
+
+#### Experimental behavior with no API artifacts
+
+Features that change behavior without changing the API (e.g., exemplar collection, auto-generation of identifiers) are implemented behind a feature gate.
+The implementation resides in an `/internal/x` package and is activated through environment variables with the `OTEL_GO_X_` prefix (e.g., `OTEL_GO_X_OBSERVABILITY`).
+The feature must be documented in a `README.md` file in the `/internal/x` package.
+
+#### Experimental methods on SDK-only interfaces
+
+Features that require new methods on SDK interfaces are defined as a new interface in an experimental module (e.g., `go.opentelemetry.io/otel/sdk/x`).
+The SDK uses type assertions (without importing the unstable package) to check if passing types implement these experimental interfaces.
+The SDK must not depend on the experimental module.
+
+#### Experimental structs, functions, or interfaces
+
+Features that don't need any changes to the existing stable package are implemented in an experimental module (e.g., `go.opentelemetry.io/otel/sdk/x`).
+
+#### Experimental signals and components
+
+New telemetry signals (e.g., Logs before stabilization) and components (e.g. bridges) are hosted in new, unstable modules (e.g., `go.opentelemetry.io/otel/log` before 1.0.0).
+The package should have the final name it will use once stabilized (i.e. not `/x`), and is released at a v0.x.y version to indicate it is not stable.
+Most new components are hosted in [opentelemetry-go-contrib](https://github.com/open-telemetry/opentelemetry-go-contrib).
+
+#### Experimental options for API or SDK functions
+
+Experimental Options functions are implemented in an experimental module (e.g., `go.opentelemetry.io/otel/sdk/x`).
+The return type of the Option function must embed the option's type (e.g. `metric.InstrumentOption`), and have an `Experimental()` method to prevent the API from panicking when the option is used.
+The SDK uses type assertions (without importing the unstable package) to check if passing types implement these experimental interfaces.
+The SDK must not depend on the experimental module.
+
+For example:
+
+```go
+type myOption struct {
+    // Embed the stable option type.
+    metric.InstrumentOption
+    value string
+}
+
+// Experimental prevents the API from panicking when the option is used.
+func (o myOption) Experimental() {}
+
+// The SDK can use type assertions to use this function.
+func (o myOption) Value() string { return o.value }
+
+func WithMyOption(value string) metric.InstrumentOption {
+    return myOption{value: value}
+}
+```
+
+#### Not Supported
+
+The following kinds of experimental features are **not currently supported** on stable interfaces:
+
+- Experimental methods on API interfaces
+- Experimental fields for API or SDK exported structs
+
+In some cases forks or long-lived branches may be used for prototyping these features.
+
 ## Approvers and Maintainers
 
 ### Maintainers

bridge/opentracing/go.mod

@@ -8,7 +8,7 @@ replace go.opentelemetry.io/otel/trace => ../../trace
 
 require (
 	github.com/opentracing-contrib/go-grpc v0.1.2
-	github.com/opentracing-contrib/go-grpc/test v0.0.0-20260320052726-de6f1ccdd147
+	github.com/opentracing-contrib/go-grpc/test v0.0.0-20260404024518-e5db98260807
 	github.com/opentracing/opentracing-go v1.2.0
 	github.com/stretchr/testify v1.11.1
 	go.opentelemetry.io/otel v1.43.0

bridge/opentracing/go.sum

@@ -20,8 +20,8 @@ github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
 github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
 github.com/opentracing-contrib/go-grpc v0.1.2 h1:MP16Ozc59kqqwn1v18aQxpeGZhsBanJ2iurZYaQSZ+g=
 github.com/opentracing-contrib/go-grpc v0.1.2/go.mod h1:glU6rl1Fhfp9aXUHkE36K2mR4ht8vih0ekOVlWKEUHM=
-github.com/opentracing-contrib/go-grpc/test v0.0.0-20260320052726-de6f1ccdd147 h1:MtzxRkCJU9aGlcL4pbcYcr9qSfcfOMkEIvJYiBIxLr4=
-github.com/opentracing-contrib/go-grpc/test v0.0.0-20260320052726-de6f1ccdd147/go.mod h1:gvr3V5Pls/X/wRxvoNuGdDxrHUuTqHHUA1dZJmlAOuo=
+github.com/opentracing-contrib/go-grpc/test v0.0.0-20260404024518-e5db98260807 h1:nOLrhRxnJis0cGL5Iya0l4r50z4syb7HHWfDs1yMS8M=
+github.com/opentracing-contrib/go-grpc/test v0.0.0-20260404024518-e5db98260807/go.mod h1:gvr3V5Pls/X/wRxvoNuGdDxrHUuTqHHUA1dZJmlAOuo=
 github.com/opentracing/opentracing-go v1.2.0 h1:uEJPy/1a5RIPAJ0Ov+OIO8OxWu77jEv+1B0VhjKrZUs=
 github.com/opentracing/opentracing-go v1.2.0/go.mod h1:GxEUsuufX4nBwe+T+Wl9TAgYrxe9dPLANfrWvHYVTgc=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=

log/logger.go

@@ -74,10 +74,17 @@ type LoggerConfig struct {
 	attrs     attribute.Set
 }
 
+type experimentalOption interface {
+	Experimental()
+}
+
 // NewLoggerConfig returns a new [LoggerConfig] with all the options applied.
 func NewLoggerConfig(options ...LoggerOption) LoggerConfig {
 	var c LoggerConfig
 	for _, opt := range options {
+		if _, ok := opt.(experimentalOption); ok {
+			continue
+		}
 		c = opt.applyLogger(c)
 	}
 	return c

log/logger_test.go

@@ -196,3 +196,15 @@ func BenchmarkNewLoggerConfig(b *testing.B) {
 		})
 	}
 }
+
+type testExperimentalOption struct {
+	log.LoggerOption
+}
+
+func (testExperimentalOption) Experimental() {}
+
+func TestExperimentalOptionSafe(t *testing.T) {
+	var opt testExperimentalOption
+
+	assert.NotPanics(t, func() { _ = log.NewLoggerConfig(opt) })
+}

metric/asyncfloat64.go

@@ -51,6 +51,9 @@ type Float64ObservableCounterConfig struct {
 func NewFloat64ObservableCounterConfig(opts ...Float64ObservableCounterOption) Float64ObservableCounterConfig {
 	var config Float64ObservableCounterConfig
 	for _, o := range opts {
+		if _, ok := o.(experimentalOption); ok {
+			continue
+		}
 		config = o.applyFloat64ObservableCounter(config)
 	}
 	return config
@@ -111,6 +114,9 @@ func NewFloat64ObservableUpDownCounterConfig(
 ) Float64ObservableUpDownCounterConfig {
 	var config Float64ObservableUpDownCounterConfig
 	for _, o := range opts {
+		if _, ok := o.(experimentalOption); ok {
+			continue
+		}
 		config = o.applyFloat64ObservableUpDownCounter(config)
 	}
 	return config
@@ -168,6 +174,9 @@ type Float64ObservableGaugeConfig struct {
 func NewFloat64ObservableGaugeConfig(opts ...Float64ObservableGaugeOption) Float64ObservableGaugeConfig {
 	var config Float64ObservableGaugeConfig
 	for _, o := range opts {
+		if _, ok := o.(experimentalOption); ok {
+			continue
+		}
 		config = o.applyFloat64ObservableGauge(config)
 	}
 	return config

metric/asyncint64.go

@@ -50,6 +50,9 @@ type Int64ObservableCounterConfig struct {
 func NewInt64ObservableCounterConfig(opts ...Int64ObservableCounterOption) Int64ObservableCounterConfig {
 	var config Int64ObservableCounterConfig
 	for _, o := range opts {
+		if _, ok := o.(experimentalOption); ok {
+			continue
+		}
 		config = o.applyInt64ObservableCounter(config)
 	}
 	return config
@@ -110,6 +113,9 @@ func NewInt64ObservableUpDownCounterConfig(
 ) Int64ObservableUpDownCounterConfig {
 	var config Int64ObservableUpDownCounterConfig
 	for _, o := range opts {
+		if _, ok := o.(experimentalOption); ok {
+			continue
+		}
 		config = o.applyInt64ObservableUpDownCounter(config)
 	}
 	return config
@@ -167,6 +173,9 @@ type Int64ObservableGaugeConfig struct {
 func NewInt64ObservableGaugeConfig(opts ...Int64ObservableGaugeOption) Int64ObservableGaugeConfig {
 	var config Int64ObservableGaugeConfig
 	for _, o := range opts {
+		if _, ok := o.(experimentalOption); ok {
+			continue
+		}
 		config = o.applyInt64ObservableGauge(config)
 	}
 	return config

metric/config.go

@@ -42,11 +42,18 @@ type MeterOption interface {
 	applyMeter(MeterConfig) MeterConfig
 }
 
+type experimentalOption interface {
+	Experimental()
+}
+
 // NewMeterConfig creates a new MeterConfig and applies
 // all the given options.
 func NewMeterConfig(opts ...MeterOption) MeterConfig {
 	var config MeterConfig
 	for _, o := range opts {
+		if _, ok := o.(experimentalOption); ok {
+			continue
+		}
 		config = o.applyMeter(config)
 	}
 	return config

metric/config_test.go

@@ -197,3 +197,49 @@ func BenchmarkNewMeterConfig(b *testing.B) {
 		})
 	}
 }
+
+type testExperimentalOption struct {
+	metric.MeterOption
+	metric.Int64CounterOption
+	metric.Int64UpDownCounterOption
+	metric.Int64HistogramOption
+	metric.Int64GaugeOption
+	metric.Float64CounterOption
+	metric.Float64UpDownCounterOption
+	metric.Float64HistogramOption
+	metric.Float64GaugeOption
+	metric.Int64ObservableCounterOption
+	metric.Int64ObservableUpDownCounterOption
+	metric.Int64ObservableGaugeOption
+	metric.Float64ObservableCounterOption
+	metric.Float64ObservableUpDownCounterOption
+	metric.Float64ObservableGaugeOption
+	metric.AddOption
+	metric.RecordOption
+	metric.ObserveOption
+}
+
+func (testExperimentalOption) Experimental() {}
+
+func TestExperimentalOptionSafe(t *testing.T) {
+	var opt testExperimentalOption
+
+	assert.NotPanics(t, func() { _ = metric.NewMeterConfig(opt) })
+	assert.NotPanics(t, func() { _ = metric.NewInt64CounterConfig(opt) })
+	assert.NotPanics(t, func() { _ = metric.NewInt64UpDownCounterConfig(opt) })
+	assert.NotPanics(t, func() { _ = metric.NewInt64HistogramConfig(opt) })
+	assert.NotPanics(t, func() { _ = metric.NewInt64GaugeConfig(opt) })
+	assert.NotPanics(t, func() { _ = metric.NewFloat64CounterConfig(opt) })
+	assert.NotPanics(t, func() { _ = metric.NewFloat64UpDownCounterConfig(opt) })
+	assert.NotPanics(t, func() { _ = metric.NewFloat64HistogramConfig(opt) })
+	assert.NotPanics(t, func() { _ = metric.NewFloat64GaugeConfig(opt) })
+	assert.NotPanics(t, func() { _ = metric.NewInt64ObservableCounterConfig(opt) })
+	assert.NotPanics(t, func() { _ = metric.NewInt64ObservableUpDownCounterConfig(opt) })
+	assert.NotPanics(t, func() { _ = metric.NewInt64ObservableGaugeConfig(opt) })
+	assert.NotPanics(t, func() { _ = metric.NewFloat64ObservableCounterConfig(opt) })
+	assert.NotPanics(t, func() { _ = metric.NewFloat64ObservableUpDownCounterConfig(opt) })
+	assert.NotPanics(t, func() { _ = metric.NewFloat64ObservableGaugeConfig(opt) })
+	assert.NotPanics(t, func() { _ = metric.NewAddConfig([]metric.AddOption{opt}) })
+	assert.NotPanics(t, func() { _ = metric.NewRecordConfig([]metric.RecordOption{opt}) })
+	assert.NotPanics(t, func() { _ = metric.NewObserveConfig([]metric.ObserveOption{opt}) })
+}

metric/instrument.go

@@ -3,7 +3,9 @@
 
 package metric // import "go.opentelemetry.io/otel/metric"
 
-import "go.opentelemetry.io/otel/attribute"
+import (
+	"go.opentelemetry.io/otel/attribute"
+)
 
 // Observable is used as a grouping mechanism for all instruments that are
 // updated within a Callback.
@@ -228,6 +230,9 @@ type AddConfig struct {
 func NewAddConfig(opts []AddOption) AddConfig {
 	config := AddConfig{attrs: *attribute.EmptySet()}
 	for _, o := range opts {
+		if _, ok := o.(experimentalOption); ok {
+			continue
+		}
 		config = o.applyAdd(config)
 	}
 	return config
@@ -253,6 +258,9 @@ type RecordConfig struct {
 func NewRecordConfig(opts []RecordOption) RecordConfig {
 	config := RecordConfig{attrs: *attribute.EmptySet()}
 	for _, o := range opts {
+		if _, ok := o.(experimentalOption); ok {
+			continue
+		}
 		config = o.applyRecord(config)
 	}
 	return config
@@ -278,6 +286,9 @@ type ObserveConfig struct {
 func NewObserveConfig(opts []ObserveOption) ObserveConfig {
 	config := ObserveConfig{attrs: *attribute.EmptySet()}
 	for _, o := range opts {
+		if _, ok := o.(experimentalOption); ok {
+			continue
+		}
 		config = o.applyObserve(config)
 	}
 	return config