Golang Errors with Stack Trace and Source Fragments

Tired of uninformative error output? Probably this will be more convenient:

Example

package main

import (
	"io/ioutil"

	"github.com/ztrue/tracerr"
)

func main() {
	if err := read(); err != nil {
		tracerr.PrintSourceColor(err)
	}
}

func read() error {
	return readNonExistent()
}

func readNonExistent() error {
	_, err := ioutil.ReadFile("/tmp/non_existent_file")
	// Add stack trace to existing error, no matter if it's nil.
	return tracerr.Wrap(err)
}

Find more executable examples in examples dir.

How to Use

Import

import "github.com/ztrue/tracerr"

Create New Error

err := tracerr.New("some error")

Or:

err := tracerr.Errorf("some error %d", num)

Add Stack Trace to Existing Error

If err is nil then it still be nil with no stack trace added.

err = tracerr.Wrap(err)

Print Error and Stack Trace

Stack trace will be printed only if err is of type tracerr.Error, otherwise just error text will be shown.

This will print error message and stack trace if any:

tracerr.Print(err)

This will add source code:

tracerr.PrintSource(err)

It's able to set up number of lines of code to display for each frame, which is 6 by default:

tracerr.PrintSource(err, 9)

Or to set up number of lines before and after traced line:

tracerr.PrintSource(err, 5, 2)

The same, but with color, which is much more useful:

tracerr.PrintSourceColor(err)

tracerr.PrintSourceColor(err, 9)

tracerr.PrintSourceColor(err, 5, 2)

Save Output to Variable

It's also able to save output to variable instead of printing it, which works the same way:

text := tracerr.Sprint(err)

text := tracerr.SprintSource(err)

text := tracerr.SprintSource(err, 9)

text := tracerr.SprintSource(err, 5, 2)

Get Stack Trace

Stack trace will be empty if err is not an instance of tracerr.Error.

frames := tracerr.StackTrace(err)

Or if err is of type tracerr.Error:

frames := err.StackTrace()

Get Original Error

Unwrapped error will be nil if err is nil and will be the same error if err is not an instance of tracerr.Error.

err = tracerr.Unwrap(err)

Or if err is of type tracerr.Error:

err = err.Unwrap()

Performance

Benchmarks for creating a new error with a stack trace of different depth:

GOMAXPROCS=1 go test -bench=. -benchmem
goos: linux
goarch: amd64
pkg: github.com/ztrue/tracerr
cpu: Intel(R) Core(TM) i7-14700KF
BenchmarkNew/5           4500129               267.1 ns/op           256 B/op          4 allocs/op
BenchmarkNew/10          3325456               359.5 ns/op           256 B/op          4 allocs/op
BenchmarkNew/20          1000000              1001 ns/op             576 B/op          5 allocs/op
BenchmarkNew/40           538689              2171 ns/op            1216 B/op          6 allocs/op
PASS
ok      github.com/ztrue/tracerr        5.246s