errors

Documentation

Overview

Personalize the errors stdlib to prepend the calling functions name to errors for simpler, smaller traces An example of how this work can be seen at github.com/danlock/gogosseract. Example error message from gogosseract: gogosseract.NewPool failed worker setup due to gogosseract.(*Pool).runTesseract gogosseract.New gogosseract.Tesseract.createByteView wasm.GetReaderSize io.Reader was empty

Index

• Variables
• func As(err error, target any) bool
• func Errorf(format string, a ...any) error
• func ErrorfWithSkip(format string, skip int, a ...any) error
• func Into[T error](err error) (val T, ok bool)
• func Is(err error, target error) bool
• func Join(errs ...error) error
• func Must[T any](val T, err error) T
• func Must2[T, U any](val T, val2 U, err error) (T, U)
• func New(text string) error
• func Unwrap(err error) error
• func UnwrapMeta(err error) []slog.Attr
• func UnwrapMetaSansErr(err error) (meta []slog.Attr)
• func Wrap(err error) error
• func WrapMeta(err error, meta ...slog.Attr) error
• func Wrapf(err error, format string, a ...any) error

Examples

• UnwrapMeta

Variables

var ErrUnsupported = errors.ErrUnsupported

Functions

func As

func As(err error, target any) bool

func Errorf

func Errorf(format string, a ...any) error

Errorf is like fmt.Errorf with the "package.func" of it's caller prepended.

func ErrorfWithSkip

func ErrorfWithSkip(format string, skip int, a ...any) error

Errorf is like fmt.Errorf with the "package.func" of the desired caller prepended.

func Into

func Into[T error](err error) (val T, ok bool)

Into finds the first error in err's chain that matches target type T, and if so, returns it.

Into is a type-safe alternative to As.

func Is

func Is(err error, target error) bool

func Join

func Join(errs ...error) error

func Must

func Must[T any](val T, err error) T

Must is a generic helper, like template.Must, that wraps a call to a function returning (T, error) and panics if the error is non-nil.

func Must2

func Must2[T, U any](val T, val2 U, err error) (T, U)

func New

func New(text string) error

New creates a new error with the package.func of it's caller prepended.

func Unwrap

func Unwrap(err error) error

func UnwrapMeta

func UnwrapMeta(err error) []slog.Attr

UnwrapMeta pulls metadata from every error in the chain for structured logging purposes. The error itself is also included as slog.Any("err", err) for ease of use with slog.LogAttrs.

Example

// This is just setup code that makes slog's output deterministic so the example output is stable.
// Typically you would be using JSONHandler or something else easier to parse.
slog.SetDefault(slog.New(slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{
	ReplaceAttr: func(_ []string, a slog.Attr) slog.Attr {
		if a.Key == slog.TimeKey {
			return slog.Attr{}
		}
		return a
	},
})))
// This example shows how to use WrapMeta() to attach metadata to errors, and how to extract that metadata later.
err := dontHurtMe()
if err != nil {
	// include some metadata about this failure
	err = WrapMeta(err, slog.String("baby", "don't"), slog.String("hurt", "me"))
}
// Typically this error would then bubble up through a few more function cals.
// Eventually something must handle this error.
// For exanple, we can log it
if err != nil {
	slog.LogAttrs(context.TODO(), slog.LevelWarn, "what is love", UnwrapMeta(err)...)
}

// Another easy way of wrapping errors with metadata known at the start of the function is to defer WrapMeta.
// This is possible since WrapMeta returns nil if the error is nil.

err = func(id uint64, parseMe string) (err error) {
	defer func() { err = WrapMeta(err, slog.Uint64("id", id)) }()
	_, err = strconv.Atoi(parseMe)
	if err != nil {
		return Wrap(err)
	}
	return nil
}(0451, "trust me i'm numerical")

if err != nil {
	slog.LogAttrs(context.TODO(), slog.LevelWarn, "parse failure", UnwrapMeta(err)...)
}

// printing an errors.WrapMeta error with something basic like fmt.Println doesn't include the metadata in the output.
fmt.Println(err)
// unless you use %+v
fmt.Printf("%+v", err)

Output:

level=WARN msg="what is love" baby=don't hurt=me err="errors.dontHurtMe no more"
level=WARN msg="parse failure" id=297 err="errors.ExampleUnwrapMeta.func2 strconv.Atoi: parsing \"trust me i'm numerical\": invalid syntax"
errors.ExampleUnwrapMeta.func2 strconv.Atoi: parsing "trust me i'm numerical": invalid syntax
errors.ExampleUnwrapMeta.func2 strconv.Atoi: parsing "trust me i'm numerical": invalid syntax {id=297}

func UnwrapMetaSansErr

func UnwrapMetaSansErr(err error) (meta []slog.Attr)

UnwrapMetaSansErr pulls metadata from every error in the chain for structured logging purposes. It doesn't include the error itself, in case you want a different error field or something.

func Wrap

func Wrap(err error) error

Wrap wraps an error with the caller's package.func prepended. Similar to github.com/pkg/errors.Wrap it also returns nil if err is nil, unlike fmt.Errorf.

func WrapMeta

func WrapMeta(err error, meta ...slog.Attr) error

WrapMeta wraps an error with metadata for structured logging, if it exists.

func Wrapf

func Wrapf(err error, format string, a ...any) error

Wrapf wraps an error with the caller's package.func prepended. Similar to github.com/pkg/errors.Wrap it also returns nil if err is nil, unlike fmt.Errorf.