consumererror

Documentation

Overview

Package consumererror provides wrappers to easily classify errors. This allows appropriate action by error handlers without the need to know each individual error type/instance. These errors are returned by the Consume*() functions of the consumer interfaces.

Error handling

The consumererror package provides a way to classify errors into two categories: Permanent and NonPermanent. The Permanent errors are those that are not expected to be resolved by retrying the same data.

If the error is Permanent, then the Consume*() call should not be retried with the same data. This typically happens when the data cannot be serialized by the exporter that is attached to the pipeline or when the destination refuses the data because it cannot decode it.

If the error is non-Permanent then the Consume*() call should be retried with the same data. This may be done by the component itself, however typically it is done by the original sender, after the receiver in the pipeline returns a response to the sender indicating that the Collector is currently overloaded and the request must be retried.

Index

• func IsDownstream(err error) bool
• func IsPermanent(err error) bool
• func NewDownstream(err error) error
• func NewLogs(err error, data plog.Logs) error
• func NewMetrics(err error, data pmetric.Metrics) error
• func NewOTLPGRPCError(origErr error, status *status.Status) error
• func NewOTLPHTTPError(origErr error, httpStatus int) error
• func NewPermanent(err error) error
• func NewRetryableError(origErr error) error
• func NewTraces(err error, data ptrace.Traces) error
• func ToGRPCStatus(err error) *status.Status
• func ToHTTPStatus(err error) int
• type Error
  • func (e *Error) Error() string
  • func (e *Error) IsRetryable() bool
  • func (e *Error) Unwrap() error
• type Logs
• type Metrics
• type Traces

Functions

func IsDownstream

func IsDownstream(err error) bool

IsDownstream checks if an error was wrapped with the NewDownstream function, or if it contains one such error in its Unwrap() tree.

func IsPermanent

func IsPermanent(err error) bool

IsPermanent checks if an error was wrapped with the NewPermanent function, which is used to indicate that a given error will always be returned in the case that its sources receives the same input.

func NewDownstream

func NewDownstream(err error) error

NewDownstream wraps an error to indicate that it is a downstream error, i.e. an error that does not come from the current component, but from one further downstream. This is used by pipeline instrumentation to determine whether an operation's outcome was an internal failure, or if it successfully produced data that was later refused. This wrapper is not intended to be used manually inside components.

func NewLogs

func NewLogs(err error, data plog.Logs) error

NewLogs creates a Logs that can encapsulate received data that failed to be processed or sent.

func NewMetrics

func NewMetrics(err error, data pmetric.Metrics) error

NewMetrics creates a Metrics that can encapsulate received data that failed to be processed or sent.

func NewOTLPGRPCError

func NewOTLPGRPCError(origErr error, status *status.Status) error

NewOTLPGRPCError records a gRPC status code that was received from a server during data submission.

NOTE: This function will panic if passed a *status.Status with an underlying code of codes.OK. This is to reserve the behavior for handling this code for the future.

func NewOTLPHTTPError

func NewOTLPHTTPError(origErr error, httpStatus int) error

NewOTLPHTTPError records an HTTP status code that was received from a server during data submission.

NOTE: This function will panic if passed an HTTP status between 200 and 299 inclusive. This is to reserve the behavior for handling these codes for the future.

func NewPermanent

func NewPermanent(err error) error

NewPermanent wraps an error to indicate that it is a permanent error, i.e. an error that will be always returned if its source receives the same inputs.

func NewRetryableError

func NewRetryableError(origErr error) error

NewRetryableError records that this error is retryable according to OTLP specification.

func NewTraces

func NewTraces(err error, data ptrace.Traces) error

NewTraces creates a Traces that can encapsulate received data that failed to be processed or sent.

func ToGRPCStatus

func ToGRPCStatus(err error) *status.Status

ToGRPCStatus returns a gRPC status code either directly set by the source on an Error object, derived from an HTTP status code set by the source, or derived from Retryable. When deriving the value, the OTLP specification is used to map to gRPC. See https://github.com/open-telemetry/opentelemetry-proto/blob/main/docs/specification.md for more details.

If an Error object is not present, then we attempt to get a status.Status from the error tree.

If a status.Status cannot be derived from these sources then INTERNAL is returned.

func ToHTTPStatus

func ToHTTPStatus(err error) int

ToHTTPStatus returns an HTTP status code either directly set by the source on an Error object, derived from a gRPC status code set by the source, or derived from Retryable. When deriving the value, the OTLP specification is used to map to HTTP. See https://github.com/open-telemetry/opentelemetry-proto/blob/main/docs/specification.md for more details.

If a http status code cannot be derived from these three sources then 500 is returned.

Types

type Error

type Error struct {
	// contains filtered or unexported fields
}

Error is intended to be used to encapsulate various information that can add context to an error that occurred within a pipeline component. Error objects are constructed through calling `New` with the relevant options to capture data around the error that occurred.

Error should be obtained from a given `error` object using `errors.As`.

func (*Error) Error

func (e *Error) Error() string

Error implements the error interface.

If an error object was given, that is used. Otherwise, the gRPC error from the status.Status is used, or an error message containing the HTTP status code is given.

func (*Error) IsRetryable

func (e *Error) IsRetryable() bool

IsRetryable returns true if the error was created with NewRetryableError, if the HTTP status code is retryable according to OTLP, or if the gRPC status is retryable according to OTLP. Otherwise, returns false.

See https://github.com/open-telemetry/opentelemetry-proto/blob/main/docs/specification.md for retryable HTTP and gRPC codes.

func (*Error) Unwrap

func (e *Error) Unwrap() error

Unwrap returns the wrapped error for use by `errors.Is` and `errors.As`.

If an error object was not passed but a gRPC `status.Status` was passed, the underlying error from the status is returned.

type Logs

type Logs struct {
	internal.Retryable[plog.Logs]
}

Logs is an error that may carry associated Log data for a subset of received data that failed to be processed or sent.

type Metrics

type Metrics struct {
	internal.Retryable[pmetric.Metrics]
}

Metrics is an error that may carry associated Metrics data for a subset of received data that failed to be processed or sent.

type Traces

type Traces struct {
	internal.Retryable[ptrace.Traces]
}

Traces is an error that may carry associated Trace data for a subset of received data that failed to be processed or sent.