Provide an API for extracting details from errors

[axw]

When an error value is translated to an apm.Error (i.e. via NewError, CaptureError, or Recovered), we currently extract details from various error types in the standard library:

apm-agent-go/error.go

Lines 358 to 415 in 525c5c4

	// Set Module, Type, Attributes, and Code.
	switch err := err.(type) {
	case *net.OpError:
	e.typePackagePath, e.typeName = "net", "OpError"
	setAttr("op", err.Op)
	setAttr("net", err.Net)
	setAttr("source", err.Source)
	setAttr("addr", err.Addr)
	case *os.LinkError:
	e.typePackagePath, e.typeName = "os", "LinkError"
	setAttr("op", err.Op)
	setAttr("old", err.Old)
	setAttr("new", err.New)
	case *os.PathError:
	e.typePackagePath, e.typeName = "os", "PathError"
	setAttr("op", err.Op)
	setAttr("path", err.Path)
	case *os.SyscallError:
	e.typePackagePath, e.typeName = "os", "SyscallError"
	setAttr("syscall", err.Syscall)
	case syscall.Errno:
	e.typePackagePath, e.typeName = "syscall", "Errno"
	e.codeNumber = float64(uintptr(err))
	default:
	t := reflect.TypeOf(err)
	if t.Name() == "" && t.Kind() == reflect.Ptr {
	t = t.Elem()
	}
	e.typePackagePath, e.typeName = t.PkgPath(), t.Name()
	// If the error implements Type, use that to
	// override the type name determined through
	// reflection.
	if err, ok := err.(interface {
	Type() string
	}); ok {
	e.typeName = err.Type()
	}
	// If the error implements a Code method, use
	// that to set the exception code.
	switch err := err.(type) {
	case interface {
	Code() string
	}:
	e.codeString = err.Code()
	case interface {
	Code() float64
	}:
	e.codeNumber = err.Code()
	}
	}
	if errTemporary(err) {
	setAttr("temporary", true)
	}
	if errTimeout(err) {
	setAttr("timeout", true)
	}

Some libraries define their own error types, and contain interesting details that we should surface. For example, https://godoc.org/github.com/mongodb/mongo-go-driver/x/network/command#Error contains an error code, labels, and error name that we should ideally surface.

We should provide an API whereby instrumentation modules can register an error type and function to use to extract information from it, e.g. by wrapping the error such that it provides methods like "Code" and "Type".

[axw]

Something like this:

diff --git a/error.go b/error.go                                                                    
index 9ba0e4ec..a50a5fec 100644                                                                     
--- a/error.go                                                                                      
+++ b/error.go                                                                                      
@@ -38,8 +38,20 @@ var (                                                                            
        runtimeFrameType        = reflect.TypeOf(runtime.Frame{})                                   
        errorsStackTraceUintptr = uintptrType.ConvertibleTo(reflect.TypeOf(*new(errors.Frame)))     
        errorsStackTraceFrame   = reflect.TypeOf(*new(errors.Frame)).ConvertibleTo(runtimeFrameType)
+       errorTypeWrappers       = make(map[reflect.Type]func(error) error)                          
 )                                                                                                  
                                                                                                    
+// RegisterErrorWrapper registers function f with type t, which should                             
+// be the named type of an error. When errors of type t are presented to                           
+// the tracer, then f will be used to wrap the value in order to influence                         
+// how its details are extracted.                                                                  
+//                                                                                                 
+// This function must not be called concurrently with creation of Error                            
+// values; it is intended to be used at program initialisaton time.                                
+func RegisterErrorWrapper(t reflect.Type, f func(error) error) {                                   
+       errorTypeWrappers[t] = f                                                                    
+}                                                                                                  
+                                                                                                   
 // Recovered creates an Error with t.NewError(err), where                                          
 // err is either v (if v implements error), or otherwise                                           
 // fmt.Errorf("%v", v). The value v is expected to have                                            
@@ -380,6 +392,15 @@ func initException(e *exceptionData, err error) {                              
                e.codeNumber = float64(uintptr(err))                                                
        default:                                                                                    
                t := reflect.TypeOf(err)                                                            
+               if wrap, ok := errorTypeWrappers[t]; ok {                                           
+                       err = wrap(err)                                                             
+               }                                                                                   
+                                                                                                   
+               // TODO(axw) define more interfaces which the error can                             
+               // implement to specify the package path and type name.                             
+               //                                                                                  
+               // Only do the below bits if those interfaces are not                               
+               // implemented.                                                                     
                if t.Name() == "" && t.Kind() == reflect.Ptr {                                      
                        t = t.Elem()                                                                
                }                                                                                   
@@ -406,6 +427,12 @@ func initException(e *exceptionData, err error) {                              
                }:                                                                                  
                        e.codeNumber = err.Code()                                                   
                }                                                                                   
+                                                                                                   
+               if err, ok := err.(interface {                                                      
+                       Attrs(func(string, interface{}))                                            
+               }); ok {                                                                            
+                       err.Attrs(setAttr)                                                          
+               }                                                                                   
        }                                                                                           
        if errTemporary(err) {                                                                      
                setAttr("temporary", true)