errtrace

Documentation

Overview

Package errtrace provides a simple way to annotate errors with the stack trace of the caller.

Index

• Variables
• func Annotate(s string) error
• func Annotatef(s string, args ...any) error
• func IsTraceable(err error) bool
• func MarshalStack(err error) any
• func New(msg string, args ...any) error
• func RelativeCleaner() func(path string) string
• func Trace(msg string, args ...any) error
• func TraceString(err error) string
• func TraceWrap(err error, msg string, args ...any) error
• func Wrap(err error) error
• func Wrapf(err error, msg string, args ...any) error
• type StackTraceData
  • func TraceData(err error) (*StackTraceData, error)
  • func (s *StackTraceData) Loc() string

Variables

var OverrideCleaner func(path string) string

OverrideCleaner is a function that can be set to override the default path cleaner for the Annotate and Traceable function. The default cleaner removes the current working directory from the file path. Use this to override that behavior, for example to use the full file path.

Functions

func Annotate

func Annotate(s string) error

Annotate is a lighter version of Traceable and a drop in replacement for errors.New. instead of returning a traceable error it returns a standard error which is prefixed with the file and line number of the caller of Annotate.

func Annotatef

func Annotatef(s string, args ...any) error

Annotatef is a lighter version of Traceable and a drop in replacement for fmt.Errorf. instead of returning a traceable error it returns a standard error which is prefixed with the file and line number of the caller of Annotatef.

This is useful for annotating errors with additional file/line context, but without the overhead of a traceable error. Using Annotatef is more appropriate for errors created by 'library' type code within your project.

Example:

err := Annotatef("users prefix: %w", errors.New("wrapped error text"))
println(err.Error())
// output: relative/path/filename.go:41 : prefix: wrapped error text

Note:

• If the first argument is an empty string Annotatef will return nil.
• If the args slice is empty Annotatef will return nil.

func IsTraceable

func IsTraceable(err error) bool

func MarshalStack

func MarshalStack(err error) any

MarshalStack implements a custom JSON marshaller for errors that are traceable. This was implemented for use within github.com/rs/zerolog package.

func New

func New(msg string, args ...any) error

New creates a new error with a stacktrace and returns the new error. Use this like you would fmt.Errorf.

func RelativeCleaner

func RelativeCleaner() func(path string) string

RelativeCleaner returns a function that can be used to clean the file path to a relative path. The returned function will remove the current working directory from the file path.

If the current working directory cannot be determined, the returned function will fall back to the default path cleaner.

Example:

errtrace.OverrideCleaner = errtrace.RelativeCleaner()

func Trace

func Trace(msg string, args ...any) error

Trace creates a new error with a stacktrace and returns the new error. Use this like you would fmt.Errorf.

Deprecated: Use New instead.

func TraceString

func TraceString(err error) string

TraceString returns a string representation of the error and all its causes.

func TraceWrap

func TraceWrap(err error, msg string, args ...any) error

TraceWrap is the same as Trace, but it wraps an existing error. Deprecated: Use Wrapf instead.

func Wrap

func Wrap(err error) error

Wrap wraps an error within a stacktrace and returns the new error.

func Wrapf

func Wrapf(err error, msg string, args ...any) error

Wrapf wraps an error within a stacktrace and returns the new error.

• The stacktrace is generated at the point of the call to Wrapf.
• The message is formatted using fmt.Sprintf. The error returned by Wrapf implements the Error and Unwrap interfaces.
• If the error is nil, Wrapf returns nil.

Wrapf errors are intended to be used for debugging and should only be viewed by developers. They should _generally_ not be returned to the users of your application.

To use a Wrapf error, you can use the TraceString function to get a printable string of the stacktrace.

Example:

func doSomething(v string) error {
  err := doSomethingElse()
  if err != nil {
    return errtrace.Wrapf(err, "failed to do something with %s", v)
  }

  return nil
}

Types

type StackTraceData

type StackTraceData struct {
	Message  string // The message of the error
	File     string // The file of the caller of the Traceable function
	Function string // The function of the caller of the Traceable function
	Line     int    // The line number of the caller of the Traceable function
	Cause    error  // The underlying error wrapped by the Traceable function
}

StackTraceData contains the data of a stacktrace. It is returned by TraceData. It is not meant to be used directly, but rather to be used by other packages.

func TraceData

func TraceData(err error) (*StackTraceData, error)

TraceData returns the file, function and line number of the caller of the Traceable function.

func (*StackTraceData) Loc

func (s *StackTraceData) Loc() string

Loc returns a formatted string that contains the file, function and line number of the caller of the Traceable function.

Example: "main.go:42 main.main"