[exporterhelper] Add pkg.exporterhelper.queueBatchEnabled feature gate (#15690)

jmacd · Copilot · mx-psi · web-flow · commit b4efd266ecb5 · 2026-08-04T14:57:37.000Z
#### Description Adds a new feature gate for batching by default in exporterhelper. Updates the RFC and timeline, we are not ready to transition to Phase 2 on the stated schedule. #### Link to tracking issue Part of #14038 Fixes #13582 Part of #12022 #### Testing ✅ #### Documentation ✅ #### Authorship - [x] I, a human, wrote this pull request description myself. Assisted-by: Claude Opus 5 --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: Pablo Baeyens <pablo.baeyens@datadoghq.com> Co-authored-by: Evan Bradley <11745660+evan-bradley@users.noreply.github.com>
diff --git a/.chloggen/exporterhelper-queue-batch-gate.yaml b/.chloggen/exporterhelper-queue-batch-gate.yaml
@@ -0,0 +1,13 @@
+change_type: enhancement
+
+component: pkg/exporterhelper
+
+note: Add the `pkg.exporterhelper.queueBatchEnabled` feature gate
+
+issues: [14038, 13582, 12022]
+
+subtext: |
+  When enabled, the batch settings returned by `NewDefaultQueueConfig()` have
+  `batch::enabled` true. See [migration RFC](https://github.com/open-telemetry/opentelemetry-collector/blob/main/docs/rfcs/batching-migration.md#phase-1).
+
+change_logs: [user]
diff --git a/docs/rfcs/batching-migration.md b/docs/rfcs/batching-migration.md
@@ -177,44 +177,37 @@ the components, evaluating for every exporter whether a `Default` or
 `None` should become `Some` in each exporter's default queue config.
 
 A feature flag for this change will be defined,
-`exporterhelper.exporterQueueBatchEnabled`.
+`pkg.exporterhelper.queueBatchEnabled`.
 
 #### Recommended final default queue configuration
 
 The `NewDefaultQueueConfig` function will begin being influenced by
-the `exporterhelper.exporterQueueBatchEnabled` feature flag. Only the
+the `pkg.exporterhelper.queueBatchEnabled` feature flag. Only the
 `Batch` field's default changes; `BlockOnOverflow` and `WaitForResult`
 remain `false`.
 
 ```go
 func NewDefaultQueueConfig() queuebatch.Config {
+    batchCfg := queuebatch.BatchConfig{
+        FlushTimeout: 200 * time.Millisecond,
+        Sizer:        request.SizerTypeItems,
+        MinSize:      8192,
+    }
+	var batch configoptional.Optional[queuebatch.BatchConfig]
+    if metadata.PkgExporterhelperQueueBatchEnabledFeatureGate.IsEnabled() {
+        // CHANGED: Batching enabled by default under the feature gate.
+        batch = configoptional.Some(batchCfg)
+    } else {
+        batch = configoptional.Default(batchCfg)
+    }
     return queuebatch.Config{
         Sizer:           request.SizerTypeRequests,
         NumConsumers:    10,
         QueueSize:       1_000,
         BlockOnOverflow: false,
         WaitForResult:   false,
-        Batch: configoptional.DefaultOrSome(
-            // CHANGED: Batching is becoming enabled by default.
-            exporterQueueBatchEnabled.IsEnabled(),
-            queuebatch.BatchConfig{
-                FlushTimeout: 200 * time.Millisecond,
-                Sizer:        request.SizerTypeItems,
-                MinSize:      8192,
-            }),
-    }
-}
-```
-
-The above makes use of an hypothetical `configoptional` helper:
-
-```
-// DefaultOrSome ties a feature flag to a default-to-some transition.
-func DefaultOrSome[T any](feature bool, value T) Optional[T] {
-    if feature {
-        return Some(value)
+        Batch:           batch,
     }
-    return Default(value)
 }
 ```
 
@@ -279,13 +272,13 @@ The sequence of events is ordered in phases.  The following table
 summarizes what an operator running a typical pipeline observes at
 each phase:
 
-| Phase | `batchprocessor` in config                                   | exporterhelper defaults                                                    | Net behavior                                                                                                                                                               | Release version  |
-|-------|--------------------------------------------------------------|----------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------|
-| <1    | OK                                                           | `batch::enabled: false`                                                    | Documented behavior                                                                                                                                                        |               |
-| 1     | OK                                                           | Unchanged; feature gate is Alpha (default off)                             | No change for users; new `queuebatchprocessor` and docs available for opt-in migration.                                                                                    |               |
-| 2     | Works, prints deprecation warning pointing to migration docs | Unchanged; gate still Alpha/off                                            | Users see warnings and have at least six releases to migrate; Helm chart switches to the new path while `batchprocessor` still works. Exit gated on early-adopter success. | v0.158.0    |
-| 3     | Removed from default distribution; still available to custom builds. Pipelines using the removed component in the default binary fail to start. | Gate Beta (default on): `batch::enabled: true`                             | Pipelines that didn't migrate fail fast; exporters batch by default; users can still opt out via gate for six releases.                                                    | v0.164.0  |
-| 4     | n/a                                                          | Gate Stable and removed; new default permanent                             | Users choose `exporterhelper` or `queuebatchprocessor` for batching                                                                                                        | v0.170.0 |
+| Phase | `batchprocessor` in config                                                                                                                      | exporterhelper defaults                        | Net behavior                                                                                                                                                               | Release version |
+|-------|-------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------|
+| <1    | OK                                                                                                                                              | `batch::enabled: false`                        | Documented behavior                                                                                                                                                        |                 |
+| 1     | OK                                                                                                                                              | Unchanged; feature gate is Alpha (default off) | No change for users; new `queuebatchprocessor` and docs available for opt-in migration.                                                                                    | v0.158.0+       |
+| 2     | Works, prints deprecation warning pointing to migration docs                                                                                    | Unchanged; gate still Alpha/off                | Users see warnings and have at least six releases to migrate; Helm chart switches to the new path while `batchprocessor` still works. Exit gated on early-adopter success. | v0.160.0        |
+| 3     | Removed from default distribution; still available to custom builds. Pipelines using the removed component in the default binary fail to start. | Gate Beta (default on): `batch::enabled: true` | Pipelines that didn't migrate fail fast; exporters batch by default; users can still opt out via gate for six releases.                                                    | v0.166.0        |
+| 4     | n/a                                                                                                                                             | Gate Stable and removed; new default permanent | Users choose `exporterhelper` or `queuebatchprocessor` for batching                                                                                                        | v0.172.0        |
 
 ### Phase 1
 
@@ -297,13 +290,12 @@ These are loosely dependent,
    config omits `queue_sender` or sets it to a non-standard value.
    Exporters that legitimately need different defaults (e.g., pull-based
    exporters) must declare the opt-out in their `metadata.yaml`.
-2. Introduce the `exporterhelper.exporterQueueBatchEnabled` feature
-   gate at **Alpha** stability (default off).
+2. Introduce the `pkg.exporterhelper.queueBatchEnabled` feature
+   gate at Alpha stability. [#15690](https://github.com/open-telemetry/opentelemetry-collector/pull/15690)
 3. Support a configurable metrics prefix to distinguish processor
    batching from exporter batching
    ([#14038](https://github.com/open-telemetry/opentelemetry-collector/issues/14038)).
-4. Implement `queuebatchprocessor`
-   ([#13583](https://github.com/open-telemetry/opentelemetry-collector/pull/13583)).
+4. Implement `queuebatchprocessor`. [#15500](https://github.com/open-telemetry/opentelemetry-collector/pull/15500)
 5. Detect pipelines that combine `batchprocessor` with an
    exporterhelper that has batching enabled, and emit a startup warning
    identifying the affected pipeline and exporter. This protects users
@@ -317,10 +309,14 @@ These are loosely dependent,
    documentation. Create a blog post about what's happening to
    `batchprocessor`, get it approved.
 
+#### Exit criteria for Phase 1
+
+All of the above must be completed.
+
 ### Phase 2
 
 7. Deprecate `batchprocessor`. Release the blog post. The first
-   release where this lands is tentatively **v0.158.0** (August 2026).
+   release where this lands is tentatively **v0.160.0** (September 2026).
 8. Full audit of exporters and default settings. Exporters can opt-in
    to the migration here by electing `Some` instead of `Default` or
    `None`. Exporters that do not want default blocking/batching will
diff --git a/exporter/exporterhelper/documentation.md b/exporter/exporterhelper/documentation.md
@@ -141,3 +141,13 @@ Number of spans successfully sent to destination.
 | Unit | Metric Type | Value Type | Monotonic | Stability |
 | ---- | ----------- | ---------- | --------- | --------- |
 | {span} | Sum | Int | true | Alpha |
+
+## Feature Gates
+
+This component has the following feature gates:
+
+| Feature Gate | Stage | Description | From Version | To Version | Reference |
+| ------------ | ----- | ----------- | ------------ | ---------- | --------- |
+| `pkg.exporterhelper.queueBatchEnabled` | alpha | Enables exporterhelper batching by default in NewDefaultQueueConfig, as described in the batching migration RFC. | v0.158.0 | N/A | [Link](https://github.com/open-telemetry/opentelemetry-collector/issues/15047) |
+
+For more information about feature gates, see the [Feature Gates](https://github.com/open-telemetry/opentelemetry-collector/blob/main/featuregate/README.md) documentation.
diff --git a/exporter/exporterhelper/go.mod b/exporter/exporterhelper/go.mod
@@ -19,6 +19,7 @@ require (
 	go.opentelemetry.io/collector/exporter/exportertest v0.158.0
 	go.opentelemetry.io/collector/extension/extensiontest v0.158.0
 	go.opentelemetry.io/collector/extension/xextension v0.158.0
+	go.opentelemetry.io/collector/featuregate v1.64.0
 	go.opentelemetry.io/collector/internal/testutil v0.158.0
 	go.opentelemetry.io/collector/pdata v1.64.0
 	go.opentelemetry.io/collector/pdata/pprofile v0.158.0
@@ -60,7 +61,6 @@ require (
 	go.opentelemetry.io/collector/consumer/xconsumer v0.158.0 // indirect
 	go.opentelemetry.io/collector/exporter/xexporter v0.158.0 // indirect
 	go.opentelemetry.io/collector/extension v1.64.0 // indirect
-	go.opentelemetry.io/collector/featuregate v1.64.0 // indirect
 	go.opentelemetry.io/collector/internal/componentalias v0.158.0 // indirect
 	go.opentelemetry.io/collector/receiver v1.64.0 // indirect
 	go.opentelemetry.io/collector/receiver/receivertest v0.158.0 // indirect
diff --git a/exporter/exporterhelper/internal/metadata/generated_feature_gates.go b/exporter/exporterhelper/internal/metadata/generated_feature_gates.go
diff --git a/exporter/exporterhelper/internal/queue_sender.go b/exporter/exporterhelper/internal/queue_sender.go
@@ -10,6 +10,7 @@ import (
 	"go.uber.org/zap"
 
 	"go.opentelemetry.io/collector/config/configoptional"
+	"go.opentelemetry.io/collector/exporter/exporterhelper/internal/metadata"
 	"go.opentelemetry.io/collector/exporter/exporterhelper/internal/queuebatch"
 	"go.opentelemetry.io/collector/exporter/exporterhelper/internal/request"
 	"go.opentelemetry.io/collector/exporter/exporterhelper/internal/sender"
@@ -22,17 +23,28 @@ import (
 // - is non-blocking when full
 // - concurrent exports limited to 10
 // - emits batches of 8192 items, timeout 200ms
+//
+// Batching is disabled by default, unless the
+// pkg.exporterhelper.queueBatchEnabled feature gate is enabled. See
+// https://github.com/open-telemetry/opentelemetry-collector/blob/main/docs/rfcs/batching-migration.md.
 func NewDefaultQueueConfig() queuebatch.Config {
+	batchCfg := queuebatch.BatchConfig{
+		FlushTimeout: 200 * time.Millisecond,
+		Sizer:        request.SizerTypeItems,
+		MinSize:      8192,
+	}
+	var batch configoptional.Optional[queuebatch.BatchConfig]
+	if metadata.PkgExporterhelperQueueBatchEnabledFeatureGate.IsEnabled() {
+		batch = configoptional.Some(batchCfg)
+	} else {
+		batch = configoptional.Default(batchCfg)
+	}
 	return queuebatch.Config{
 		Sizer:           request.SizerTypeRequests,
 		NumConsumers:    10,
 		QueueSize:       1_000,
 		BlockOnOverflow: false,
-		Batch: configoptional.Default(queuebatch.BatchConfig{
-			FlushTimeout: 200 * time.Millisecond,
-			Sizer:        request.SizerTypeItems,
-			MinSize:      8192,
-		}),
+		Batch:           batch,
 	}
 }
 
diff --git a/exporter/exporterhelper/internal/queue_sender_test.go b/exporter/exporterhelper/internal/queue_sender_test.go
@@ -7,6 +7,7 @@ import (
 	"context"
 	"errors"
 	"testing"
+	"time"
 
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
@@ -16,11 +17,13 @@ import (
 	"go.opentelemetry.io/collector/component"
 	"go.opentelemetry.io/collector/component/componenttest"
 	"go.opentelemetry.io/collector/config/configoptional"
+	"go.opentelemetry.io/collector/exporter/exporterhelper/internal/metadata"
 	"go.opentelemetry.io/collector/exporter/exporterhelper/internal/queuebatch"
 	"go.opentelemetry.io/collector/exporter/exporterhelper/internal/request"
 	"go.opentelemetry.io/collector/exporter/exporterhelper/internal/requesttest"
 	"go.opentelemetry.io/collector/exporter/exporterhelper/internal/sender"
 	"go.opentelemetry.io/collector/exporter/exportertest"
+	"go.opentelemetry.io/collector/featuregate"
 	"go.opentelemetry.io/collector/pipeline"
 )
 
@@ -45,6 +48,24 @@ func TestNewQueueSenderFailedRequestDropped(t *testing.T) {
 	assert.Equal(t, "Exporting failed. Dropping data.", observed.All()[0].Message)
 }
 
+func TestNewDefaultQueueConfigBatchFeatureGate(t *testing.T) {
+	// The batch config is present but not enabled by default.
+	qCfg := NewDefaultQueueConfig()
+	require.False(t, qCfg.Batch.HasValue())
+	require.Equal(t, int64(8192), qCfg.Batch.GetOrInsertDefault().MinSize)
+
+	require.NoError(t, featuregate.GlobalRegistry().Set(metadata.PkgExporterhelperQueueBatchEnabledFeatureGate.ID(), true))
+	defer func() {
+		require.NoError(t, featuregate.GlobalRegistry().Set(metadata.PkgExporterhelperQueueBatchEnabledFeatureGate.ID(), false))
+	}()
+
+	qCfg = NewDefaultQueueConfig()
+	require.True(t, qCfg.Batch.HasValue())
+	require.Equal(t, int64(8192), qCfg.Batch.Get().MinSize)
+	require.Equal(t, 200*time.Millisecond, qCfg.Batch.Get().FlushTimeout)
+	require.Equal(t, request.SizerTypeItems, qCfg.Batch.Get().Sizer)
+}
+
 func TestQueueConfig_Validate(t *testing.T) {
 	qCfg := NewDefaultQueueConfig()
 	require.NoError(t, qCfg.Validate())
diff --git a/exporter/exporterhelper/metadata.yaml b/exporter/exporterhelper/metadata.yaml
@@ -11,6 +11,13 @@ status:
   stability:
     beta: [traces, metrics, logs]
 
+feature_gates:
+  - id: pkg.exporterhelper.queueBatchEnabled
+    description: "Enables exporterhelper batching by default in NewDefaultQueueConfig, as described in the batching migration RFC."
+    stage: alpha
+    from_version: 'v0.158.0'
+    reference_url: 'https://github.com/open-telemetry/opentelemetry-collector/issues/15047'
+
 telemetry:
   metrics:
     exporter_enqueue_failed_log_records:
