feat(log): Add structured field logging

log/log.go

@@ -1,3 +1,4 @@
+// Package log provides utilities for providing output to the user.
 package log
 
 import (
@@ -7,11 +8,32 @@ import (
 	logging "github.com/op/go-logging"
 )
 
+// Logger is a re-exported logger from `go-logging`. Originally, we provided
+// wrapper functions around the specific logging methods that we use, but this
+// causes the package, file, and line numbers to be useless (they all point to
+// the wrapper instead of the caller). Instead, we only use the documented log
+// levels below:
+//
+// _Debug_ messages are used for tracing execution and diagnosing unintended
+// error cases.
+//
+// _Notice_ messages are non-error events that the user should be informed of,
+// such as notifications that an action has occurred.
+//
+// _Warning_ messages are non-fatal error events that the user should be
+// informed of. Generally, the user can do something to fix these.
+//
+// _Fatal_ messages are non-recoverable errors, and cause an `os.Exit(1)`. They
+// should be used for foreseen error conditions that we cannot continue from.
+//
+// _Panic_ messages are errors that are unforeseen, should never happen, and
+// indicate that something has gone terribly wrong. They are akin to assertion
+// failures, and are generally only used as sanity checks for invariants.
 var Logger = logging.MustGetLogger("fossa-cli")
 
-var useSpinner bool
-
-// Initialize sets up logging modes.
+// Initialize configures logging. If `interactive` is true, then logging will
+// include colors and ANSI codes (e.g. spinners). If `debug` is true, then
+// logging will include debugging output.
 func Initialize(interactive, debug bool) {
 	// If `interactive`, then use ANSI codes (spinner + colors)
 	useSpinner = interactive
@@ -44,3 +66,27 @@ func Print(args ...interface{}) {
 func Printf(format string, args ...interface{}) {
 	fmt.Printf(format, args...)
 }
+
+type Fields map[string]interface{}
+
+type Entry struct {
+	Message string
+	Error   error
+	Fields  Fields
+}
+
+func (e Entry) String() string {
+	var fields string
+	for key, val := range e.Fields {
+		switch v := val.(type) {
+		case fmt.Stringer:
+			fields += fmt.Sprintf(" %s=%#v", key, v.String())
+		default:
+			fields += fmt.Sprintf(" %s=%#v", key, v)
+		}
+	}
+	if e.Error != nil {
+		return fmt.Sprintf("%s error=%#v %s", e.Message, e.Error, fields)
+	}
+	return fmt.Sprintf("%s%s", e.Message, fields)
+}

log/spinner.go

@@ -6,7 +6,10 @@ import (
 	"github.com/briandowns/spinner"
 )
 
-var s = spinner.New(spinner.CharSets[11], 100*time.Millisecond)
+var (
+	useSpinner bool
+	s          = spinner.New(spinner.CharSets[11], 100*time.Millisecond)
+)
 
 // ShowSpinner shows a progress spinner with a message.
 func ShowSpinner(message string) {