Deprecate blocking in favor of block_on_overflow

Signed-off-by: Bogdan Drutu <[email protected]>

Author: bogdandrutu

.chloggen/deprecate-blocking.yaml

@@ -0,0 +1,25 @@
+# Use this changelog template to create an entry for release notes.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: deprecation
+
+# The name of the component, or a single word describing the area of concern, (e.g. otlpreceiver)
+component: exporterhelper
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Deprecate `blocking` in favor of `block_on_overflow`.
+
+# One or more tracking issues or pull requests related to the change
+issues: [12710]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext:
+
+# Optional: The change log or logs in which this entry should be included.
+# e.g. '[user]' or '[user, api]'
+# Include 'user' if the change is relevant to end users.
+# Include 'api' if there is a change to a library API.
+# Default: '[user]'
+change_logs: [user]

exporter/exporterhelper/internal/queue_sender.go

@@ -12,6 +12,7 @@ import (
 	"go.uber.org/zap"
 
 	"go.opentelemetry.io/collector/component"
+	"go.opentelemetry.io/collector/confmap"
 	"go.opentelemetry.io/collector/exporter/exporterhelper/internal/queuebatch"
 	"go.opentelemetry.io/collector/exporter/exporterhelper/internal/request"
 	"go.opentelemetry.io/collector/exporter/exporterhelper/internal/sender"
@@ -32,8 +33,8 @@ func NewDefaultQueueConfig() QueueConfig {
 		// By default, batches are 8192 spans, for a total of up to 8 million spans in the queue
 		// This can be estimated at 1-4 GB worth of maximum memory usage
 		// This default is probably still too high, and may be adjusted further down in a future release
-		QueueSize: 1_000,
-		Blocking:  false,
+		QueueSize:       1_000,
+		BlockOnOverflow: false,
 	}
 }
 
@@ -48,12 +49,33 @@ type QueueConfig struct {
 	NumConsumers int `mapstructure:"num_consumers"`
 	// QueueSize is the maximum number of requests allowed in queue at any given time.
 	QueueSize int `mapstructure:"queue_size"`
-	// Blocking controls the queue behavior when full.
-	// If true it blocks until enough space to add the new request to the queue.
+
+	// Deprecated: [v0.123.0] use `block_on_overflow`.
 	Blocking bool `mapstructure:"blocking"`
+
+	// BlockOnOverflow determines the behavior when the component's TotalSize limit is reached.
+	// If true, the component will wait for space; otherwise, operations will immediately return a retryable error.
+	BlockOnOverflow bool `mapstructure:"block_on_overflow"`
+
 	// StorageID if not empty, enables the persistent storage and uses the component specified
 	// as a storage extension for the persistent queue
 	StorageID *component.ID `mapstructure:"storage"`
+
+	hasBlocking bool
+}
+
+func (qCfg *QueueConfig) Unmarshal(conf *confmap.Conf) error {
+	if err := conf.Unmarshal(qCfg); err != nil {
+		return err
+	}
+
+	// If user still uses the old blocking, override and will log error during initialization.
+	if conf.IsSet("blocking") {
+		qCfg.hasBlocking = true
+		qCfg.BlockOnOverflow = qCfg.Blocking
+	}
+
+	return nil
 }
 
 // Validate checks if the Config is valid
@@ -77,6 +99,9 @@ func NewQueueSender(
 	exportFailureMessage string,
 	next sender.Sender[request.Request],
 ) (sender.Sender[request.Request], error) {
+	if qCfg.hasBlocking {
+		qSet.Telemetry.Logger.Error("using deprecated field `blocking`")
+	}
 	exportFunc := func(ctx context.Context, req request.Request) error {
 		// Have to read the number of items before sending the request since the request can
 		// be modified by the downstream components like the batcher.
@@ -99,7 +124,7 @@ func newQueueBatchConfig(qCfg QueueConfig, bCfg BatcherConfig) queuebatch.Config
 		Sizer:           request.SizerTypeRequests,
 		QueueSize:       qCfg.QueueSize,
 		NumConsumers:    qCfg.NumConsumers,
-		BlockOnOverflow: qCfg.Blocking,
+		BlockOnOverflow: qCfg.BlockOnOverflow,
 		StorageID:       qCfg.StorageID,
 	}
 	if bCfg.Enabled {

exporter/exporterhelper/internal/queue_sender_test.go

@@ -15,6 +15,7 @@ import (
 
 	"go.opentelemetry.io/collector/component"
 	"go.opentelemetry.io/collector/component/componenttest"
+	"go.opentelemetry.io/collector/confmap"
 	"go.opentelemetry.io/collector/exporter/exporterhelper/internal/queuebatch"
 	"go.opentelemetry.io/collector/exporter/exporterhelper/internal/request"
 	"go.opentelemetry.io/collector/exporter/exporterhelper/internal/requesttest"
@@ -45,6 +46,21 @@ func TestNewQueueSenderFailedRequestDropped(t *testing.T) {
 	assert.Equal(t, "Exporting failed. Dropping data.", observed.All()[0].Message)
 }
 
+func TestQueueConfig_DeprecatedBlockingUnmarshal(t *testing.T) {
+	conf := confmap.NewFromStringMap(map[string]any{
+		"enabled":       true,
+		"num_consumers": 2,
+		"queue_size":    100,
+		"blocking":      true,
+	})
+
+	qCfg := QueueConfig{}
+	assert.False(t, qCfg.BlockOnOverflow)
+	require.NoError(t, conf.Unmarshal(&qCfg))
+	assert.True(t, qCfg.BlockOnOverflow)
+	assert.True(t, qCfg.hasBlocking)
+}
+
 func TestQueueConfig_Validate(t *testing.T) {
 	qCfg := NewDefaultQueueConfig()
 	require.NoError(t, qCfg.Validate())

exporter/exporterhelper/queue_batch.go

@@ -61,17 +61,7 @@ func WithQueueBatch(cfg QueueBatchConfig, set QueueBatchSettings) Option {
 
 // NewDefaultQueueConfig returns the default config for QueueConfig.
 // By default, the queue stores 1000 items of telemetry and is non-blocking when full.
-func NewDefaultQueueConfig() QueueConfig {
-	return QueueConfig{
-		Enabled:      true,
-		NumConsumers: 10,
-		// By default, batches are 8192 spans, for a total of up to 8 million spans in the queue
-		// This can be estimated at 1-4 GB worth of maximum memory usage
-		// This default is probably still too high, and may be adjusted further down in a future release
-		QueueSize: 1_000,
-		Blocking:  false,
-	}
-}
+var NewDefaultQueueConfig = internal.NewDefaultQueueConfig
 
 // BatcherConfig defines a configuration for batching requests based on a timeout and a minimum number of items.
 // Experimental: This API is at the early stage of development and may change without backward compatibility

exporter/exporterhelper/xexporterhelper/go.mod

@@ -29,15 +29,24 @@ require (
 	github.com/davecgh/go-spew v1.1.1 // indirect
 	github.com/go-logr/logr v1.4.2 // indirect
 	github.com/go-logr/stdr v1.2.2 // indirect
+	github.com/go-viper/mapstructure/v2 v2.2.1 // indirect
 	github.com/gogo/protobuf v1.3.2 // indirect
 	github.com/google/uuid v1.6.0 // indirect
+	github.com/hashicorp/go-version v1.7.0 // indirect
 	github.com/json-iterator/go v1.1.12 // indirect
+	github.com/knadh/koanf/maps v0.1.1 // indirect
+	github.com/knadh/koanf/providers/confmap v0.1.0 // indirect
+	github.com/knadh/koanf/v2 v2.1.2 // indirect
+	github.com/mitchellh/copystructure v1.2.0 // indirect
+	github.com/mitchellh/reflectwalk v1.0.2 // indirect
 	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
 	github.com/modern-go/reflect2 v1.0.2 // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
 	go.opentelemetry.io/auto/sdk v1.1.0 // indirect
+	go.opentelemetry.io/collector/confmap v1.28.1 // indirect
 	go.opentelemetry.io/collector/extension v1.28.1 // indirect
 	go.opentelemetry.io/collector/extension/xextension v0.122.1 // indirect
+	go.opentelemetry.io/collector/featuregate v1.28.1 // indirect
 	go.opentelemetry.io/collector/pdata v1.28.1 // indirect
 	go.opentelemetry.io/collector/pipeline v0.122.1 // indirect
 	go.opentelemetry.io/collector/receiver v1.28.1 // indirect
@@ -98,3 +107,7 @@ replace go.opentelemetry.io/collector/consumer/consumererror => ../../../consume
 replace go.opentelemetry.io/collector/extension/extensiontest => ../../../extension/extensiontest
 
 replace go.opentelemetry.io/collector/extension/xextension => ../../../extension/xextension
+
+replace go.opentelemetry.io/collector/featuregate => ../../../featuregate
+
+replace go.opentelemetry.io/collector/confmap => ../../../confmap

exporter/exporterhelper/xexporterhelper/go.sum

@@ -26,15 +26,24 @@ require (
 	github.com/davecgh/go-spew v1.1.1 // indirect
 	github.com/go-logr/logr v1.4.2 // indirect
 	github.com/go-logr/stdr v1.2.2 // indirect
+	github.com/go-viper/mapstructure/v2 v2.2.1 // indirect
 	github.com/gogo/protobuf v1.3.2 // indirect
+	github.com/hashicorp/go-version v1.7.0 // indirect
 	github.com/json-iterator/go v1.1.12 // indirect
+	github.com/knadh/koanf/maps v0.1.1 // indirect
+	github.com/knadh/koanf/providers/confmap v0.1.0 // indirect
+	github.com/knadh/koanf/v2 v2.1.2 // indirect
+	github.com/mitchellh/copystructure v1.2.0 // indirect
+	github.com/mitchellh/reflectwalk v1.0.2 // indirect
 	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
 	github.com/modern-go/reflect2 v1.0.2 // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
 	go.opentelemetry.io/auto/sdk v1.1.0 // indirect
+	go.opentelemetry.io/collector/confmap v1.28.1 // indirect
 	go.opentelemetry.io/collector/consumer/xconsumer v0.122.1 // indirect
 	go.opentelemetry.io/collector/extension v1.28.1 // indirect
 	go.opentelemetry.io/collector/extension/xextension v0.122.1 // indirect
+	go.opentelemetry.io/collector/featuregate v1.28.1 // indirect
 	go.opentelemetry.io/collector/receiver/xreceiver v0.122.1 // indirect
 	go.opentelemetry.io/otel v1.35.0 // indirect
 	go.opentelemetry.io/otel/metric v1.35.0 // indirect
@@ -88,3 +97,7 @@ replace go.opentelemetry.io/collector/consumer/consumererror => ../../consumer/c
 replace go.opentelemetry.io/collector/extension/extensiontest => ../../extension/extensiontest
 
 replace go.opentelemetry.io/collector/extension/xextension => ../../extension/xextension
+
+replace go.opentelemetry.io/collector/featuregate => ../../featuregate
+
+replace go.opentelemetry.io/collector/confmap => ../../confmap