[FAB-6386] Update error handling documentation

This CR updates the error handling documentation to reflect the
(relatively) newly vendored github.com/pkg/errors, its usage, and
general guidelines for use within Fabric code.

Change-Id: I8f727e2489a267611fa50238d9a2d848335beac0
Signed-off-by: Will Lahti <wtlahti@us.ibm.com>

Author: wlahti

docs/source/error-handling.rst

@@ -3,148 +3,85 @@ Error handling
 
 General Overview
 ----------------
-The Hyperledger Fabric error handling framework can be found in the source
-repository under **common/errors**. It defines a new type of error,
-CallStackError, to use in place of the standard error type provided by Go.
-
-A CallStackError consists of the following:
-
-- Component code - a name for the general area of the code that is generating
-  the error. Component codes should consist of three uppercase letters. Numerics
-  and special characters are not allowed. A set of component codes is defined
-  in common/errors/codes.go
-- Reason code - a short code to help identify the reason the error occurred.
-  Reason codes should consist of three numeric values. Letters and special
-  characters are not allowed. A set of reason codes is defined in
-  common/error/codes.go
-- Error code - the component code and reason code separated by a colon,
-  e.g. MSP:404
-- Error message - the text that describes the error. This is the same as the
-  input provided to ``fmt.Errorf()`` and ``Errors.New()``. If an error has been
-  wrapped into the current error, its message will be appended.
-- Callstack - the callstack at the time the error is created. If an error has
-  been wrapped into the current error, its error message and callstack will be
-  appended to retain the context of the wrapped error.
-
-The CallStackError interface exposes the following functions:
-
-- Error() - returns the error message with callstack appended
-- Message() - returns the error message (without callstack appended)
-- GetComponentCode() - returns the 3-character component code
-- GetReasonCode() - returns the 3-digit reason code
-- GetErrorCode() - returns the error code, which is "component:reason"
-- GetStack() - returns just the callstack
-- WrapError(error) - wraps the provided error into the CallStackError
+Hyperledger Fabric code should use the vendored package
+**github.com/pkg/errors** in place of the standard error type provided by Go.
+This package allows easy generation and display of stack traces with error
+messages.
 
 Usage Instructions
 ------------------
 
-The new error handling framework should be used in place of all calls to
-``fmt.Errorf()`` or ``Errors.new()``. Using this framework will provide error
-codes to check against as well as the option to generate a callstack that will be
-appended to the error message.
+**github.com/pkg/errors** should be used in place of all calls to
+``fmt.Errorf()`` or ``errors.New()``. Using this package will generate a
+call stack that will be appended to the error message.
 
-Using the framework is simple and will only require an easy tweak to your code.
+Using this package is simple and will only require easy tweaks to your code.
 
-First, you'll need to import **github.com/hyperledger/fabric/common/errors** into
-any file that uses this framework.
+First, you'll need to import **github.com/pkg/errors**.
 
-Let's take the following as an example from core/chaincode/chaincode_support.go:
+Next, update all errors that are generated by your code to use one of the error
+creation functions (errors.New(), errors.Errorf(), errors.WithMessage(),
+errors.Wrap(), errors.Wrapf().
 
-.. code:: go
-
-  err = fmt.Errorf("Error starting container: %s", err)
-
-For this error, we will simply call the constructor for Error and pass a
-component code, reason code, followed by the error message. At the end, we
-then call the ``WrapError()`` function, passing along the error itself.
-
-.. code:: go
-
-  fmt.Errorf("Error starting container: %s", err)
-
-becomes
-
-.. code:: go
-
-  errors.ErrorWithCallstack("CHA", "505", "Error starting container").WrapError(err)
-
-You could also just leave the message as is without any problems:
-
-.. code:: go
-
-  errors.ErrorWithCallstack("CHA", "505", "Error starting container: %s", err)
-
-With this usage you will be able to format the error message from the previous
-error into the new error, but will lose the ability to print the callstack (if
-the wrapped error is a CallStackError).
-
-A second example to highlight a scenario that involves formatting directives for
-parameters other than errors, while still wrapping an error, is as follows:
-
-.. code:: go
-
-  fmt.Errorf("failed to get deployment payload %s - %s", canName, err)
-
-becomes
-
-.. code:: go
-
-  errors.ErrorWithCallstack("CHA", "506", "Failed to get deployment payload %s", canName).WrapError(err)
+.. note:: See https://godoc.org/github.com/pkg/errors for complete documentation
+of the available error creation function. Also, refer to the General guidelines
+section below for more specific guidelines for using the package for Fabric
+code.
 
-Displaying error messages
--------------------------
+Finally, change the formatting directive for any logger or fmt.Printf() calls
+from ``%s`` to ``%+v`` to print the call stack along with the error message.
 
-Once the error has been created using the framework, displaying the error
-message is as simple as:
-
-.. code:: go
-
-  logger.Errorf(err)
-
-or
-
-.. code:: go
-
-  fmt.Println(err)
-
-or
+General guidelines for error handling in Hyperledger Fabric
+-----------------------------------------------------------
 
-.. code:: go
+- If you are servicing a user request, you should log the error and return it.
+- If the error comes from an external source, such as a Go library or vendored
+  package, wrap the error using errors.Wrap() to generate a call stack for the
+  error.
+- If the error comes from another Fabric function, add further context, if
+  desired, to the error message using errors.WithMessage() while leaving the
+  call stack unaffected.
+- A panic should not be allowed to propagate to other packages.
 
-  fmt.Printf("%s\n", err)
+Example program
+---------------
 
-An example from peer/common/common.go:
+The following example program provides a clear demonstration of using the
+package:
 
 .. code:: go
 
-  errors.ErrorWithCallstack("PER", "404", "Error trying to connect to local peer").WrapError(err)
-
-would display the error message:
-
-.. code:: bash
-
-  PER:404 - Error trying to connect to local peer
-  Caused by: grpc: timed out when dialing
-
-.. note:: The callstacks have not been displayed for this example for the sake of
-          brevity.
-
-General guidelines for error handling in Hyperledger Fabric
------------------------------------------------------------
-
-- If it is some sort of best effort thing you are doing, you should log the
-  error and ignore it.
-- If you are servicing a user request, you should log the error and return it.
-- If the error comes from elsewhere, you have the choice to wrap the error
-  or not. Typically, it's best to not wrap the error and simply return
-  it as is. However, for certain cases where a utility function is called,
-  wrapping the error with a new component and reason code can help an end user
-  understand where the error is really occurring without inspecting the callstack.
-- A panic should be handled within the same layer by throwing an internal error
-  code/start a recovery process and should not be allowed to propagate to other
-  packages.
+  package main
+
+  import (
+    "fmt"
+
+    "github.com/pkg/errors"
+  )
+
+  func wrapWithStack() error {
+    err := createError()
+    // do this when error comes from external source (go lib or vendor)
+    return errors.Wrap(err, "wrapping an error with stack")
+  }
+  func wrapWithoutStack() error {
+    err := createError()
+    // do this when error comes from internal Fabric since it already has stack trace
+    return errors.WithMessage(err, "wrapping an error without stack")
+  }
+  func createError() error {
+    return errors.New("original error")
+  }
+
+  func main() {
+    err := createError()
+    fmt.Printf("print error without stack: %s\n\n", err)
+    fmt.Printf("print error with stack: %+v\n\n", err)
+    err = wrapWithoutStack()
+    fmt.Printf("%+v\n\n", err)
+    err = wrapWithStack()
+    fmt.Printf("%+v\n\n", err)
+  }
 
 .. Licensed under Creative Commons Attribution 4.0 International License
    https://creativecommons.org/licenses/by/4.0/
-