Update zap.NewJSON to use functional options (uber-go#23)

Default options are:

- Info

- Write logs to stdout

- Write logging errors to stderr

- No fields



Log levels implement the option interface so you can pass them directly.



Added examples for NewJSON that show default vs passing options.

Author: prashantv

benchmarks/zap_bench_test.go

@@ -51,7 +51,7 @@ var _jane = user{
 }
 
 func BenchmarkZapAddingFields(b *testing.B) {
-	logger := zap.NewJSON(zap.All, ioutil.Discard, ioutil.Discard)
+	logger := zap.NewJSON(zap.All, zap.Output(ioutil.Discard))
 	b.ResetTimer()
 	b.RunParallel(func(pb *testing.PB) {
 		for pb.Next() {
@@ -72,7 +72,7 @@ func BenchmarkZapAddingFields(b *testing.B) {
 }
 
 func BenchmarkZapWithAccumulatedContext(b *testing.B) {
-	logger := zap.NewJSON(zap.All, ioutil.Discard, ioutil.Discard,
+	logger := zap.NewJSON(zap.All, zap.Output(ioutil.Discard), zap.Fields(
 		zap.Int("int", 1),
 		zap.Int64("int64", 2),
 		zap.Float64("float", 3.0),
@@ -83,7 +83,7 @@ func BenchmarkZapWithAccumulatedContext(b *testing.B) {
 		zap.Duration("duration", time.Second),
 		zap.Object("user-defined type", _jane),
 		zap.String("another string", "done!"),
-	)
+	))
 	b.ResetTimer()
 	b.RunParallel(func(pb *testing.PB) {
 		for pb.Next() {
@@ -93,7 +93,7 @@ func BenchmarkZapWithAccumulatedContext(b *testing.B) {
 }
 
 func BenchmarkZapWithoutFields(b *testing.B) {
-	logger := zap.NewJSON(zap.All, ioutil.Discard, ioutil.Discard)
+	logger := zap.NewJSON(zap.All, zap.Output(ioutil.Discard))
 	b.ResetTimer()
 	b.RunParallel(func(pb *testing.PB) {
 		for pb.Next() {

example_test.go

@@ -21,15 +21,15 @@
 package zap_test
 
 import (
-	"os"
 	"time"
 
 	"github.com/uber-common/zap"
 )
 
 func Example() {
 	// Log in JSON, using zap's reflection-free JSON encoder.
-	logger := zap.NewJSON(zap.Info, os.Stdout, os.Stderr)
+	// The default options will log any Info or higher logs to standard out.
+	logger := zap.NewJSON()
 	// For repeatable tests, pretend that it's always 1970.
 	logger.StubTime()
 
@@ -53,20 +53,47 @@ func Example() {
 }
 
 func ExampleNest() {
-	logger := zap.NewJSON(zap.Info, os.Stdout, os.Stderr)
+	logger := zap.NewJSON()
 	// Stub the current time in tests.
 	logger.StubTime()
 
 	// We'd like the logging context to be {"outer":{"inner":42}}
-	logger.Debug("Nesting context.", zap.Nest("outer",
-		zap.Int("inner", 42),
-	))
-
-	// If we want to stop a field from being returned to a sync.Pool on use,
-	// use Keep.
 	nest := zap.Nest("outer", zap.Int("inner", 42))
 	logger.Info("Logging a nested field.", nest)
 
 	// Output:
 	// {"msg":"Logging a nested field.","level":"info","ts":0,"fields":{"outer":{"inner":42}}}
 }
+
+func ExampleNewJSON() {
+	// The default logger outputs to standard out and only writes logs that are
+	// Info level or higher.
+	logger := zap.NewJSON()
+	// Stub the current time in tests.
+	logger.StubTime()
+
+	// The default logger does not print Debug logs.
+	logger.Debug("this won't be printed")
+	logger.Info("This is an info log.")
+
+	// Output:
+	// {"msg":"This is an info log.","level":"info","ts":0,"fields":{}}
+}
+
+func ExampleNewJSON_options() {
+	// We can pass multiple options to the NewJSON method to configure
+	// the logging level, output location, or even the initial context.
+	logger := zap.NewJSON(
+		zap.Debug,
+		zap.Fields(zap.Int("count", 1)),
+	)
+	// Stub the current time in tests.
+	logger.StubTime()
+
+	logger.Debug("This is a debug log.")
+	logger.Info("This is an info log.")
+
+	// Output:
+	// {"msg":"This is a debug log.","level":"debug","ts":0,"fields":{"count":1}}
+	// {"msg":"This is an info log.","level":"info","ts":0,"fields":{"count":1}}
+}

logger.go

@@ -70,22 +70,26 @@ type jsonLogger struct {
 // NewJSON returns a logger that formats its output as JSON. Zap uses a
 // customized JSON encoder to avoid reflection and minimize allocations.
 //
-// Any passed fields are added to the logger as context.
-func NewJSON(lvl Level, sink, errSink io.Writer, fields ...Field) Logger {
-	if errSink == nil {
-		errSink = _defaultErrSink
-	}
-
-	integerLevel := int32(lvl)
+// By default, the logger will write Info logs or higher to standard
+// out. Any errors during logging will be written to standard error.
+//
+// Options can change the log level, the output location, or the initial
+// fields that should be added as context.
+func NewJSON(options ...Option) Logger {
+	defaultLevel := int32(Info)
 	jl := &jsonLogger{
-		level: &integerLevel,
 		enc:   newJSONEncoder(),
-		errW:  errSink,
-		w:     sink,
+		level: &defaultLevel,
+		errW:  _defaultErrSink,
+		w:     os.Stdout,
 	}
-	if err := jl.enc.AddFields(fields); err != nil {
-		jl.internalError(err.Error())
+
+	for _, opt := range options {
+		if err := opt.apply(jl); err != nil {
+			jl.internalError(err.Error())
+		}
 	}
+
 	return jl
 }
 

logger_bench_test.go

@@ -49,7 +49,7 @@ var _jane = user{
 }
 
 func withBenchedLogger(b *testing.B, f func(zap.Logger)) {
-	logger := zap.NewJSON(zap.All, ioutil.Discard, ioutil.Discard)
+	logger := zap.NewJSON(zap.All, zap.Output(ioutil.Discard))
 	b.ResetTimer()
 	b.RunParallel(func(pb *testing.PB) {
 		for pb.Next() {
@@ -152,7 +152,7 @@ func Benchmark10Fields(b *testing.B) {
 
 func Benchmark100Fields(b *testing.B) {
 	const batchSize = 50
-	logger := zap.NewJSON(zap.All, ioutil.Discard, ioutil.Discard)
+	logger := zap.NewJSON(zap.All, zap.Output(ioutil.Discard))
 
 	// Don't include allocating these helper slices in the benchmark. Since
 	// access to them isn't synchronized, we can't run the benchmark in

logger_test.go

@@ -23,18 +23,25 @@ package zap
 import (
 	"bytes"
 	"fmt"
-	"io/ioutil"
 	"os"
 	"strings"
 	"testing"
 
 	"github.com/stretchr/testify/assert"
 )
 
-func withJSONLogger(t testing.TB, f func(*jsonLogger, func() []string), fields ...Field) {
+func opts(opts ...Option) []Option {
+	return opts
+}
+
+func withJSONLogger(t testing.TB, opts []Option, f func(*jsonLogger, func() []string)) {
 	sink := &bytes.Buffer{}
 	errSink := &bytes.Buffer{}
-	jl := NewJSON(All, sink, errSink, fields...)
+
+	allOpts := make([]Option, 0, 3+len(opts))
+	allOpts = append(allOpts, All, Output(sink), ErrorOutput(errSink))
+	allOpts = append(allOpts, opts...)
+	jl := NewJSON(allOpts...)
 	jl.StubTime()
 
 	f(jl.(*jsonLogger), func() []string { return strings.Split(sink.String(), "\n") })
@@ -56,16 +63,15 @@ func assertFields(t testing.TB, jl Logger, getOutput func() []string, expectedFi
 }
 
 func TestJSONLoggerSetLevel(t *testing.T) {
-	withJSONLogger(t, func(jl *jsonLogger, _ func() []string) {
+	withJSONLogger(t, nil, func(jl *jsonLogger, _ func() []string) {
 		assert.Equal(t, All, jl.Level(), "Unexpected initial level.")
 		jl.SetLevel(Debug)
 		assert.Equal(t, Debug, jl.Level(), "Unexpected level after SetLevel.")
 	})
 }
 
 func TestJSONLoggerEnabled(t *testing.T) {
-	withJSONLogger(t, func(jl *jsonLogger, _ func() []string) {
-		jl.SetLevel(Info)
+	withJSONLogger(t, opts(Info), func(jl *jsonLogger, _ func() []string) {
 		assert.False(t, jl.Enabled(Debug), "Debug logs shouldn't be enabled at Info level.")
 		assert.True(t, jl.Enabled(Info), "Info logs should be enabled at Info level.")
 		assert.True(t, jl.Enabled(Warn), "Warn logs should be enabled at Info level.")
@@ -85,7 +91,7 @@ func TestJSONLoggerEnabled(t *testing.T) {
 func TestJSONLoggerConcurrentLevelMutation(t *testing.T) {
 	// Trigger races for non-atomic level mutations.
 	proceed := make(chan struct{})
-	jl := NewJSON(Info, ioutil.Discard, ioutil.Discard)
+	jl := NewJSON()
 
 	for i := 0; i < 50; i++ {
 		go func(l Logger) {
@@ -101,51 +107,53 @@ func TestJSONLoggerConcurrentLevelMutation(t *testing.T) {
 }
 
 func TestJSONLoggerInitialFields(t *testing.T) {
-	withJSONLogger(t, func(jl *jsonLogger, output func() []string) {
+	fieldOpts := opts(Fields(Int("foo", 42), String("bar", "baz")))
+	withJSONLogger(t, fieldOpts, func(jl *jsonLogger, output func() []string) {
 		assertFields(t, jl, output, `{"foo":42,"bar":"baz"}`)
-	}, Int("foo", 42), String("bar", "baz"))
+	})
 }
 
 func TestJSONLoggerWith(t *testing.T) {
-	withJSONLogger(t, func(jl *jsonLogger, output func() []string) {
+	fieldOpts := opts(Fields(Int("foo", 42)))
+	withJSONLogger(t, fieldOpts, func(jl *jsonLogger, output func() []string) {
 		// Child loggers should have copy-on-write semantics, so two children
 		// shouldn't stomp on each other's fields or affect the parent's fields.
 		jl.With(String("one", "two")).Debug("")
 		jl.With(String("three", "four")).Debug("")
 		assertFields(t, jl, output, `{"foo":42,"one":"two"}`, `{"foo":42,"three":"four"}`, `{"foo":42}`)
-	}, Int("foo", 42))
+	})
 }
 
 func TestJSONLoggerDebug(t *testing.T) {
-	withJSONLogger(t, func(jl *jsonLogger, output func() []string) {
+	withJSONLogger(t, nil, func(jl *jsonLogger, output func() []string) {
 		jl.Debug("foo")
 		assertMessage(t, "debug", "foo", output()[0])
 	})
 }
 
 func TestJSONLoggerInfo(t *testing.T) {
-	withJSONLogger(t, func(jl *jsonLogger, output func() []string) {
+	withJSONLogger(t, nil, func(jl *jsonLogger, output func() []string) {
 		jl.Info("foo")
 		assertMessage(t, "info", "foo", output()[0])
 	})
 }
 
 func TestJSONLoggerWarn(t *testing.T) {
-	withJSONLogger(t, func(jl *jsonLogger, output func() []string) {
+	withJSONLogger(t, nil, func(jl *jsonLogger, output func() []string) {
 		jl.Warn("foo")
 		assertMessage(t, "warn", "foo", output()[0])
 	})
 }
 
 func TestJSONLoggerError(t *testing.T) {
-	withJSONLogger(t, func(jl *jsonLogger, output func() []string) {
+	withJSONLogger(t, nil, func(jl *jsonLogger, output func() []string) {
 		jl.Error("foo")
 		assertMessage(t, "error", "foo", output()[0])
 	})
 }
 
 func TestJSONLoggerPanic(t *testing.T) {
-	withJSONLogger(t, func(jl *jsonLogger, output func() []string) {
+	withJSONLogger(t, nil, func(jl *jsonLogger, output func() []string) {
 		assert.Panics(t, func() {
 			jl.Panic("foo")
 		})
@@ -154,7 +162,7 @@ func TestJSONLoggerPanic(t *testing.T) {
 }
 
 func TestJSONLoggerNoOpsDisabledLevels(t *testing.T) {
-	withJSONLogger(t, func(jl *jsonLogger, output func() []string) {
+	withJSONLogger(t, nil, func(jl *jsonLogger, output func() []string) {
 		jl.SetLevel(Warn)
 		jl.Info("silence!")
 		assert.Equal(t, []string{""}, output(), "Expected logging at a disabled level to produce no output.")
@@ -168,7 +176,7 @@ func TestJSONLoggerInternalErrorHandlingNoSink(t *testing.T) {
 
 	buf := &bytes.Buffer{}
 
-	jl := NewJSON(All, buf, nil, Object("user", fakeUser{"fail"}))
+	jl := NewJSON(All, Output(buf), Fields(Object("user", fakeUser{"fail"})))
 	jl.StubTime()
 	output := func() []string { return strings.Split(buf.String(), "\n") }
 
@@ -183,7 +191,7 @@ func TestJSONLoggerInternalErrorHandlingWithSink(t *testing.T) {
 	buf := &bytes.Buffer{}
 	errBuf := &bytes.Buffer{}
 
-	jl := NewJSON(All, buf, errBuf, Object("user", fakeUser{"fail"}))
+	jl := NewJSON(All, Output(buf), ErrorOutput(errBuf), Fields(Object("user", fakeUser{"fail"})))
 	jl.StubTime()
 	output := func() []string { return strings.Split(buf.String(), "\n") }
 
@@ -197,7 +205,7 @@ func TestJSONLoggerInternalErrorHandlingWithSink(t *testing.T) {
 func TestJSONLoggerRuntimeLevelChange(t *testing.T) {
 	// Test that changing a logger's level also changes the level of all
 	// ancestors and descendants.
-	grandparent := NewJSON(Info, ioutil.Discard, ioutil.Discard, Int("generation", 1))
+	grandparent := NewJSON(Fields(Int("generation", 1)))
 	parent := grandparent.With(Int("generation", 2))
 	child := parent.With(Int("generation", 3))
 

options.go

@@ -0,0 +1,64 @@
+// Copyright (c) 2016 Uber Technologies, Inc.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+// THE SOFTWARE.
+
+package zap
+
+import "io"
+
+// Option is used to set options for the logger.
+type Option interface {
+	apply(*jsonLogger) error
+}
+
+// optionFunc wraps a func so it satisfies the Option interface.
+type optionFunc func(*jsonLogger) error
+
+func (f optionFunc) apply(jl *jsonLogger) error {
+	return f(jl)
+}
+
+// This allows any Level to be used as an option.
+func (l Level) apply(jl *jsonLogger) error {
+	jl.SetLevel(l)
+	return nil
+}
+
+// Fields sets the initial fields for the logger.
+func Fields(fields ...Field) Option {
+	return optionFunc(func(jl *jsonLogger) error {
+		return jl.enc.AddFields(fields)
+	})
+}
+
+// Output sets the destination for the logger's output.
+func Output(w io.Writer) Option {
+	return optionFunc(func(jl *jsonLogger) error {
+		jl.w = w
+		return nil
+	})
+}
+
+// ErrorOutput sets the destination for errors generated by the logger.
+func ErrorOutput(w io.Writer) Option {
+	return optionFunc(func(jl *jsonLogger) error {
+		jl.errW = w
+		return nil
+	})
+}