feat(stack): error stack traces

Author: ChrisRx

errors/stack.go

@@ -0,0 +1,55 @@
+package errors
+
+import (
+	"strings"
+
+	"go.chrisrx.dev/x/slices"
+	"go.chrisrx.dev/x/stack"
+)
+
+type Frames []stack.Frame
+
+func (f Frames) String() string {
+	return strings.Join(slices.Map(f, func(f stack.Frame) string {
+		return f.String()
+	}), "\n    ")
+}
+
+type StackError interface {
+	error
+
+	// Trace returns a stack trace for this error.
+	Trace() Frames
+
+	isStackError()
+}
+
+type stackError struct {
+	error
+
+	frames []stack.Frame
+}
+
+var _ StackError = (*stackError)(nil)
+
+func Stack(err error) error {
+	if err == nil {
+		return nil
+	}
+	if _, ok := err.(StackError); ok {
+		return err
+	}
+	return &stackError{
+		error:  err,
+		frames: stack.Trace(1),
+	}
+}
+
+func (e *stackError) Error() string { return e.error.Error() }
+func (e *stackError) Unwrap() error { return e.error }
+
+func (e *stackError) Trace() Frames {
+	return e.frames
+}
+
+func (e *stackError) isStackError() {}

errors/stack_test.go

@@ -0,0 +1,40 @@
+package errors_test
+
+import (
+	"cmp"
+	"fmt"
+	"strings"
+	"testing"
+
+	"go.chrisrx.dev/x/assert"
+	"go.chrisrx.dev/x/errors"
+	"go.chrisrx.dev/x/slices"
+	"go.chrisrx.dev/x/stack"
+)
+
+func getError() error {
+	return getStackError()
+}
+
+func getStackError() error {
+	return errors.Stack(fmt.Errorf("is a stack error"))
+}
+
+func TestStackError(t *testing.T) {
+	err, _ := errors.As[errors.StackError](getError())
+	assert.Error(t, "is a stack error", err)
+	assert.Equal(t,
+		[]string{
+			"go.chrisrx.dev/x/errors_test.getStackError",
+			"go.chrisrx.dev/x/errors_test.getError",
+			"go.chrisrx.dev/x/errors_test.TestStackError",
+		},
+		slices.Filter(slices.Map(err.Trace(), func(f stack.Frame) string {
+			return f.Name()
+		}), func(name string) bool {
+			return !cmp.Or(
+				strings.HasPrefix(name, "testing"),
+				strings.HasPrefix(name, "runtime"),
+			)
+		}))
+}

log/alias.go

@@ -1,12 +1,17 @@
-//go:generate go tool aliaspkg -docs=decls -include Fatal,Fatalf,Fatalln,Panic,Panicf,Panicln,Print,Printf,Println
+//go:generate go tool aliaspkg -docs=decls -include Panic,Panicf,Panicln,Print,Printf,Println
 
 package log
 
 import (
+	"fmt"
 	"log/slog"
+	"os"
 	"sync"
 
 	"go.chrisrx.dev/x/env"
+	"go.chrisrx.dev/x/errors"
+	"go.chrisrx.dev/x/slices"
+	"go.chrisrx.dev/x/strings"
 )
 
 // New constructs a new [*slog.Logger] with the provided options.
@@ -37,3 +42,80 @@ func SetDefault() {
 		slog.Debug("default slog configured from environment", slog.Any("options", opts))
 	})
 }
+
+// Fatal is similar to [log.Fatal], but uses the default [slog.Logger]. It is
+// meant to be used at the end of an error chain only.
+//
+// If GO_BACKTRACE=1 environment variable is set, any arguments containing a
+// stack trace will be printed directly to stderr. Only the first argument
+// containing a stack trace will be printed.
+func Fatal(v ...any) {
+	msg := fmt.Sprint(v...)
+	if isBacktraceEnabled() {
+		printBacktrace(msg, v)
+	}
+	slog.Error(msg)
+	os.Exit(1)
+}
+
+// Fatalf is similar to [log.Fatalf], but uses the default [slog.Logger]. It is
+// meant to be used at the end of an error chain only.
+//
+// If GO_BACKTRACE=1 environment variable is set, any arguments containing a
+// stack trace will be printed directly to stderr. Only the first argument
+// containing a stack trace will be printed.
+func Fatalf(format string, v ...any) {
+	msg := fmt.Sprintf(format, v...)
+	if isBacktraceEnabled() {
+		printBacktrace(msg, v)
+	}
+	slog.Error(msg)
+	os.Exit(1)
+}
+
+// Fatalln is similar to [log.Fatalln], but uses the default [slog.Logger]. It
+// is meant to be used at the end of an error chain only.
+//
+// If GO_BACKTRACE=1 environment variable is set, any arguments containing a
+// stack trace will be printed directly to stderr. Only the first argument
+// containing a stack trace will be printed.
+func Fatalln(v ...any) {
+	msg := fmt.Sprintln(v...)
+	if isBacktraceEnabled() {
+		printBacktrace(msg, v)
+	}
+	slog.Error(msg)
+	os.Exit(1)
+}
+
+const backtraceEnvVar = "GO_BACKTRACE"
+
+func isBacktraceEnabled() bool {
+	if value, ok := os.LookupEnv(backtraceEnvVar); ok && value == "1" {
+		return true
+	}
+	return false
+}
+
+// checkBacktrace checks if any arguments implement [errors.StackError] and
+// prints the full stack trace to stderr. Arguments are checked in order and if
+// multiple stack traces are provided, only the first is printed.
+//
+// This behavior is opt-in, requiring environment variable GO_BACKTRACE=1 to be
+// set.
+func printBacktrace(msg string, args []any) {
+	if len(args) == 0 {
+		return
+	}
+	for _, arg := range args {
+		if err, ok := arg.(error); ok {
+			if err, ok := errors.As[errors.StackError](err); ok {
+				if v, ok := os.LookupEnv(backtraceEnvVar); ok && v == "1" {
+					slog.Error(msg)
+					fmt.Fprintln(os.Stderr, strings.Join(slices.Map(err.Trace(), strings.ToString), "\n\t"))
+					os.Exit(1)
+				}
+			}
+		}
+	}
+}

log/log.go

@@ -20,11 +20,11 @@ func Recover(errs ...error) {
 	if r := recover(); r != nil {
 		if len(errs) == 0 {
 			slog.Error("panic",
-				slog.String("loc", stack.GetLocation(func(s stack.Source) bool {
+				slog.String("loc", stack.Location(func(s stack.Frame) bool {
 					return cmp.Or(
-						strings.HasPrefix(s.FullName, "runtime"),
-						strings.HasPrefix(s.FullName, "go.chrisrx.dev/x/must"),
-						strings.HasPrefix(s.FullName, "go.chrisrx.dev/x/safe"),
+						strings.HasPrefix(s.Name(), "runtime"),
+						strings.HasPrefix(s.Name(), "go.chrisrx.dev/x/must"),
+						strings.HasPrefix(s.Name(), "go.chrisrx.dev/x/safe"),
 					)
 				})),
 				slog.Any("err", asError(r)),

must/recover.go

@@ -4,50 +4,74 @@ package stack
 
 import (
 	"fmt"
-	"path/filepath"
+	"go/build"
+	"reflect"
 	"runtime"
 	"strings"
 )
 
-type Source struct {
-	File     string
-	Line     int
-	FullName string
-}
+const maxStackDepth = 10
 
-func (s Source) Name() string {
-	return s.FullName[strings.LastIndex(s.FullName, "/")+1:]
+type Frame struct {
+	pc   uintptr
+	file string
+	line int
+	name string
 }
 
-func (s Source) String() string {
-	name := s.Name()
-	if name == "" {
-		return fmt.Sprintf("%s:%d", s.File, s.Line)
+func (f Frame) String() string {
+	s := fmt.Sprintf("%s:%d", f.file, f.line)
+	if f.name == "" {
+		return s
 	}
-	return fmt.Sprintf("%s:%d %s", s.File, s.Line, name)
+	return s + fmt.Sprintf(" -- %s()", f.name[strings.LastIndex(f.name, "/")+1:])
 }
 
-func GetSource(skip int) Source {
-	pc, file, line, _ := runtime.Caller(1 + skip)
-	s := Source{
-		File: filepath.Base(file),
-		Line: line,
-	}
-	if fn := runtime.FuncForPC(pc); fn != nil {
-		s.FullName = fn.Name()
-	}
-	return s
+func (f Frame) Name() string {
+	return f.name
 }
 
-const maxStackDepth = 10
+type dummy struct{}
+
+var packageName = reflect.TypeOf(dummy{}).PkgPath()
 
-func GetLocation(ignore func(Source) bool) string {
+func Trace(skip int) (frames []Frame) {
 	for i := 1; i < maxStackDepth; i++ {
-		s := GetSource(i + 1)
-		if ignore(s) {
+		pc, file, line, ok := runtime.Caller(i + skip)
+		if !ok {
+			break
+		}
+		fn := runtime.FuncForPC(pc)
+		if fn == nil {
+			break
+		}
+		name := fn.Name()
+		file = strings.TrimPrefix(file, build.Default.GOROOT+"/src/")
+
+		// Filter out all frames from this package.
+		if strings.HasPrefix(name, packageName) {
+			continue
+		}
+		GOROOT := build.Default.GOROOT
+		if len(GOROOT) > 0 && strings.Contains(file, GOROOT) {
+			continue
+		}
+		frames = append(frames, Frame{
+			pc:   pc,
+			file: file,
+			line: line,
+			name: name,
+		})
+	}
+	return frames
+}
+
+func Location(ignore func(Frame) bool) string {
+	for _, frame := range Trace(1) {
+		if ignore(frame) {
 			continue
 		}
-		return s.String()
+		return frame.String()
 	}
 	return "<unknown>"
 }

stack/stack.go

@@ -6,6 +6,7 @@ import (
 	"bufio"
 	"bytes"
 	"cmp"
+	"fmt"
 	"strings"
 	"unicode"
 	"unicode/utf8"
@@ -89,3 +90,7 @@ func ToSnakeCase(s string) string {
 	}
 	return b.String()
 }
+
+func ToString[T fmt.Stringer](s T) string {
+	return s.String()
+}