[xconsumererror]: Add Partial error type

.chloggen/partial_error.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: enhancement
+
+# The name of the component, or a single word describing the area of concern, (e.g. otlpreceiver)
+component: consumer/consumererror/xconsumererror
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Add new Partial error, allowing consumers to express a permanent error with a failed item count.
+
+# One or more tracking issues or pull requests related to the change
+issues: [13423]
+
+# (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: [api]

.github/CODEOWNERS

@@ -25,6 +25,17 @@ cmd/mdatagen/internal/samplefactoryreceiver/ @open-telemetry/collector-approvers
 cmd/mdatagen/internal/sampleprocessor/       @open-telemetry/collector-approvers
 cmd/mdatagen/internal/samplereceiver/        @open-telemetry/collector-approvers @dmitryax
 cmd/mdatagen/internal/samplescraper/         @open-telemetry/collector-approvers @dmitryax
+config/configauth/                           @open-telemetry/collector-approvers
+config/configcompression/                    @open-telemetry/collector-approvers
+config/configgrpc/                           @open-telemetry/collector-approvers
+config/confighttp/                           @open-telemetry/collector-approvers
+config/configmiddleware/                     @open-telemetry/collector-approvers
+config/confignet/                            @open-telemetry/collector-approvers
+config/configopaque/                         @open-telemetry/collector-approvers
+config/configoptional/                       @open-telemetry/collector-approvers
+config/configretry/                          @open-telemetry/collector-approvers
+config/configtelemetry/                      @open-telemetry/collector-approvers
+config/configtls/                            @open-telemetry/collector-approvers
 confmap/                                     @open-telemetry/collector-approvers @mx-psi @evan-bradley
 confmap/provider/envprovider/                @open-telemetry/collector-approvers
 confmap/provider/fileprovider/               @open-telemetry/collector-approvers

.github/ISSUE_TEMPLATE/bug_report.yaml

@@ -25,6 +25,17 @@ body:
       - cmd/mdatagen/internal/sampleprocessor
       - cmd/mdatagen/internal/samplereceiver
       - cmd/mdatagen/internal/samplescraper
+      - config/configauth
+      - config/configcompression
+      - config/configgrpc
+      - config/confighttp
+      - config/configmiddleware
+      - config/confignet
+      - config/configopaque
+      - config/configoptional
+      - config/configretry
+      - config/configtelemetry
+      - config/configtls
       - confmap
       - confmap/provider/envprovider
       - confmap/provider/fileprovider

.github/ISSUE_TEMPLATE/feature_request.yaml

@@ -19,6 +19,17 @@ body:
       - cmd/mdatagen/internal/sampleprocessor
       - cmd/mdatagen/internal/samplereceiver
       - cmd/mdatagen/internal/samplescraper
+      - config/configauth
+      - config/configcompression
+      - config/configgrpc
+      - config/confighttp
+      - config/configmiddleware
+      - config/confignet
+      - config/configopaque
+      - config/configoptional
+      - config/configretry
+      - config/configtelemetry
+      - config/configtls
       - confmap
       - confmap/provider/envprovider
       - confmap/provider/fileprovider

.github/ISSUE_TEMPLATE/other.yaml

@@ -18,6 +18,17 @@ body:
       - cmd/mdatagen/internal/sampleprocessor
       - cmd/mdatagen/internal/samplereceiver
       - cmd/mdatagen/internal/samplescraper
+      - config/configauth
+      - config/configcompression
+      - config/configgrpc
+      - config/confighttp
+      - config/configmiddleware
+      - config/confignet
+      - config/configopaque
+      - config/configoptional
+      - config/configretry
+      - config/configtelemetry
+      - config/configtls
       - confmap
       - confmap/provider/envprovider
       - confmap/provider/fileprovider

consumer/consumererror/xconsumererror/go.mod

@@ -19,6 +19,10 @@ require (
 	go.opentelemetry.io/collector/featuregate v1.45.0 // indirect
 	go.opentelemetry.io/collector/pdata v1.45.0 // indirect
 	go.uber.org/multierr v1.11.0 // indirect
+	golang.org/x/sys v0.34.0 // indirect
+	google.golang.org/genproto/googleapis/rpc v0.0.0-20250804133106-a7a43d27e69b // indirect
+	google.golang.org/grpc v1.76.0 // indirect
+	google.golang.org/protobuf v1.36.10 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 )
 

consumer/consumererror/xconsumererror/partial.go

@@ -0,0 +1,56 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+package xconsumererror // import "go.opentelemetry.io/collector/consumer/consumererror/xconsumererror"
+
+import (
+	"errors"
+
+	"go.opentelemetry.io/collector/consumer/consumererror"
+)
+
+type partialError struct {
+	inner  error
+	failed int
+}
+
+var _ error = partialError{}
+
+func (pe partialError) Error() string {
+	return pe.inner.Error()
+}
+
+func (pe partialError) Unwrap() error {
+	return pe.inner
+}
+
+// NewPartial creates a new partial error. This is used to report errors
+// where only a subset of the total items failed to be written, but it
+// is not possible to tell which particular items failed. An example of this
+// would be a backend that can report partial successes, but only communicate
+// the number of failed items without specifying which specific items failed.
+//
+// A partial error wraps a PermanentError; it can be treated as any other permanent
+// error with no changes, meaning that consumers can transition to producing this
+// error when appropriate without breaking any parts of the pipeline that check for
+// permanent errors.
+//
+// In a scenario where the exact items that failed are known and can be retried,
+// it's recommended to use the respective signal error ([consumererror.Logs],
+// [consumererror.Metrics], or [consumererror.Traces]).
+func NewPartial(err error, failed int) error {
+	return consumererror.NewPermanent(partialError{
+		inner:  err,
+		failed: failed,
+	})
+}
+
+// IsPartial checks if an error was wrapped with the NewPartial function,
+// or if it contains one such error in its Unwrap() tree. The results are
+// the count of failed items if the error is a partial error, and a boolean
+// result of whether the error was a partial or not.
+func IsPartial(err error) (int, bool) {
+	var pe partialError
+	ok := errors.As(err, &pe)
+	return pe.failed, ok
+}

consumer/consumererror/xconsumererror/partial_test.go

@@ -0,0 +1,65 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+package xconsumererror_test
+
+import (
+	"errors"
+	"fmt"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+
+	"go.opentelemetry.io/collector/consumer/consumererror"
+	"go.opentelemetry.io/collector/consumer/consumererror/xconsumererror"
+)
+
+func TestPartial(t *testing.T) {
+	internalErr := errors.New("some points failed")
+	err := xconsumererror.NewPartial(internalErr, 5)
+	// The partial error must be wrapped and be able to be
+	// treated as a plain permanent error.
+	require.True(t, consumererror.IsPermanent(err))
+	// The error should be unwrappable to verify the internal
+	// error if necessary.
+	require.ErrorIs(t, err, internalErr)
+	// It must be possible to retrieve the failed items from
+	// the partial error.
+	failed, ok := xconsumererror.IsPartial(err)
+	require.True(t, ok)
+	require.Equal(t, 5, failed)
+}
+
+func ExampleNewPartial() {
+	// Produce a partial error.
+	failedItems := 5
+	consumptionErr := errors.New("some points failed to be written")
+	err := xconsumererror.NewPartial(consumptionErr, failedItems)
+	fmt.Println(err)
+
+	// Output: Permanent error: some points failed to be written
+}
+
+func ExampleIsPartial() {
+	// Produce a partial error.
+	partialErr := xconsumererror.NewPartial(errors.New("some points failed to be written"), 10)
+
+	// IsPartial will return the failed item count, and a boolean
+	// to indicate whether it is a partial error or not.
+	if count, ok := xconsumererror.IsPartial(partialErr); ok {
+		fmt.Println(count)
+	}
+
+	// Output: 10
+}
+
+func ExampleIsPartial_second() {
+	// Produce a partial error.
+	partialErr := xconsumererror.NewPartial(errors.New("some points failed to be written"), 10)
+
+	// Partial errors wrap a Permanent error, so it can simply be treated
+	// as one if the number of failed items isn't important.
+	fmt.Println(consumererror.IsPermanent(partialErr))
+
+	// Output: true
+}