move from pkg/errors to std lib and support go 1.13 errors

Author: bzon

README.md

@@ -2,37 +2,35 @@
 
 # errors
 
-My drop-in replacement for `github.com/pkg/errors`. 
+A drop-in replacement for creating errors with OpenCensus instrumentation (OpenTelemetry soon).
+
+This package also supports the Go 1.13 `errors.As` and `errors.Is` methods. Check the examples in Go doc.
 
 I created this package to help me link the details of my Stackdriver traces with Stackdriver logs.
 
 * https://cloud.google.com/trace/docs/viewing-details
 * https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry
 * https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#LogEntrySourceLocation
 
-## Goals
-
-Add OpenCensus trace attributes when creating a new error.
-
-## Basic Usage
+## Getting Started
 
 Drop-in replacement. Creating an error.
 
 ```golang
-err := errors.New("msg") // Wrap .. Wrapf .. Errof ..
+err := errors.New("msg") // Wrap .. Wrapf .. Errorf ..
 ```
 
 Creating an error with context useful for monitoring.
 
 ```golang
 func main() {
-	_, span := trace.StartSpan(context.Background(), "ExampleNewT")
+	_, span := trace.StartSpan(context.Background(), "main")
 	defer span.End()
 
 	err := errors.NewT(span, "error")
 	fmt.Println(err)
 
-	if erctx, ok := err.(errors.Error); ok {
+	if erctx, ok := err.(errors.ErrorTracer); ok {
 		fmt.Println(erctx.SourceLocation().Function)
 		fmt.Println(erctx.SourceLocation().File)
 		fmt.Println(erctx.SourceLocation().Line)

errors.go

@@ -0,0 +1,298 @@
+package errors
+
+import (
+	"fmt"
+	"runtime"
+
+	"errors"
+
+	"go.opencensus.io/trace"
+)
+
+// Overwrite these values during build via -ldflags.
+var (
+	// VERSION is the app-global version.
+	VERSION = "UNKNOWN"
+
+	// COMMIT is the app-global commit id.
+	COMMIT = "UNKNOWN"
+
+	// BRANCH is the app-global git branch.
+	BRANCH = "UNKNOWN"
+)
+
+const (
+	wrappedFunctionCallDepth = 2
+)
+
+// Tracer represents an error that has TraceContext and SourceLocation.
+type Tracer interface {
+	SourceLocation() SourceLocation
+	TraceContext() TraceContext
+	SetTraceContext(trace.SpanContext)
+	SetSourceLocation(depth int)
+}
+
+// TraceContext is used to provide a tracing context to an object for logging purposes.
+// This is helpful for Developers to link Stackdriver traces to Stackdriver logs.
+// See https://cloud.google.com/trace/docs/viewing-details.
+// See https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry.
+type TraceContext struct {
+	TraceID string `json:"trace"`
+	SpanID  string `json:"spanId"`
+}
+
+// SourceLocation provides the information where the actual error happened in the code.
+// https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#LogEntrySourceLocation
+type SourceLocation struct {
+	Function string `json:"function"`
+	File     string `json:"file"`
+	Line     int    `json:"line"`
+	Version  string `json:"version,omitempty"`
+	Commit   string `json:"commit,omitempty"`
+	Branch   string `json:"branch,omitempty"`
+}
+
+// NewSourceLocation creates a SourceLocation using stdlib runtime.Caller.
+func NewSourceLocation(depth int) SourceLocation {
+	function, file, line, _ := runtime.Caller(depth)
+	return SourceLocation{
+		runtime.FuncForPC(function).Name(), file, line, VERSION, COMMIT, BRANCH,
+	}
+}
+
+// As is a drop-in replacement for errors.As method.
+func As(target error, dest interface{}) bool {
+	return errors.As(target, dest)
+}
+
+// Is is a drop-in replacement for errors.Is method.
+func Is(err, target error) bool {
+	return errors.Is(err, target)
+}
+
+// ErrorTracer represents an error with tracing.
+type ErrorTracer interface {
+	error
+	// Unwrap is used to implement the Go 1.13 error wrapping technique.
+	// This makes the implementation of ErrorTracer to make use of errors.Is and errors.As.
+	Unwrap() error
+	Tracer
+}
+
+// Compile time implementation check.
+var _ ErrorTracer = &errorContext{}
+
+type errorContext struct {
+	err            error
+	sourceLocation SourceLocation
+	traceContext   TraceContext
+}
+
+func (e *errorContext) Unwrap() error {
+	return e.err
+}
+
+func (e *errorContext) Error() string {
+	return e.err.Error()
+}
+
+func (e *errorContext) SourceLocation() SourceLocation {
+	return e.sourceLocation
+}
+
+func (e *errorContext) SetSourceLocation(depth int) {
+	e.sourceLocation = NewSourceLocation(depth)
+}
+
+func (e *errorContext) TraceContext() TraceContext {
+	return e.traceContext
+}
+
+func (e *errorContext) SetTraceContext(t trace.SpanContext) {
+	e.traceContext = TraceContext{
+		TraceID: t.TraceID.String(),
+		SpanID:  t.SpanID.String(),
+	}
+}
+
+// NewCaller wraps errors.New with a specified caller depth.
+func NewCaller(depth int, m string) error {
+	err := &errorContext{
+		err:            errors.New(m),
+		sourceLocation: NewSourceLocation(depth),
+	}
+	return err
+}
+
+// NewCallerT wraps errors.New with a specified caller depth and a span trace context.
+func NewCallerT(depth int, span *trace.Span, m string) error {
+	err := &errorContext{
+		err:            errors.New(m),
+		sourceLocation: NewSourceLocation(depth),
+	}
+	return annotate(err, span)
+}
+
+// NewCallerf wraps fmt.Errorf with a specified caller depth.
+func NewCallerf(depth int, m string, args ...interface{}) error {
+	err := &errorContext{
+		err:            fmt.Errorf(m, args...),
+		sourceLocation: NewSourceLocation(depth),
+	}
+	return err
+}
+
+// NewCallerfT wraps fmt.Errorf with a specified caller depth and a span trace context.
+func NewCallerfT(depth int, span *trace.Span, m string, args ...interface{}) error {
+	err := &errorContext{
+		err:            fmt.Errorf(m, args...),
+		sourceLocation: NewSourceLocation(depth),
+	}
+	return annotate(err, span)
+}
+
+// WrapCaller wraps fmt.Errorf with a specified caller depth.
+func WrapCaller(depth int, e error, m string) error {
+	err := &errorContext{
+		err:            fmt.Errorf("%s: %w", m, e),
+		sourceLocation: NewSourceLocation(depth),
+	}
+	return err
+}
+
+// WrapCallerT wraps fmt.Errorf with a specified caller depth with a span trace context.
+func WrapCallerT(depth int, span *trace.Span, e error, m string) error {
+	err := &errorContext{
+		err:            fmt.Errorf("%s: %w", m, e),
+		sourceLocation: NewSourceLocation(depth),
+	}
+	return annotate(err, span)
+}
+
+// WrapCallerf wraps fmt.Errorf with a specified caller depth.
+func WrapCallerf(depth int, e error, format string, args ...interface{}) error {
+	m := fmt.Sprintf(format, args...)
+	err := &errorContext{
+		err:            fmt.Errorf("%s: %w", m, e),
+		sourceLocation: NewSourceLocation(depth),
+	}
+	return err
+}
+
+// WrapCallerfT wraps fmt.Errorf with a specified caller depth with a span trace context.
+func WrapCallerfT(depth int, span *trace.Span, e error, format string, args ...interface{}) error {
+	m := fmt.Sprintf(format, args...)
+	err := &errorContext{
+		err:            fmt.Errorf("%s: %w", m, e),
+		sourceLocation: NewSourceLocation(depth),
+	}
+	return annotate(err, span)
+}
+
+// New is the drop-in replacement for errors.New.
+func New(m string) error {
+	err := &errorContext{
+		err:            errors.New(m),
+		sourceLocation: NewSourceLocation(wrappedFunctionCallDepth),
+	}
+	return err
+}
+
+// NewT wraps errors.New with a span trace context.
+func NewT(span *trace.Span, m string) error {
+	err := &errorContext{
+		err:            errors.New(m),
+		sourceLocation: NewSourceLocation(wrappedFunctionCallDepth),
+	}
+	return annotate(err, span)
+}
+
+// Errorf wraps fmt.Errorf.
+func Errorf(m string, args ...interface{}) error {
+	err := &errorContext{
+		err:            fmt.Errorf(m, args...),
+		sourceLocation: NewSourceLocation(wrappedFunctionCallDepth),
+	}
+	return err
+}
+
+// ErrorfT wraps fmt.Errorf with a span trace context.
+func ErrorfT(span *trace.Span, m string, args ...interface{}) error {
+	err := &errorContext{
+		err:            fmt.Errorf(m, args...),
+		sourceLocation: NewSourceLocation(wrappedFunctionCallDepth),
+	}
+	return annotate(err, span)
+}
+
+// Wrap wraps an error fmt.Errorf with `%w` without formatting.
+func Wrap(e error, m string) error {
+	err := &errorContext{
+		err:            fmt.Errorf("%s: %w", m, e),
+		sourceLocation: NewSourceLocation(wrappedFunctionCallDepth),
+	}
+	return err
+}
+
+// WrapT wraps an error with a span trace context.
+func WrapT(span *trace.Span, e error, m string) error {
+	err := &errorContext{
+		err:            fmt.Errorf("%s: %w", m, e),
+		sourceLocation: NewSourceLocation(wrappedFunctionCallDepth),
+	}
+	return annotate(err, span)
+}
+
+// Wrap wraps fmt.Errorf with `%w` with formatting.
+func Wrapf(e error, f string, args ...interface{}) error {
+	m := fmt.Sprintf(f, args...)
+	err := &errorContext{
+		err:            fmt.Errorf("%s: %w", m, e),
+		sourceLocation: NewSourceLocation(wrappedFunctionCallDepth),
+	}
+	return err
+}
+
+// WrapfT is Wrapf with a trace context.
+func WrapfT(span *trace.Span, e error, f string, args ...interface{}) error {
+	m := fmt.Sprintf(f, args...)
+	err := &errorContext{
+		err:            fmt.Errorf("%s: %w", m, e),
+		sourceLocation: NewSourceLocation(wrappedFunctionCallDepth),
+	}
+	return annotate(err, span)
+}
+
+func annotate(e *errorContext, span *trace.Span) error {
+	if span == nil {
+		return e
+	}
+
+	// Add the trace ID and span ID.
+	ctx := span.SpanContext()
+	e.traceContext = TraceContext{
+		TraceID: ctx.TraceID.String(),
+		SpanID:  ctx.SpanID.String(),
+	}
+
+	// Add OpenCensus span annotation.
+	src := e.SourceLocation()
+	span.Annotate(
+		[]trace.Attribute{
+			trace.StringAttribute("function", src.Function),
+			trace.StringAttribute("file", src.File),
+			trace.Int64Attribute("line", int64(src.Line)),
+			trace.StringAttribute("version", src.Version),
+			trace.StringAttribute("commit", src.Commit),
+			trace.StringAttribute("branch", src.Branch),
+		},
+		"Error: "+e.Error(),
+	)
+
+	// Generic error
+	span.SetStatus(trace.Status{
+		Code: trace.StatusCodeUnknown,
+	})
+	return e
+}