README
¶
go-errstack
Error wrapping with stack traces for Go
Installation
go get github.com/philiprehberger/go-errstack
Usage
import "github.com/philiprehberger/go-errstack"
Wrapping an existing error
file, err := os.Open("config.json")
if err != nil {
return errstack.Wrap(err)
}
Wrapping with a message
user, err := db.FindUser(id)
if err != nil {
return errstack.Wrapf(err, "failed to find user %d", id)
}
Creating a new error
if name == "" {
return errstack.New("name must not be empty")
}
Extracting the stack trace
if err != nil {
frames := errstack.Stack(err)
for _, f := range frames {
fmt.Println(f) // main.handleRequest (/app/server.go:42)
}
}
Annotations
Attach key-value metadata to errors without changing the message:
err := errstack.WithValue(err, "request_id", "abc-123")
err = errstack.WithValue(err, "user", "alice")
val, ok := errstack.Value(err, "request_id") // "abc-123", true
Caller
Capture a single stack frame at a given depth:
f := errstack.Caller(0) // frame of the current function
fmt.Println(f) // main.handleRequest (/app/server.go:18)
Frame filtering
Trim stack frames to focus on relevant packages:
frames := errstack.Stack(err)
frames = errstack.TrimAbove(frames, "myapp/handler") // remove frames above handler
frames = errstack.TrimBelow(frames, "myapp/handler") // remove frames below handler
Formatted stack trace
Get a formatted multi-line stack trace string:
fmt.Println(errstack.StackString(err))
// main.doWork
// /path/to/file.go:42
// main.main
// /path/to/file.go:15
Compatible with errors.Is and errors.As
var ErrNotFound = errors.New("not found")
err := errstack.Wrap(ErrNotFound)
errors.Is(err, ErrNotFound) // true
API
| Function / Type | Description |
|---|---|
Frame |
A single stack frame with Function, File, and Line fields |
Frame.String() |
Formats the frame as "Function (File:Line)" |
Wrap(err) |
Wraps an error with a stack trace; returns nil if err is nil |
Wrapf(err, fmt, args...) |
Wraps an error with a formatted message and stack trace |
New(msg) |
Creates a new error with a stack trace |
Newf(fmt, args...) |
Creates a new formatted error with a stack trace |
Stack(err) |
Extracts stack frames from an error; returns nil if none found |
StackString(err) |
Returns a formatted multi-line stack trace string |
Caller(skip) |
Returns a single stack frame at the given skip depth |
WithValue(err, key, val) |
Wraps an error with a key-value annotation |
Value(err, key) |
Extracts an annotation value from the error chain |
TrimAbove(frames, pkg) |
Removes frames above the first occurrence of pkg |
TrimBelow(frames, pkg) |
Removes frames below the last occurrence of pkg |
Development
go test ./...
go vet ./...
License
MIT
Documentation
¶
Overview ¶
Package errstack provides error wrapping with stack traces for Go.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func New ¶
New creates a new error with the given message and a stack trace captured at the call site.
func Newf ¶
Newf creates a new error with a formatted message and a stack trace captured at the call site.
func StackString ¶ added in v0.2.0
StackString returns a formatted multi-line stack trace string from an error. Each frame is rendered as two lines: the function name, then the file and line indented with a tab. Returns an empty string if no stack frames are found.
func Value ¶ added in v0.2.0
Value extracts an annotation value from the error chain by key. It walks the chain using errors.As looking for an annotatedError with a matching key. Returns the value and true if found, or nil and false otherwise.
func WithValue ¶ added in v0.2.0
WithValue wraps err with a key-value annotation. The original error and its chain are preserved. Returns nil if err is nil.
Types ¶
type Frame ¶
Frame represents a single stack frame.
func Caller ¶ added in v0.2.0
Caller returns a single stack frame at the given skip depth. Skip 0 refers to the caller of Caller itself.
func Stack ¶
Stack extracts stack frames from an error. It walks the Unwrap chain looking for an error that carries stack information. Returns nil if no stack frames are found.
func TrimAbove ¶ added in v0.2.0
TrimAbove removes frames from packages above the specified package in the stack. It finds the first frame whose Function contains pkg and returns that frame and all frames below it (i.e., frames from the first occurrence onward).
Source Files