Introduce UseCallerSkipForStacktrace & StackSkip

* UseCallerSkipForStacktrace configures the Logger to honor CallerSkip
when taking stacktraces.
* StackSkip is similar to Stack but allows
skipping frames from the top of the stack

Fixes uber-go#512, fixes uber-go#727

field.go

@@ -368,7 +368,20 @@ func Stack(key string) Field {
 	// from expanding the zapcore.Field union struct to include a byte slice. Since
 	// taking a stacktrace is already so expensive (~10us), the extra allocation
 	// is okay.
-	return String(key, takeStacktrace())
+	return String(key, takeStacktrace(nil))
+}
+
+// StackSkip constructs a field that stores a stacktrace of the current
+// goroutine under provided key, skipping the given number of frames from the
+// top of the stacktrace. Keep in mind that taking a stacktrace is eager and
+// expensive (relatively speaking); this function both makes an allocation and
+// takes about two microseconds.
+func StackSkip(key string, skip int) Field {
+	// Returning the stacktrace as a string costs an allocation, but saves us
+	// from expanding the zapcore.Field union struct to include a byte slice. Since
+	// taking a stacktrace is already so expensive (~10us), the extra allocation
+	// is okay.
+	return String(key, takeStacktrace(&skip))
 }
 
 // Duration constructs a field with the given key and value. The encoder

field_test.go

@@ -259,6 +259,6 @@ func TestStackField(t *testing.T) {
 	f := Stack("stacktrace")
 	assert.Equal(t, "stacktrace", f.Key, "Unexpected field key.")
 	assert.Equal(t, zapcore.StringType, f.Type, "Unexpected field type.")
-	assert.Equal(t, takeStacktrace(), f.String, "Unexpected stack trace")
+	assert.Equal(t, takeStacktrace(nil), f.String, "Unexpected stack trace")
 	assertCanBeReused(t, f)
 }

logger.go

@@ -48,7 +48,8 @@ type Logger struct {
 	addCaller bool
 	addStack  zapcore.LevelEnabler
 
-	callerSkip int
+	callerSkip            int
+	useCallerSkipForStack bool
 }
 
 // New constructs a new Logger from the provided zapcore.Core and Options. If
@@ -304,7 +305,11 @@ func (log *Logger) check(lvl zapcore.Level, msg string) *zapcore.CheckedEntry {
 		}
 	}
 	if log.addStack.Enabled(ce.Entry.Level) {
-		ce.Entry.Stack = Stack("").String
+		if log.useCallerSkipForStack {
+			ce.Entry.Stack = StackSkip("", log.callerSkip).String
+		} else {
+			ce.Entry.Stack = Stack("").String
+		}
 	}
 
 	return ce

options.go

@@ -119,6 +119,14 @@ func AddStacktrace(lvl zapcore.LevelEnabler) Option {
 	})
 }
 
+// UseCallerSkipForStacktrace configures the logger to use the number of frames
+// that should be skipped for caller (CallerSkip) annotation when taking stacktraces.
+func UseCallerSkipForStacktrace(enabled bool) Option {
+	return optionFunc(func(log *Logger) {
+		log.useCallerSkipForStack = enabled
+	})
+}
+
 // IncreaseLevel increase the level of the logger. It has no effect if
 // the passed in level tries to decrease the level of the logger.
 func IncreaseLevel(lvl zapcore.LevelEnabler) Option {

stacktrace.go

@@ -43,7 +43,7 @@ var (
 	_zapStacktraceVendorContains = addPrefix("/vendor/", _zapStacktracePrefixes...)
 )
 
-func takeStacktrace() string {
+func takeStacktrace(skip *int) string {
 	buffer := bufferpool.Get()
 	defer buffer.Free()
 	programCounters := _stacktracePool.Get().(*programCounters)
@@ -69,13 +69,22 @@ func takeStacktrace() string {
 	// Note: On the last iteration, frames.Next() returns false, with a valid
 	// frame, but we ignore this frame. The last frame is a a runtime frame which
 	// adds noise, since it's only either runtime.main or runtime.goexit.
+	toSkip := 0
+	if skip != nil {
+		toSkip = *skip
+	}
 	for frame, more := frames.Next(); more; frame, more = frames.Next() {
 		if skipZapFrames && isZapFrame(frame.Function) {
 			continue
 		} else {
 			skipZapFrames = false
 		}
 
+		if toSkip > 0 {
+			toSkip--
+			continue
+		}
+
 		if i != 0 {
 			buffer.AppendByte('\n')
 		}

stacktrace_test.go

@@ -29,7 +29,7 @@ import (
 )
 
 func TestTakeStacktrace(t *testing.T) {
-	trace := takeStacktrace()
+	trace := takeStacktrace(nil)
 	lines := strings.Split(trace, "\n")
 	require.True(t, len(lines) > 0, "Expected stacktrace to have at least one frame.")
 	assert.Contains(
@@ -70,6 +70,6 @@ func TestIsZapFrame(t *testing.T) {
 
 func BenchmarkTakeStacktrace(b *testing.B) {
 	for i := 0; i < b.N; i++ {
-		takeStacktrace()
+		takeStacktrace(nil)
 	}
 }