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, a ...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.
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,
)
Two notable properties do not require a name: errors and integers.
New("failed to parse form",
err,
http.StatusBadRequest,
"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.
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.
New("user not found",
http.StatusNotFound,
"id", userID,
)
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:"function"`
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,omitempty"`
Properties map[string]any `json:"properties,omitempty"`
Stack []*StackFrame `json:"stack,omitempty"`
}
StreamedError is the schema used to marshal and unmarshal the traced error.
type TracedError ¶
type TracedError struct {
Err error
Stack []*StackFrame
StatusCode int
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.
func (*TracedError) Unwrap ¶
func (e *TracedError) Unwrap() error
Unwrap returns the underlying error.
Source Files