Merge branch 'master' into stdlib-context

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"
 }

log/stdlib.go

@@ -39,7 +39,7 @@ func TimestampKey(key string) StdlibAdapterOption {
 	return func(a *StdlibAdapter) { a.timestampKey = key }
 }
 
-// FileKey sets the key for the file and line field. By default, it's "file".
+// FileKey sets the key for the file and line field. By default, it's "caller".
 func FileKey(key string) StdlibAdapterOption {
 	return func(a *StdlibAdapter) { a.fileKey = key }
 }
@@ -55,7 +55,7 @@ func NewStdlibAdapter(logger Logger, options ...StdlibAdapterOption) io.Writer {
 	a := StdlibAdapter{
 		Logger:       logger,
 		timestampKey: "ts",
-		fileKey:      "file",
+		fileKey:      "caller",
 		messageKey:   "msg",
 	}
 	for _, option := range options {

log/stdlib_test.go

@@ -35,9 +35,9 @@ func TestStdlibAdapterUsage(t *testing.T) {
 		log.Ldate:                              "ts=" + date + " msg=hello\n",
 		log.Ltime:                              "ts=" + time + " msg=hello\n",
 		log.Ldate | log.Ltime:                  "ts=\"" + date + " " + time + "\" msg=hello\n",
-		log.Lshortfile:                         "file=stdlib_test.go:44 msg=hello\n",
-		log.Lshortfile | log.Ldate:             "ts=" + date + " file=stdlib_test.go:44 msg=hello\n",
-		log.Lshortfile | log.Ldate | log.Ltime: "ts=\"" + date + " " + time + "\" file=stdlib_test.go:44 msg=hello\n",
+		log.Lshortfile:                         "caller=stdlib_test.go:44 msg=hello\n",
+		log.Lshortfile | log.Ldate:             "ts=" + date + " caller=stdlib_test.go:44 msg=hello\n",
+		log.Lshortfile | log.Ldate | log.Ltime: "ts=\"" + date + " " + time + "\" caller=stdlib_test.go:44 msg=hello\n",
 	} {
 		buf.Reset()
 		stdlog.SetFlags(flag)
@@ -58,11 +58,11 @@ func TestStdLibAdapterExtraction(t *testing.T) {
 		"2009/01/23 01:23:23: hello":                       "ts=\"2009/01/23 01:23:23\" msg=hello\n",
 		"01:23:23: hello":                                  "ts=01:23:23 msg=hello\n",
 		"2009/01/23 01:23:23.123123: hello":                "ts=\"2009/01/23 01:23:23.123123\" msg=hello\n",
-		"2009/01/23 01:23:23.123123 /a/b/c/d.go:23: hello": "ts=\"2009/01/23 01:23:23.123123\" file=/a/b/c/d.go:23 msg=hello\n",
-		"01:23:23.123123 /a/b/c/d.go:23: hello":            "ts=01:23:23.123123 file=/a/b/c/d.go:23 msg=hello\n",
-		"2009/01/23 01:23:23 /a/b/c/d.go:23: hello":        "ts=\"2009/01/23 01:23:23\" file=/a/b/c/d.go:23 msg=hello\n",
-		"2009/01/23 /a/b/c/d.go:23: hello":                 "ts=2009/01/23 file=/a/b/c/d.go:23 msg=hello\n",
-		"/a/b/c/d.go:23: hello":                            "file=/a/b/c/d.go:23 msg=hello\n",
+		"2009/01/23 01:23:23.123123 /a/b/c/d.go:23: hello": "ts=\"2009/01/23 01:23:23.123123\" caller=/a/b/c/d.go:23 msg=hello\n",
+		"01:23:23.123123 /a/b/c/d.go:23: hello":            "ts=01:23:23.123123 caller=/a/b/c/d.go:23 msg=hello\n",
+		"2009/01/23 01:23:23 /a/b/c/d.go:23: hello":        "ts=\"2009/01/23 01:23:23\" caller=/a/b/c/d.go:23 msg=hello\n",
+		"2009/01/23 /a/b/c/d.go:23: hello":                 "ts=2009/01/23 caller=/a/b/c/d.go:23 msg=hello\n",
+		"/a/b/c/d.go:23: hello":                            "caller=/a/b/c/d.go:23 msg=hello\n",
 	} {
 		buf.Reset()
 		fmt.Fprint(writer, input)

log/value.go

@@ -42,11 +42,11 @@ func Timestamp(t func() time.Time) Valuer {
 var (
 	// DefaultTimestamp is a Valuer that returns the current wallclock time,
 	// respecting time zones, when bound.
-	DefaultTimestamp Valuer = func() interface{} { return time.Now().Format(time.RFC3339) }
+	DefaultTimestamp Valuer = func() interface{} { return time.Now().Format(time.RFC3339Nano) }
 
 	// DefaultTimestampUTC is a Valuer that returns the current time in UTC
 	// when bound.
-	DefaultTimestampUTC Valuer = func() interface{} { return time.Now().UTC().Format(time.RFC3339) }
+	DefaultTimestampUTC Valuer = func() interface{} { return time.Now().UTC().Format(time.RFC3339Nano) }
 )
 
 // Caller returns a Valuer that returns a file and line from a specified depth

metrics/discard/discard.go

@@ -25,6 +25,9 @@ func (g gauge) With(labelValues ...string) metrics.Gauge { return g }
 // Set implements Gauge.
 func (g gauge) Set(value float64) {}
 
+// Add implements metrics.Gauge.
+func (g gauge) Add(delta float64) {}
+
 type histogram struct{}
 
 // NewHistogram returns a new no-op histogram.

metrics/doc.go

@@ -91,7 +91,6 @@
 //    expvar      1    atomic                 atomic                 synthetic, batch, in-place expose
 //    influx      n    custom                 custom                 custom
 //    prometheus  n    native                 native                 native
-//    circonus    1    native                 native                 native
 //    pcp         1    native                 native                 native
 //
 package metrics