Documentation
¶
Overview ¶
Package errors replaces the standard Go package, adding the ability to attach a stack trace and annotations to an error
Index ¶
- func As(err error, target any) bool
- func CatchPanic(f func() error) (err error)
- func Is(err, target error) bool
- func Join(errs ...error) error
- func New(pattern string, args ...any) error
- func Newc(statusCode int, text string) errordeprecated
- func Newcf(statusCode int, format string, a ...any) errordeprecated
- func Newf(format string, a ...any) errordeprecated
- func RuntimeTrace(levels int) (file string, function string, line int, ok bool)
- func StatusCode(err error) int
- func Trace(err error, a ...any) error
- func TraceCaller(err error) error
- func TraceFull(err error, level int) error
- func TraceUp(err error, level int) errordeprecated
- func Tracec(statusCode int, err error) errordeprecated
- func Unwrap(err error) error
- type StackFrame
- type StreamedError
- type TracedError
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CatchPanic ¶ added in v1.13.1
CatchPanic calls the given function and returns any panic as a standard error.
func Join ¶
Join aggregates multiple errors into one. The stack traces of the original errors are discarded and a new stack trace is captured.
func New ¶
New creates a new error, with a static or formatted message, optionally wrapping another error, attaching a status code or attaching properties.
In the simplest case, the pattern is a static string.
New("network timeout")
If the pattern contains % signs, the next appropriate number of arguments are used to format the message of the new error as if with fmt.Errorf.
New("failed to parse '%s' for user %d", dateStr, userID)
Any additional arguments are treated like slog name=value pairs and added to the error's property bag. Properties are not part of the error's message and can be retrieved up the call stack in a structured way.
New("failed to execute '%s'", cmd,
"exitCode", exitCode,
"os", os,
)
Three notable properties do not require a name: errors, integers and 32-character long hex string.
New("failed to parse form",
err,
http.StatusBadRequest,
"ba0da7b3d3150f20702229c4521b58e9",
"path", r.URL.Path,
)
An unnamed error is interpreted to be the original source of the error. The new error is created to wrap the original error as if with
fmt.Errorf(errorMessage+": %w", originalError)
An unnamed integer is interpreted to be an HTTP status code to associate with the error. If the pattern is empty, the status text is set by default.
An unnamed 32-character long hex string is interpreted to be a trace ID.
func RuntimeTrace ¶
RuntimeTrace traces back by the amount of levels to retrieve the runtime information used for tracing.
func StatusCode ¶
StatusCode returns the HTTP status code associated with an error. It is the equivalent of Convert(err).StatusCode. If not specified, the default status code is 500.
func Trace ¶
Trace appends the current stack location to the error's stack trace. The variadic arguments behave like those of New.
func TraceCaller ¶ added in v1.13.1
TraceCaller appends the stack location of the caller to the error's stack trace.
func TraceFull ¶
TraceFull appends the full stack to the error's stack trace, starting at the indicated level. Level 0 captures the location of the caller.
Types ¶
type StackFrame ¶ added in v1.13.1
type StackFrame struct {
Function string `json:"func"`
File string `json:"file"`
Line int `json:"line"`
}
StackFrame is a single stack location.
func (*StackFrame) String ¶ added in v1.13.1
func (t *StackFrame) String() string
String returns a string representation of the stack frame.
type StreamedError ¶ added in v1.13.1
type StreamedError struct {
Error string `json:"error" jsonschema:"example=message"`
StatusCode int `json:"statusCode,omitzero"`
Trace string `json:"trace,omitzero"`
Stack []*StackFrame `json:"stack,omitzero"`
}
StreamedError is the schema used to marshal and unmarshal the traced error.
type TracedError ¶
type TracedError struct {
Err error
Stack []*StackFrame
StatusCode int
Trace string
Properties map[string]any
}
TracedError is a standard Go error augmented with a stack trace, status code and property bag.
func Convert ¶
func Convert(err error) *TracedError
Convert converts an error to one that supports stack tracing. If the error already supports this, it is returned as it is. Note: Trace should be called to include the error's trace in the stack.
func (*TracedError) Error ¶ added in v1.13.1
func (e *TracedError) Error() string
Error returns the error string.
func (*TracedError) Format ¶
func (e *TracedError) Format(s fmt.State, verb rune)
Format the error based on the verb and flag.
func (*TracedError) MarshalJSON ¶
func (e *TracedError) MarshalJSON() ([]byte, error)
MarshalJSON marshals the error to JSON.
func (*TracedError) String ¶
func (e *TracedError) String() string
String returns a human-friendly representation of the traced error.
func (*TracedError) UnmarshalJSON ¶
func (e *TracedError) UnmarshalJSON(data []byte) error
UnmarshalJSON unmarshals the error from JSON. Neither the type of the error nor any errors it wraps can be restored.
func (*TracedError) Unwrap ¶
func (e *TracedError) Unwrap() error
Unwrap returns the underlying error.
Source Files