Enhance package log docs.

log/doc.go

@@ -90,4 +90,27 @@
 // handled atomically within the wrapped logger, but it typically serializes
 // both the formatting and output logic. Use a SyncLogger if the formatting
 // logger may perform multiple writes per log event.
+//
+// Error Handling
+//
+// This package relies on the practice of wrapping or decorating loggers with
+// other loggers to provide composable pieces of functionality. It also means
+// that Logger.Log must return an error because some
+// implementations—especially those that output log data to an io.Writer—may
+// encounter errors that cannot be handled locally. This in turn means that
+// Loggers that wrap other loggers should return errors from the wrapped
+// logger up the stack.
+//
+// Fortunately, the decorator pattern also provides a way to avoid the
+// necessity to check for errors every time an application calls Logger.Log.
+// An application required to panic whenever its Logger encounters
+// an error could initialize its logger as follows.
+//
+//    fmtlogger := log.NewLogfmtLogger(log.NewSyncWriter(os.Stdout))
+//    logger := log.LoggerFunc(func(keyvals ...interface{}) error {
+//        if err := fmtlogger.Log(keyvals...); err != nil {
+//            panic(err)
+//        }
+//        return nil
+//    })
 package log

log/example_test.go

@@ -1,7 +1,9 @@
 package log_test
 
 import (
+	"math/rand"
 	"os"
+	"sync"
 	"time"
 
 	"github.com/go-kit/kit/log"
@@ -96,7 +98,40 @@ func Example_debugInfo() {
 	logger.Log("call", "third")
 
 	// Output:
-	// time=2015-02-03T10:00:01Z caller=example_test.go:91 call=first
-	// time=2015-02-03T10:00:02Z caller=example_test.go:92 call=second
-	// time=2015-02-03T10:00:03Z caller=example_test.go:96 call=third
+	// time=2015-02-03T10:00:01Z caller=example_test.go:93 call=first
+	// time=2015-02-03T10:00:02Z caller=example_test.go:94 call=second
+	// time=2015-02-03T10:00:03Z caller=example_test.go:98 call=third
+}
+
+func Example_syncWriter() {
+	w := log.NewSyncWriter(os.Stdout)
+	logger := log.NewLogfmtLogger(w)
+
+	type Task struct {
+		ID int
+	}
+
+	var wg sync.WaitGroup
+
+	RunTask := func(task Task, logger log.Logger) {
+		logger.Log("taskID", task.ID, "event", "starting task")
+
+		time.Sleep(time.Duration(rand.Intn(200)) * time.Millisecond)
+
+		logger.Log("taskID", task.ID, "event", "task complete")
+		wg.Done()
+	}
+
+	wg.Add(2)
+
+	go RunTask(Task{ID: 1}, logger)
+	go RunTask(Task{ID: 2}, logger)
+
+	wg.Wait()
+
+	// Unordered output:
+	// taskID=1 event="starting task"
+	// taskID=2 event="starting task"
+	// taskID=1 event="task complete"
+	// taskID=2 event="task complete"
 }