Add a field factory for stacktraces (uber-go#20)

* Add a field factory for stacktraces

Add a field factory that wraps `runtime.Stack`, so that users don't need
to pick a byte size for their stacktraces. The wrapper attempts to
re-use a buffer from the pool, but allocates if it's necessary to
capture the whole stacktrace.

Note that the Stack() function is *really* expensive - casting the trace
to a string costs an allocation, but just taking a stacktrace is ~10
microseconds (roughly the same amount of time as logging 100
non-stacktrace fields).

* Update from CR

Author: akshayjshah

field.go

@@ -92,6 +92,23 @@ func Err(err error) Field {
 	return String("error", err.Error())
 }
 
+// Stack constructs a Field that stores a stacktrace of the current goroutine
+// under the key "stacktrace". Keep in mind that taking a stacktrace is
+// extremely expensive (relatively speaking); this function both makes an
+// allocation and takes ~10 microseconds.
+func Stack() Field {
+	// Try to avoid allocating a buffer.
+	enc := newJSONEncoder()
+	bs := enc.bytes[:cap(enc.bytes)]
+	// Returning the stacktrace as a string costs an allocation, but saves us
+	// from expanding the Field union struct to include a byte slice. Since
+	// taking a stacktrace is already so expensive (~10us), the extra allocation
+	// is okay.
+	field := String("stacktrace", takeStacktrace(bs, false))
+	enc.Free()
+	return field
+}
+
 // Duration constructs a Field with the given key and value. It represents
 // durations as an integer number of nanoseconds.
 func Duration(key string, val time.Duration) Field {

field_test.go

@@ -22,11 +22,13 @@ package zap
 
 import (
 	"errors"
+	"strings"
 	"sync"
 	"testing"
 	"time"
 
 	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
 )
 
 type fakeUser struct{ name string }
@@ -129,3 +131,14 @@ func TestNestField(t *testing.T) {
 	nest := Nest("foo", String("name", "phil"), Int("age", 42))
 	assertCanBeReused(t, nest)
 }
+
+func TestStackField(t *testing.T) {
+	enc := newJSONEncoder()
+	defer enc.Free()
+
+	Stack().addTo(enc)
+	output := string(enc.bytes)
+
+	require.True(t, strings.HasPrefix(output, `"stacktrace":`), "Stacktrace added under an unexpected key.")
+	assert.Contains(t, output[13:], "zap.TestStackField", "Expected stacktrace to contain caller.")
+}

logger_bench_test.go

@@ -114,6 +114,12 @@ func BenchmarkErrorField(b *testing.B) {
 	})
 }
 
+func BenchmarkStackField(b *testing.B) {
+	withBenchedLogger(b, func(log zap.Logger) {
+		log.Info("Error.", zap.Stack())
+	})
+}
+
 func BenchmarkObjectField(b *testing.B) {
 	// Expect an extra allocation here, since casting the user struct to the
 	// zap.Marshaler interface costs an alloc.

stacktrace.go

@@ -0,0 +1,42 @@
+// 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 "runtime"
+
+// takeStacktrace attempts to use the provided byte slice to take a stacktrace.
+// If the provided slice isn't large enough, takeStacktrace will allocate
+// successively larger slices until it can capture the whole stack.
+func takeStacktrace(buf []byte, includeAllGoroutines bool) string {
+	if len(buf) == 0 {
+		// We may have been passed a nil byte slice.
+		buf = make([]byte, 1024)
+	}
+	n := runtime.Stack(buf, includeAllGoroutines)
+	for n >= len(buf) {
+		// Buffer wasn't large enough, allocate a larger one. No need to copy
+		// previous buffer's contents.
+		size := 2 * n
+		buf = make([]byte, size)
+		n = runtime.Stack(buf, includeAllGoroutines)
+	}
+	return string(buf[:n])
+}

stacktrace_test.go

@@ -0,0 +1,40 @@
+// 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 (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestTakeStacktrace(t *testing.T) {
+	// Even if we pass a tiny buffer, takeStacktrace should allocate until it
+	// can capture the whole stacktrace.
+	traceNil := takeStacktrace(nil, false)
+	traceTiny := takeStacktrace(make([]byte, 1), false)
+	for _, trace := range []string{traceNil, traceTiny} {
+		// The top frame should be takeStacktrace.
+		assert.Contains(t, trace, "zap.takeStacktrace", "Stacktrace should contain the takeStacktrace function.")
+		// The stacktrace should also capture its immediate caller.
+		assert.Contains(t, trace, "TestTakeStacktrace", "Stacktrace should contain the test function.")
+	}
+}