errs

Documentation

Overview

Package errs implements a detailed error object that provides stack traces with source locations, along with nested causes, if any.

Index

• Constants
• Variables
• func Log(err error, args ...any)
• func LogAttrs(err error, attrs ...slog.Attr)
• func LogAttrsContext(ctx context.Context, err error, attrs ...slog.Attr)
• func LogAttrsContextTo(ctx context.Context, logger *slog.Logger, err error, attrs ...slog.Attr)
• func LogAttrsTo(logger *slog.Logger, err error, attrs ...slog.Attr)
• func LogAttrsWithLevel(ctx context.Context, level slog.Level, logger *slog.Logger, err error, ...)
• func LogContext(ctx context.Context, err error, args ...any)
• func LogContextTo(ctx context.Context, logger *slog.Logger, err error, args ...any)
• func LogTo(logger *slog.Logger, err error, args ...any)
• func LogWithLevel(ctx context.Context, level slog.Level, logger *slog.Logger, err error, ...)
• func Recovery(handler RecoveryHandler)
• func Wrap(cause error) error
• type Error
  • func Append(err error, errs ...error) *Error
  • func New(message string) *Error
  • func NewWithCause(message string, cause error) *Error
  • func NewWithCausef(cause error, format string, v ...any) *Error
  • func Newf(format string, v ...any) *Error
  • func WrapTyped(cause error) *Error
  • func (e *Error) CloneWithPrefixMessage(prefix string) error
  • func (e *Error) Count() int
  • func (e *Error) Detail(trimRuntime bool) string
  • func (e *Error) Error() string
  • func (e *Error) ErrorOrNil() error
  • func (e *Error) Format(state fmt.State, verb rune)
  • func (e *Error) LogValue() slog.Value
  • func (e *Error) Message() string
  • func (e *Error) RawStackTrace() []uintptr
  • func (e *Error) StackTrace(trimRuntime bool) string
  • func (e *Error) Unwrap() error
  • func (e *Error) WrappedErrors() []error
• type ErrorWrapper
• type RecoveryHandler
• type StackError

Examples

• Error

Constants

const StackTraceKey = "stack_trace"

StackTraceKey is the key used for logging the stack trace.

Variables

var (

	// RuntimePrefixesToFilter is a list of prefixes to filter out of the stack trace.
	//
	// This variable is not used in a thread-safe manner, so any alterations should be done before any goroutines are
	// started.
	RuntimePrefixesToFilter = []string{
		"runtime.",
		"testing.",
		"github.com/richardwilkes/toolbox/errs.",
	}
)

Functions

func Log

func Log(err error, args ...any)

Log an error with a stack trace.

func LogAttrs

func LogAttrs(err error, attrs ...slog.Attr)

LogAttrs logs an error with a stack trace.

func LogAttrsContext

func LogAttrsContext(ctx context.Context, err error, attrs ...slog.Attr)

LogAttrsContext logs an error with a stack trace.

func LogAttrsContextTo

func LogAttrsContextTo(ctx context.Context, logger *slog.Logger, err error, attrs ...slog.Attr)

LogAttrsContextTo logs an error with a stack trace.

func LogAttrsTo

func LogAttrsTo(logger *slog.Logger, err error, attrs ...slog.Attr)

LogAttrsTo logs an error with a stack trace.

func LogAttrsWithLevel

func LogAttrsWithLevel(ctx context.Context, level slog.Level, logger *slog.Logger, err error, attrs ...slog.Attr)

LogAttrsWithLevel logs an error with a stack trace.

func LogContext

func LogContext(ctx context.Context, err error, args ...any)

LogContext logs an error with a stack trace.

func LogContextTo

func LogContextTo(ctx context.Context, logger *slog.Logger, err error, args ...any)

LogContextTo logs an error with a stack trace.

func LogTo

func LogTo(logger *slog.Logger, err error, args ...any)

LogTo logs an error with a stack trace.

func LogWithLevel

func LogWithLevel(ctx context.Context, level slog.Level, logger *slog.Logger, err error, args ...any)

LogWithLevel logs an error with a stack trace.

func Recovery

func Recovery(handler RecoveryHandler)

Recovery provides an easy way to run code that may panic. 'handler' will be called with the panic turned into an error. Pass in nil to silently ignore any panic.

Typical usage:

func runSomeCode(handler errs.RecoveryHandler) {
    defer errs.Recovery(handler)
    // ... run the code here ...
}

func Wrap

func Wrap(cause error) error

Wrap an error and turn it into a detailed error. If error is already a detailed error or nil, it will be returned as-is.

Types

type Error

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

Error holds the detailed error message.

Example

package main

import (
	"fmt"

	"github.com/richardwilkes/toolbox/errs"
)

func main() {
	var bad *int
	func() int {
		defer errs.Recovery(func(err error) { fmt.Println(err) })
		return *bad // trigger a panic due to a nil pointer dereference
	}()
}

Output:

recovered from panic
    [github.com/richardwilkes/toolbox/errs_test.ExampleError.func1] errors_test.go:27
    [github.com/richardwilkes/toolbox/errs_test.ExampleError] errors_test.go:28
  Caused by: runtime error: invalid memory address or nil pointer dereference

func Append

func Append(err error, errs ...error) *Error

Append one or more errors to an existing error. err may be nil.

func New

func New(message string) *Error

New creates a new detailed error with the 'message'.

func NewWithCause

func NewWithCause(message string, cause error) *Error

NewWithCause creates a new detailed error with the 'message' and underlying 'cause'.

func NewWithCausef

func NewWithCausef(cause error, format string, v ...any) *Error

NewWithCausef creates a new detailed error with an underlying 'cause' and using fmt.Sprintf() to format the message.

func Newf

func Newf(format string, v ...any) *Error

Newf creates a new detailed error using fmt.Sprintf() to format the message.

func WrapTyped

func WrapTyped(cause error) *Error

WrapTyped wraps an error and turns it into a detailed error. If error is already a detailed error or nil, it will be returned as-is. This method returns the error as an *Error. Use Wrap() to receive a generic error.

func (*Error) CloneWithPrefixMessage

func (e *Error) CloneWithPrefixMessage(prefix string) error

CloneWithPrefixMessage clones this error and adds a prefix to its message.

func (*Error) Count

func (e *Error) Count() int

Count returns the number of contained errors, not including causes.

func (*Error) Detail

func (e *Error) Detail(trimRuntime bool) string

Detail returns the fully detailed error message, which includes the primary message, the call stack, and potentially one or more chained causes. Note that any included stack trace will be only for the first error in the case where multiple errors were accumulated into one via calls to .Append().

func (*Error) Error

func (e *Error) Error() string

Error implements the error interface.

func (*Error) ErrorOrNil

func (e *Error) ErrorOrNil() error

ErrorOrNil returns an error interface if this Error represents one or more errors, or nil if it is empty.

func (*Error) Format

func (e *Error) Format(state fmt.State, verb rune)

Format implements the fmt.Formatter interface.

Supported formats:

• "%s" Just the message
• "%q" Just the message, but quoted
• "%v" The message plus a stack trace, trimmed of golang runtime calls
• "%+v" The message plus a stack trace

func (*Error) LogValue

func (e *Error) LogValue() slog.Value

LogValue implements the slog.LogValuer interface.

func (*Error) Message

func (e *Error) Message() string

Message returns the message attached to this error.

func (*Error) RawStackTrace

func (e *Error) RawStackTrace() []uintptr

RawStackTrace returns the raw call stack pointers for the first error within this error.

func (*Error) StackTrace

func (e *Error) StackTrace(trimRuntime bool) string

StackTrace returns just the stack trace portion of the message.

func (*Error) Unwrap

func (e *Error) Unwrap() error

Unwrap implements errors.Unwrap and returns the underlying cause, if any.

func (*Error) WrappedErrors

func (e *Error) WrappedErrors() []error

WrappedErrors returns the contained errors.

type ErrorWrapper

type ErrorWrapper interface {
	error
	Count() int
	WrappedErrors() []error
}

ErrorWrapper contains methods for interacting with the wrapped errors.

type RecoveryHandler

type RecoveryHandler func(error)

RecoveryHandler defines the callback used when panics occur with Recovery.

type StackError

type StackError interface {
	error
	Message() string
	Detail(trimRuntime bool) string
	StackTrace(trimRuntime bool) string
}

StackError contains methods with the stack trace and message.