errors

Documentation

Overview

Package errors defines error types used across Lantern project.

n, err := Foo()
if err != nil {
    return n, errors.New("Unable to do Foo: %v", err)
}

or

  n, err := Foo()
	return n, errors.Wrap(err)

New() method will create a new error with err as its cause. Wrap will wrap err, returning nil if err is nil. If err is an error from Go's standard library, errors will extract details from that error, at least the Go type name and the return value of err.Error().

One can record the operation on which the error occurred using Op():

return n, errors.New("Unable to do Foo: %v", err).Op("FooDooer")

One can also record additional data:

  return n, errors.
		New("Unable to do Foo: %v", err).
		Op("FooDooer").
		With("mydata", "myvalue").
		With("moredata", 5)

When used with github.com/getlantern/ops, Error captures its current context and propagates that data for use in calling layers.

When used with github.com/getlantern/golog, Error provides stacktraces:

Hello World
	at github.com/getlantern/errors.TestNewWithCause (errors_test.go:999)
	at testing.tRunner (testing.go:999)
	at runtime.goexit (asm_amd999.s:999)
Caused by: World
	at github.com/getlantern/errors.buildCause (errors_test.go:999)
	at github.com/getlantern/errors.TestNewWithCause (errors_test.go:999)
	at testing.tRunner (testing.go:999)
	at runtime.goexit (asm_amd999.s:999)
Caused by: orld
Caused by: ld
	at github.com/getlantern/errors.buildSubSubCause (errors_test.go:999)
	at github.com/getlantern/errors.buildSubCause (errors_test.go:999)
	at github.com/getlantern/errors.buildCause (errors_test.go:999)
	at github.com/getlantern/errors.TestNewWithCause (errors_test.go:999)
	at testing.tRunner (testing.go:999)
	at runtime.goexit (asm_amd999.s:999)
Caused by: d

It's the caller's responsibility to avoid race conditions accessing the same error instance from multiple goroutines.

Index

• type Error
  • func New(desc string, args ...interface{}) Error
  • func NewOffset(offset int, desc string, args ...interface{}) Error
  • func Wrap(err error) Error

Types

type Error

type Error interface {
	error
	context.Contextual

	// ErrorClean returns a non-parameterized version of the error whenever
	// possible. For example, if the error text is:
	//
	//     unable to dial www.google.com caused by: i/o timeout
	//
	// ErrorClean might return:
	//
	//     unable to dial %v caused by: %v
	//
	// This can be useful when performing analytics on the error.
	ErrorClean() string

	// MultiLinePrinter implements the interface golog.MultiLine
	MultiLinePrinter() func(buf *bytes.Buffer) bool

	// Op attaches a hint of the operation triggers this Error. Many error types
	// returned by net and os package have Op pre-filled.
	Op(op string) Error

	// With attaches arbitrary field to the error. keys will be normalized as
	// underscore_divided_words, so all characters except letters and numbers will
	// be replaced with underscores, and all letters will be lowercased.
	With(key string, value interface{}) Error

	// RootCause returns the bottom-most cause of this Error. If the Error
	// resulted from wrapping a plain error, the wrapped error will be returned as
	// the cause.
	RootCause() error
}

Error wraps system and application defined errors in unified structure for reporting and logging. It's not meant to be created directly. User New(), Wrap() and Report() instead.

func New

func New(desc string, args ...interface{}) Error

New creates an Error with supplied description and format arguments to the description. If any of the arguments is an error, we use that as the cause.

func NewOffset

func NewOffset(offset int, desc string, args ...interface{}) Error

NewOffset is like New but offsets the stack by the given offset. This is useful for utilities like golog that may create errors on behalf of others.

func Wrap

func Wrap(err error) Error

Wrap creates an Error based on the information in an error instance. It returns nil if the error passed in is nil, so we can simply call errors.Wrap(s.l.Close()) regardless there's an error or not. If the error is already wrapped, it is returned as is.