errors

README

Adds stacktraces to errors in golang.

This was made to help build the Bugsnag notifier but can be used standalone if you like to have stacktraces on errors.

See Godoc for the API docs.

Documentation

Overview

Package errors provides errors that have stack-traces.

Index

• Variables
• type Error
  • func Errorf(format string, a ...interface{}) *Error
  • func New(e interface{}, skip int) *Error
  • func ParsePanic(text string) (*Error, error)
  • func (err *Error) Callers() []uintptr
  • func (err *Error) Error() string
  • func (err *Error) Stack() []byte
  • func (err *Error) StackFrames() []StackFrame
  • func (err *Error) TypeName() string
• type ErrorWithCallers
• type ErrorWithStackFrames
• type StackFrame
  • func NewStackFrame(pc uintptr) (frame StackFrame)
  • func (frame *StackFrame) Func() *runtime.Func
  • func (frame *StackFrame) SourceLine() (string, error)
  • func (frame *StackFrame) String() string

Examples

• Errorf
• New
• New (Skip)

Variables

var MaxStackDepth = 50

The maximum number of stackframes on any error.

Types

type Error

type Error struct {
	Err   error
	Cause *Error
	// contains filtered or unexported fields
}

Error is an error with an attached stacktrace. It can be used wherever the builtin error interface is expected.

func Errorf

func Errorf(format string, a ...interface{}) *Error

Errorf creates a new error with the given message. You can use it as a drop-in replacement for fmt.Errorf() to provide descriptive errors in return values.

Example

for i := 1; i <= 2; i++ {
	if i%2 == 1 {
		e := Errorf("can only halve even numbers, got %d", i)
		fmt.Printf("Error: %+v", e)
	}
}

Output:

Error: can only halve even numbers, got 1

func New

func New(e interface{}, skip int) *Error

New makes an Error from the given value. If that value is already an error then it will be used directly, if not, it will be passed to fmt.Errorf("%v"). The skip parameter indicates how far up the stack to start the stacktrace. 0 is from the current call, 1 from its caller, etc.

Example

// Wrap io.EOF with the current stack-trace and return it
e := New(io.EOF, 0)
fmt.Printf("%+v", e)

Output:

EOF

Example (Skip)

defer func() {
	if err := recover(); err != nil {
		// skip 1 frame (the deferred function) and then return the wrapped err
		err = New(err, 1)
	}
}()

func ParsePanic

func ParsePanic(text string) (*Error, error)

ParsePanic allows you to get an error object from the output of a go program that panicked. This is particularly useful with https://github.com/mitchellh/panicwrap.

func (*Error) Callers

func (err *Error) Callers() []uintptr

Callers returns the raw stack frames as returned by runtime.Callers()

func (*Error) Error

func (err *Error) Error() string

Error returns the underlying error's message.

func (*Error) Stack

func (err *Error) Stack() []byte

Stack returns the callstack formatted the same way that go does in runtime/debug.Stack()

func (*Error) StackFrames

func (err *Error) StackFrames() []StackFrame

StackFrames returns an array of frames containing information about the stack.

func (*Error) TypeName

func (err *Error) TypeName() string

TypeName returns the type this error. e.g. *errors.stringError.

type ErrorWithCallers

type ErrorWithCallers interface {
	Error() string
	Callers() []uintptr
}

ErrorWithCallers allows passing in error objects that also have caller information attached.

type ErrorWithStackFrames

type ErrorWithStackFrames interface {
	Error() string
	StackFrames() []StackFrame
}

ErrorWithStackFrames allows the stack to be rebuilt from the stack frames, thus allowing to use the Error type when the program counter is not available.

type StackFrame

type StackFrame struct {
	File           string
	LineNumber     int
	Name           string
	Package        string
	ProgramCounter uintptr
	// contains filtered or unexported fields
}

A StackFrame contains all necessary information about to generate a line in a callstack.

func NewStackFrame

func NewStackFrame(pc uintptr) (frame StackFrame)

NewStackFrame popoulates a stack frame object from the program counter.

func (*StackFrame) Func

func (frame *StackFrame) Func() *runtime.Func

Func returns the function that this stackframe corresponds to

func (*StackFrame) SourceLine

func (frame *StackFrame) SourceLine() (string, error)

SourceLine gets the line of code (from File and Line) of the original source if possible

func (*StackFrame) String

func (frame *StackFrame) String() string

String returns the stackframe formatted in the same way as go does in runtime/debug.Stack()