errors

package
v3.0.0+incompatible Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 15, 2019 License: Apache-2.0 Imports: 6 Imported by: 0

README

Errors

Package is a fork of https://github.com/pkg/errors with additional functions for improving the relationship between structured logging and error handling in go.

Adding structured context to an error

Wraps the original error while providing structured context data

_, err := ioutil.ReadFile(fileName)
if err != nil {
        return errors.WithContext{"file": fileName}.Wrap(err, "read failed")
}

Retrieving the structured context

Using errors.WithContext{} stores the provided context for later retrieval by upstream code or structured logging systems

// Pass to logrus as structured logging
logrus.WithFields(errors.ToLogrus(err)).Error("open file error")

Stack information on the source of the error is also included

context := errors.ToMap(err)
context == map[string]interface{}{
      "file": "my-file.txt",
      "go-func": "loadFile()",
      "go-line": 146,
      "go-file": "with_context_example.go"
}

Conforms to the Causer interface

Errors wrapped with errors.WithContext{} are compatible with errors wrapped by github.com/pkg/errors

switch err := errors.Cause(err).(type) {
case *MyError:
        // handle specifically
default:
        // unknown error
}

Proper Usage

The context wrapped by errors.WithContext{} is not intended to be used to by code to decide how an error should be handled. It is a convenience where the failure is well known, but the context is dynamic. In other words, you know the database returned an unrecoverable query error, but creating a new error type with the details of each query error is overkill ErrorFetchPage{}, ErrorFetchAll{}, ErrorFetchAuthor{}, etc...

As an example

func (r *Repository) FetchAuthor(isbn string) (Author, error) {
    // Returns ErrorNotFound{} if not exist
    book, err := r.fetchBook(isbn)
    if err != nil {
        return nil, errors.WithContext{"isbn": isbn}.Wrap(err, "while fetching book")
    }
    // Returns ErrorNotFound{} if not exist
    author, err := r.fetchAuthorByBook(book)
    if err != nil {
        return nil, errors.WithContext{"book": book}.Wrap(err, "while fetching author")
    }
    return author, nil
}

You should continue to create and inspect error types

type ErrorAuthorNotFound struct {}

func isNotFound(err error) {
    _, ok := err.(*ErrorAuthorNotFound)
    return ok
}

func main() {
    r := Repository{}
    author, err := r.FetchAuthor("isbn-213f-23422f52356")
    if err != nil {
        // Fetch the original Cause() and determine if the error is recoverable
        if isNotFound(error.Cause(err)) {
                author, err := r.AddBook("isbn-213f-23422f52356", "charles", "darwin")
        }
        if err != nil {
                logrus.WithFields(errors.ToLogrus(err)).Errorf("while fetching author - %s", err)
                os.Exit(1)
        }
    }
    fmt.Printf("Author %+v\n", author)
}

Context for concrete error types

If the error implements the errors.HasContext interface the context can be retrieved

context, ok := err.(errors.HasContext)
if ok {
    fmt.Println(context.Context())
}

This makes it easy for error types to provide their context information.

type ErrorBookNotFound struct {
   ISBN string
}
// Implements the `HasContext` interface
func (e *ErrorBookNotFound) func Context() map[string]interface{} {
   return map[string]interface{}{
       "isbn": e.ISBN,
   }
}

Now we can create the error and logrus knows how to retrieve the context

func (* Repository) FetchBook(isbn string) (*Book, error) {
    var book Book
    err := r.db.Query("SELECT * FROM books WHERE isbn = ?").One(&book)
    if err != nil {
        return nil, ErrorBookNotFound{ISBN: isbn}
    }
}

func main() {
    r := Repository{}
    book, err := r.FetchBook("isbn-213f-23422f52356")
    if err != nil {
        logrus.WithFields(errors.ToLogrus(err)).Errorf("while fetching book - %s", err)
        os.Exit(1)
    }
    fmt.Printf("Book %+v\n", book)
}

A Complete example

The following is a complete example using http://github.com/mailgun/logrus-hooks/kafkahook to marshal the context into ES fields.

package main

import (
    "github.com/mailgun/holster/errors"
    "github.com/mailgun/logrus-hooks/kafkahook"
    "github.com/sirupsen/logrus"
    "log"
    "io/ioutil"
)

func OpenWithError(fileName string) error {
    _, err := ioutil.ReadFile(fileName)
    if err != nil {
            // pass the filename up via the error context
            return errors.WithContext{
                "file": fileName,
            }.Wrap(err, "read failed")
    }
    return nil
}

func main() {
    // Init the kafka hook logger
    hook, err := kafkahook.New(kafkahook.Config{
        Endpoints: []string{"kafka-n01", "kafka-n02"},
        Topic:     "udplog",
    })
    if err != nil {
        log.Fatal(err)
    }

    // Add the hook to logrus
    logrus.AddHook(hook)

    // Create an error and log it
    if err := OpenWithError("/tmp/non-existant.file"); err != nil {
        // This log line will show up in ES with the additional fields
        //
        // excText: "read failed"
        // excValue: "read failed: open /tmp/non-existant.file: no such file or directory"
        // excType: "*errors.WithContext"
        // filename: "/src/to/main.go"
        // funcName: "main()"
        // lineno: 25
        // context.file: "/tmp/non-existant.file"
        // context.domain.id: "some-id"
        // context.foo: "bar"
        logrus.WithFields(logrus.Fields{
            "domain.id": "some-id",
            "foo": "bar",
            "err": err,
        }).Error("log messge")
    }
}

Documentation

Overview

Package errors provides simple error handling primitives.

The traditional error handling idiom in Go is roughly akin to 

if err != nil {
        return err
}

which applied recursively up the call stack results in error reports without context or debugging information. The errors package allows programmers to add context to the failure path in their code in a way that does not destroy the original value of the error.

Adding context to an error

The errors.Wrap function returns a new error that adds context to the original error by recording a stack trace at the point Wrap is called, and the supplied message. For example 

_, err := ioutil.ReadAll(r)
if err != nil {
        return errors.Wrap(err, "read failed")
}

If additional control is required the errors.WithStack and errors.WithMessage functions destructure errors.Wrap into its component operations of annotating an error with a stack trace and an a message, respectively.

Retrieving the cause of an error

Using errors.Wrap constructs a stack of errors, adding context to the preceding error. Depending on the nature of the error it may be necessary to reverse the operation of errors.Wrap to retrieve the original error for inspection. Any error value which implements this interface 

type causer interface {
        Cause() error
}

can be inspected by errors.Cause. errors.Cause will recursively retrieve the topmost error which does not implement causer, which is assumed to be the original cause. For example: 

switch err := errors.Cause(err).(type) {
case *MyError:
        // handle specifically
default:
        // unknown error
}

causer interface is not exported by this package, but is considered a part of stable public API.

Formatted printing of errors

All error values returned from this package implement fmt.Formatter and can be formatted by the fmt package. The following verbs are supported 

%s    print the error. If the error has a Cause it will be
      printed recursively
%v    see %s
%+v   extended format. Each Frame of the error's StackTrace will
      be printed in detail.

Retrieving the stack trace of an error or wrapper

New, Errorf, Wrap, and Wrapf record a stack trace at the point they are invoked. This information can be retrieved with the following interface. 

type stackTracer interface {
        StackTrace() errors.StackTrace
}

Where errors.StackTrace is defined as 

type StackTrace []Frame

The Frame type represents a call site in the stack trace. Frame supports the fmt.Formatter interface that can be used for printing information about the stack trace of this error. For example: 

if err, ok := err.(stackTracer); ok {
        for _, f := range err.StackTrace() {
                fmt.Printf("%+s:%d", f)
        }
}

stackTracer interface is not exported by this package, but is considered a part of stable public API.

See the documentation for Frame.Format for more details.

Example (StackTrace) 
package main

import (
	"fmt"

	"github.com/pkg/errors"
)

func fn() error {
	e1 := errors.New("error")
	e2 := errors.Wrap(e1, "inner")
	e3 := errors.Wrap(e2, "middle")
	return errors.Wrap(e3, "outer")
}

func main() {
	type stackTracer interface {
		StackTrace() errors.StackTrace
	}

	err, ok := errors.Cause(fn()).(stackTracer)
	if !ok {
		panic("oops, err does not implement stackTracer")
	}

	st := err.StackTrace()
	fmt.Printf("%+v", st[0:2]) // top two frames

	// Example output:
	// github.com/pkg/errors_test.fn
	//	/home/dfc/src/github.com/pkg/errors/example_test.go:47
	// github.com/pkg/errors_test.Example_stackTrace
	//	/home/dfc/src/github.com/pkg/errors/example_test.go:127
}

Output:

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func Cause 

func Cause(err error) error

Cause returns the underlying cause of the error, if possible. An error value has a cause if it implements the following interface: 

type causer interface {
       Cause() error
}

If the error does not implement Cause, the original error will be returned. If the error is nil, nil will be returned without further investigation.

Example 
package main

import (
	"fmt"

	"github.com/pkg/errors"
)

func fn() error {
	e1 := errors.New("error")
	e2 := errors.Wrap(e1, "inner")
	e3 := errors.Wrap(e2, "middle")
	return errors.Wrap(e3, "outer")
}

func main() {
	err := fn()
	fmt.Println(err)
	fmt.Println(errors.Cause(err))

}

Output:

outer: middle: inner: error
error
Example (Printf) 
package main

import (
	"fmt"

	"github.com/pkg/errors"
)

func main() {
	err := errors.Wrap(func() error {
		return func() error {
			return errors.Errorf("hello %s", fmt.Sprintf("world"))
		}()
	}(), "failed")

	fmt.Printf("%v", err)

}

Output:

failed: hello world

func Errorf 

func Errorf(format string, args ...interface{}) error

Errorf formats according to a format specifier and returns the string as a value that satisfies error. Errorf also records the stack trace at the point it was called.

Example (Extended) 
package main

import (
	"fmt"

	"github.com/pkg/errors"
)

func main() {
	err := errors.Errorf("whoops: %s", "foo")
	fmt.Printf("%+v", err)

	// Example output:
	// whoops: foo
	// github.com/pkg/errors_test.ExampleErrorf
	//         /home/dfc/src/github.com/pkg/errors/example_test.go:101
	// testing.runExample
	//         /home/dfc/go/src/testing/example.go:114
	// testing.RunExamples
	//         /home/dfc/go/src/testing/example.go:38
	// testing.(*M).Run
	//         /home/dfc/go/src/testing/testing.go:744
	// main.main
	//         /github.com/pkg/errors/_test/_testmain.go:102
	// runtime.main
	//         /home/dfc/go/src/runtime/proc.go:183
	// runtime.goexit
	//         /home/dfc/go/src/runtime/asm_amd64.s:2059
}

Output:

func New 

func New(message string) error

New returns an error with the supplied message. New also records the stack trace at the point it was called.

Example 
package main

import (
	"fmt"

	"github.com/pkg/errors"
)

func main() {
	err := errors.New("whoops")
	fmt.Println(err)

}

Output:

whoops
Example (Printf) 
package main

import (
	"fmt"

	"github.com/pkg/errors"
)

func main() {
	err := errors.New("whoops")
	fmt.Printf("%+v", err)

	// Example output:
	// whoops
	// github.com/pkg/errors_test.ExampleNew_printf
	//         /home/dfc/src/github.com/pkg/errors/example_test.go:17
	// testing.runExample
	//         /home/dfc/go/src/testing/example.go:114
	// testing.RunExamples
	//         /home/dfc/go/src/testing/example.go:38
	// testing.(*M).Run
	//         /home/dfc/go/src/testing/testing.go:744
	// main.main
	//         /github.com/pkg/errors/_test/_testmain.go:106
	// runtime.main
	//         /home/dfc/go/src/runtime/proc.go:183
	// runtime.goexit
	//         /home/dfc/go/src/runtime/asm_amd64.s:2059
}

Output:

func ToLogrus 

func ToLogrus(err error) logrus.Fields

Returns the context and stacktrace information for the underlying error as logrus.Fields{} returns empty logrus.Fields{} if err has no context or no stacktrace 

logrus.WithFields(errors.ToLogrus(err)).WithField("tid", 1).Error(err)

func ToMap 

func ToMap(err error) map[string]interface{}

Returns the context for the underlying error as map[string]interface{} If no context is available returns nil

func WithMessage 

func WithMessage(err error, message string) error

WithMessage annotates err with a new message. If err is nil, WithMessage returns nil.

Example 
package main

import (
	"fmt"

	"github.com/pkg/errors"
)

func main() {
	cause := errors.New("whoops")
	err := errors.WithMessage(cause, "oh noes")
	fmt.Println(err)

}

Output:

oh noes: whoops

func WithStack 

func WithStack(err error) error

WithStack annotates err with a stack trace at the point WithStack was called. If err is nil, WithStack returns nil.

Example 
package main

import (
	"fmt"

	"github.com/pkg/errors"
)

func main() {
	cause := errors.New("whoops")
	err := errors.WithStack(cause)
	fmt.Println(err)

}

Output:

whoops
Example (Printf) 
package main

import (
	"fmt"

	"github.com/pkg/errors"
)

func main() {
	cause := errors.New("whoops")
	err := errors.WithStack(cause)
	fmt.Printf("%+v", err)

	// Example Output:
	// whoops
	// github.com/pkg/errors_test.ExampleWithStack_printf
	//         /home/fabstu/go/src/github.com/pkg/errors/example_test.go:55
	// testing.runExample
	//         /usr/lib/go/src/testing/example.go:114
	// testing.RunExamples
	//         /usr/lib/go/src/testing/example.go:38
	// testing.(*M).Run
	//         /usr/lib/go/src/testing/testing.go:744
	// main.main
	//         github.com/pkg/errors/_test/_testmain.go:106
	// runtime.main
	//         /usr/lib/go/src/runtime/proc.go:183
	// runtime.goexit
	//         /usr/lib/go/src/runtime/asm_amd64.s:2086
	// github.com/pkg/errors_test.ExampleWithStack_printf
	//         /home/fabstu/go/src/github.com/pkg/errors/example_test.go:56
	// testing.runExample
	//         /usr/lib/go/src/testing/example.go:114
	// testing.RunExamples
	//         /usr/lib/go/src/testing/example.go:38
	// testing.(*M).Run
	//         /usr/lib/go/src/testing/testing.go:744
	// main.main
	//         github.com/pkg/errors/_test/_testmain.go:106
	// runtime.main
	//         /usr/lib/go/src/runtime/proc.go:183
	// runtime.goexit
	//         /usr/lib/go/src/runtime/asm_amd64.s:2086
}

Output:

func Wrap 

func Wrap(err error, message string) error

Wrap returns an error annotating err with a stack trace at the point Wrap is called, and the supplied message. If err is nil, Wrap returns nil.

Example 
package main

import (
	"fmt"

	"github.com/pkg/errors"
)

func main() {
	cause := errors.New("whoops")
	err := errors.Wrap(cause, "oh noes")
	fmt.Println(err)

}

Output:

oh noes: whoops
Example (Extended) 
package main

import (
	"fmt"

	"github.com/pkg/errors"
)

func fn() error {
	e1 := errors.New("error")
	e2 := errors.Wrap(e1, "inner")
	e3 := errors.Wrap(e2, "middle")
	return errors.Wrap(e3, "outer")
}

func main() {
	err := fn()
	fmt.Printf("%+v\n", err)

	// Example output:
	// error
	// github.com/pkg/errors_test.fn
	//         /home/dfc/src/github.com/pkg/errors/example_test.go:47
	// github.com/pkg/errors_test.ExampleCause_printf
	//         /home/dfc/src/github.com/pkg/errors/example_test.go:63
	// testing.runExample
	//         /home/dfc/go/src/testing/example.go:114
	// testing.RunExamples
	//         /home/dfc/go/src/testing/example.go:38
	// testing.(*M).Run
	//         /home/dfc/go/src/testing/testing.go:744
	// main.main
	//         /github.com/pkg/errors/_test/_testmain.go:104
	// runtime.main
	//         /home/dfc/go/src/runtime/proc.go:183
	// runtime.goexit
	//         /home/dfc/go/src/runtime/asm_amd64.s:2059
	// github.com/pkg/errors_test.fn
	// 	  /home/dfc/src/github.com/pkg/errors/example_test.go:48: inner
	// github.com/pkg/errors_test.fn
	//        /home/dfc/src/github.com/pkg/errors/example_test.go:49: middle
	// github.com/pkg/errors_test.fn
	//      /home/dfc/src/github.com/pkg/errors/example_test.go:50: outer
}

Output:

func Wrapf 

func Wrapf(err error, format string, args ...interface{}) error

Wrapf returns an error annotating err with a stack trace at the point Wrapf is call, and the format specifier. If err is nil, Wrapf returns nil.

Example 
package main

import (
	"fmt"

	"github.com/pkg/errors"
)

func main() {
	cause := errors.New("whoops")
	err := errors.Wrapf(cause, "oh noes #%d", 2)
	fmt.Println(err)

}

Output:

oh noes #2: whoops

Types

type CauseError 

type CauseError struct {
	// contains filtered or unexported fields
}

func NewCauseError 

func NewCauseError(err error, depth ...int) *CauseError

Creates a new error that becomes the cause even if 'err' is a wrapped error but preserves the Context() and StackTrace() information. This allows the user to create a concrete error type without losing context 

// Our new concrete type encapsulates CauseError
type RetryError struct {
	errors.CauseError
}

func NewRetryError(err error) *RetryError {
	return &RetryError{errors.NewCauseError(err, 1)}
}

// Returns true if the error is of type RetryError
func IsRetryError(err error) bool {
	err = errors.Cause(err)
	_, ok := err.(*RetryError)
	return ok
}

func (*CauseError) Context 

func (e *CauseError) Context() map[string]interface{}

func (*CauseError) Error 

func (e *CauseError) Error() string

func (*CauseError) StackTrace 

func (e *CauseError) StackTrace() pkg.StackTrace

type HasContext 

type HasContext interface {
	Context() map[string]interface{}
}

Implement this interface to pass along unstructured context to the logger

type HasFormat 

type HasFormat interface {
	Format(st fmt.State, verb rune)
}

True if the interface has the format method (from fmt package)

type WithContext 

type WithContext map[string]interface{}

Creates errors that conform to the `HasContext` interface

func (WithContext) Error 

func (c WithContext) Error(msg string) error

func (WithContext) Errorf 

func (c WithContext) Errorf(format string, args ...interface{}) error

func (WithContext) Wrap 

func (c WithContext) Wrap(err error, msg string) error

Wrap returns an error annotating err with a stack trace at the point Wrap is called, and the supplied message. If err is nil, Wrap returns nil.

func (WithContext) Wrapf 

func (c WithContext) Wrapf(err error, format string, args ...interface{}) error

Wrapf returns an error annotating err with a stack trace at the point Wrapf is call, and the format specifier. If err is nil, Wrapf returns nil.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.