Merge branch 'uber-go:master' into feature/custom-mapping-level

.github/workflows/go.yml

@@ -41,7 +41,9 @@ jobs:
       run: make cover
 
     - name: Upload coverage to codecov.io
-      uses: codecov/codecov-action@v3
+      uses: codecov/codecov-action@v4
+      env:
+        CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
 
   lint:
     name: Lint
@@ -56,7 +58,7 @@ jobs:
         go-version: 1.22.x
         cache: false  # managed by golangci-lint
 
-    - uses: golangci/golangci-lint-action@v3
+    - uses: golangci/golangci-lint-action@v4
       name: Install golangci-lint
       with:
         version: latest

CHANGELOG.md

@@ -3,6 +3,20 @@ All notable changes to this project will be documented in this file.
 
 This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 1.27.0 (20 Feb 2024)
+Enhancements:
+* [#1378][]: Add `WithLazy` method for `SugaredLogger`.
+* [#1399][]: zaptest: Add `NewTestingWriter` for customizing TestingWriter with more flexibility than `NewLogger`.
+* [#1406][]: Add `Log`, `Logw`, `Logln` methods for `SugaredLogger`.
+* [#1416][]: Add `WithPanicHook` option for testing panic logs.
+
+Thanks to @defval, @dimmo, @arxeiss, and @MKrupauskas for their contributions to this release.
+
+[#1378]: https://github.com/uber-go/zap/pull/1378
+[#1399]: https://github.com/uber-go/zap/pull/1399
+[#1406]: https://github.com/uber-go/zap/pull/1406
+[#1416]: https://github.com/uber-go/zap/pull/1416
+
 ## 1.26.0 (14 Sep 2023)
 Enhancements:
 * [#1297][]: Add Dict as a Field.

logger.go

@@ -43,6 +43,7 @@ type Logger struct {
 
 	development bool
 	addCaller   bool
+	onPanic     zapcore.CheckWriteHook // default is WriteThenPanic
 	onFatal     zapcore.CheckWriteHook // default is WriteThenFatal
 
 	name        string
@@ -345,27 +346,12 @@ func (log *Logger) check(lvl zapcore.Level, msg string) *zapcore.CheckedEntry {
 	// Set up any required terminal behavior.
 	switch ent.Level {
 	case zapcore.PanicLevel:
-		ce = ce.After(ent, zapcore.WriteThenPanic)
+		ce = ce.After(ent, terminalHookOverride(zapcore.WriteThenPanic, log.onPanic))
 	case zapcore.FatalLevel:
-		onFatal := log.onFatal
-		// nil or WriteThenNoop will lead to continued execution after
-		// a Fatal log entry, which is unexpected. For example,
-		//
-		//   f, err := os.Open(..)
-		//   if err != nil {
-		//     log.Fatal("cannot open", zap.Error(err))
-		//   }
-		//   fmt.Println(f.Name())
-		//
-		// The f.Name() will panic if we continue execution after the
-		// log.Fatal.
-		if onFatal == nil || onFatal == zapcore.WriteThenNoop {
-			onFatal = zapcore.WriteThenFatal
-		}
-		ce = ce.After(ent, onFatal)
+		ce = ce.After(ent, terminalHookOverride(zapcore.WriteThenFatal, log.onFatal))
 	case zapcore.DPanicLevel:
 		if log.development {
-			ce = ce.After(ent, zapcore.WriteThenPanic)
+			ce = ce.After(ent, terminalHookOverride(zapcore.WriteThenPanic, log.onPanic))
 		}
 	}
 
@@ -430,3 +416,20 @@ func (log *Logger) check(lvl zapcore.Level, msg string) *zapcore.CheckedEntry {
 
 	return ce
 }
+
+func terminalHookOverride(defaultHook, override zapcore.CheckWriteHook) zapcore.CheckWriteHook {
+	// A nil or WriteThenNoop hook will lead to continued execution after
+	// a Panic or Fatal log entry, which is unexpected. For example,
+	//
+	//   f, err := os.Open(..)
+	//   if err != nil {
+	//     log.Fatal("cannot open", zap.Error(err))
+	//   }
+	//   fmt.Println(f.Name())
+	//
+	// The f.Name() will panic if we continue execution after the log.Fatal.
+	if override == nil || override == zapcore.WriteThenNoop {
+		return defaultHook
+	}
+	return override
+}

logger_test.go

@@ -836,6 +836,130 @@ func TestLoggerFatalOnNoop(t *testing.T) {
 	assert.Equal(t, 1, exitStub.Code, "must exit with status 1 for WriteThenNoop")
 }
 
+func TestLoggerCustomOnPanic(t *testing.T) {
+	tests := []struct {
+		msg          string
+		level        zapcore.Level
+		opts         []Option
+		finished     bool
+		want         []observer.LoggedEntry
+		recoverValue any
+	}{
+		{
+			msg:      "panic with nil hook",
+			level:    PanicLevel,
+			opts:     opts(WithPanicHook(nil)),
+			finished: false,
+			want: []observer.LoggedEntry{
+				{
+					Entry:   zapcore.Entry{Level: PanicLevel, Message: "foobar"},
+					Context: []Field{},
+				},
+			},
+			recoverValue: "foobar",
+		},
+		{
+			msg:      "panic with noop hook",
+			level:    PanicLevel,
+			opts:     opts(WithPanicHook(zapcore.WriteThenNoop)),
+			finished: false,
+			want: []observer.LoggedEntry{
+				{
+					Entry:   zapcore.Entry{Level: PanicLevel, Message: "foobar"},
+					Context: []Field{},
+				},
+			},
+			recoverValue: "foobar",
+		},
+		{
+			msg:      "no panic with goexit hook",
+			level:    PanicLevel,
+			opts:     opts(WithPanicHook(zapcore.WriteThenGoexit)),
+			finished: false,
+			want: []observer.LoggedEntry{
+				{
+					Entry:   zapcore.Entry{Level: PanicLevel, Message: "foobar"},
+					Context: []Field{},
+				},
+			},
+			recoverValue: nil,
+		},
+		{
+			msg:      "dpanic no panic in development mode with goexit hook",
+			level:    DPanicLevel,
+			opts:     opts(WithPanicHook(zapcore.WriteThenGoexit), Development()),
+			finished: false,
+			want: []observer.LoggedEntry{
+				{
+					Entry:   zapcore.Entry{Level: DPanicLevel, Message: "foobar"},
+					Context: []Field{},
+				},
+			},
+			recoverValue: nil,
+		},
+		{
+			msg:      "dpanic panic in development mode with noop hook",
+			level:    DPanicLevel,
+			opts:     opts(WithPanicHook(zapcore.WriteThenNoop), Development()),
+			finished: false,
+			want: []observer.LoggedEntry{
+				{
+					Entry:   zapcore.Entry{Level: DPanicLevel, Message: "foobar"},
+					Context: []Field{},
+				},
+			},
+			recoverValue: "foobar",
+		},
+		{
+			msg:      "dpanic no exit in production mode with goexit hook",
+			level:    DPanicLevel,
+			opts:     opts(WithPanicHook(zapcore.WriteThenPanic)),
+			finished: true,
+			want: []observer.LoggedEntry{
+				{
+					Entry:   zapcore.Entry{Level: DPanicLevel, Message: "foobar"},
+					Context: []Field{},
+				},
+			},
+			recoverValue: nil,
+		},
+		{
+			msg:      "dpanic no panic in production mode with panic hook",
+			level:    DPanicLevel,
+			opts:     opts(WithPanicHook(zapcore.WriteThenPanic)),
+			finished: true,
+			want: []observer.LoggedEntry{
+				{
+					Entry:   zapcore.Entry{Level: DPanicLevel, Message: "foobar"},
+					Context: []Field{},
+				},
+			},
+			recoverValue: nil,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.msg, func(t *testing.T) {
+			withLogger(t, InfoLevel, tt.opts, func(logger *Logger, logs *observer.ObservedLogs) {
+				var finished bool
+				recovered := make(chan any)
+				go func() {
+					defer func() {
+						recovered <- recover()
+					}()
+
+					logger.Log(tt.level, "foobar")
+					finished = true
+				}()
+
+				assert.Equal(t, tt.recoverValue, <-recovered, "unexpected value from recover()")
+				assert.Equal(t, tt.finished, finished, "expect goroutine finished state doesn't match")
+				assert.Equal(t, tt.want, logs.AllUntimed(), "unexpected logs")
+			})
+		})
+	}
+}
+
 func TestLoggerCustomOnFatal(t *testing.T) {
 	tests := []struct {
 		msg          string

options.go

@@ -132,6 +132,21 @@ func IncreaseLevel(lvl zapcore.LevelEnabler) Option {
 	})
 }
 
+// WithPanicHook sets a CheckWriteHook to run on Panic/DPanic logs.
+// Zap will call this hook after writing a log statement with a Panic/DPanic level.
+//
+// For example, the following builds a logger that will exit the current
+// goroutine after writing a Panic/DPanic log message, but it will not start a panic.
+//
+//	zap.New(core, zap.WithPanicHook(zapcore.WriteThenGoexit))
+//
+// This is useful for testing Panic/DPanic log output.
+func WithPanicHook(hook zapcore.CheckWriteHook) Option {
+	return optionFunc(func(log *Logger) {
+		log.onPanic = hook
+	})
+}
+
 // OnFatal sets the action to take on fatal logs.
 //
 // Deprecated: Use [WithFatalHook] instead.

sugar.go

@@ -137,6 +137,12 @@ func (s *SugaredLogger) Level() zapcore.Level {
 	return zapcore.LevelOf(s.base.core)
 }
 
+// Log logs the provided arguments at provided level.
+// Spaces are added between arguments when neither is a string.
+func (s *SugaredLogger) Log(lvl zapcore.Level, args ...interface{}) {
+	s.log(lvl, "", args, nil)
+}
+
 // Debug logs the provided arguments at [DebugLevel].
 // Spaces are added between arguments when neither is a string.
 func (s *SugaredLogger) Debug(args ...interface{}) {
@@ -180,6 +186,12 @@ func (s *SugaredLogger) Fatal(args ...interface{}) {
 	s.log(FatalLevel, "", args, nil)
 }
 
+// Logf formats the message according to the format specifier
+// and logs it at provided level.
+func (s *SugaredLogger) Logf(lvl zapcore.Level, template string, args ...interface{}) {
+	s.log(lvl, template, args, nil)
+}
+
 // Debugf formats the message according to the format specifier
 // and logs it at [DebugLevel].
 func (s *SugaredLogger) Debugf(template string, args ...interface{}) {
@@ -223,6 +235,12 @@ func (s *SugaredLogger) Fatalf(template string, args ...interface{}) {
 	s.log(FatalLevel, template, args, nil)
 }
 
+// Logw logs a message with some additional context. The variadic key-value
+// pairs are treated as they are in With.
+func (s *SugaredLogger) Logw(lvl zapcore.Level, msg string, keysAndValues ...interface{}) {
+	s.log(lvl, msg, nil, keysAndValues)
+}
+
 // Debugw logs a message with some additional context. The variadic key-value
 // pairs are treated as they are in With.
 //
@@ -270,6 +288,12 @@ func (s *SugaredLogger) Fatalw(msg string, keysAndValues ...interface{}) {
 	s.log(FatalLevel, msg, nil, keysAndValues)
 }
 
+// Logln logs a message at provided level.
+// Spaces are always added between arguments.
+func (s *SugaredLogger) Logln(lvl zapcore.Level, args ...interface{}) {
+	s.logln(lvl, args, nil)
+}
+
 // Debugln logs a message at [DebugLevel].
 // Spaces are always added between arguments.
 func (s *SugaredLogger) Debugln(args ...interface{}) {

sugar_test.go

@@ -311,9 +311,10 @@ func TestSugarStructuredLogging(t *testing.T) {
 			logger.With(context...).Warnw(tt.msg, extra...)
 			logger.With(context...).Errorw(tt.msg, extra...)
 			logger.With(context...).DPanicw(tt.msg, extra...)
+			logger.With(context...).Logw(WarnLevel, tt.msg, extra...)
 
-			expected := make([]observer.LoggedEntry, 5)
-			for i, lvl := range []zapcore.Level{DebugLevel, InfoLevel, WarnLevel, ErrorLevel, DPanicLevel} {
+			expected := make([]observer.LoggedEntry, 6)
+			for i, lvl := range []zapcore.Level{DebugLevel, InfoLevel, WarnLevel, ErrorLevel, DPanicLevel, WarnLevel} {
 				expected[i] = observer.LoggedEntry{
 					Entry:   zapcore.Entry{Message: tt.expectMsg, Level: lvl},
 					Context: expectedFields,
@@ -343,9 +344,10 @@ func TestSugarConcatenatingLogging(t *testing.T) {
 			logger.With(context...).Warn(tt.args...)
 			logger.With(context...).Error(tt.args...)
 			logger.With(context...).DPanic(tt.args...)
+			logger.With(context...).Log(InfoLevel, tt.args...)
 
-			expected := make([]observer.LoggedEntry, 5)
-			for i, lvl := range []zapcore.Level{DebugLevel, InfoLevel, WarnLevel, ErrorLevel, DPanicLevel} {
+			expected := make([]observer.LoggedEntry, 6)
+			for i, lvl := range []zapcore.Level{DebugLevel, InfoLevel, WarnLevel, ErrorLevel, DPanicLevel, InfoLevel} {
 				expected[i] = observer.LoggedEntry{
 					Entry:   zapcore.Entry{Message: tt.expect, Level: lvl},
 					Context: expectedFields,
@@ -379,9 +381,10 @@ func TestSugarTemplatedLogging(t *testing.T) {
 			logger.With(context...).Warnf(tt.format, tt.args...)
 			logger.With(context...).Errorf(tt.format, tt.args...)
 			logger.With(context...).DPanicf(tt.format, tt.args...)
+			logger.With(context...).Logf(ErrorLevel, tt.format, tt.args...)
 
-			expected := make([]observer.LoggedEntry, 5)
-			for i, lvl := range []zapcore.Level{DebugLevel, InfoLevel, WarnLevel, ErrorLevel, DPanicLevel} {
+			expected := make([]observer.LoggedEntry, 6)
+			for i, lvl := range []zapcore.Level{DebugLevel, InfoLevel, WarnLevel, ErrorLevel, DPanicLevel, ErrorLevel} {
 				expected[i] = observer.LoggedEntry{
 					Entry:   zapcore.Entry{Message: tt.expect, Level: lvl},
 					Context: expectedFields,
@@ -415,9 +418,10 @@ func TestSugarLnLogging(t *testing.T) {
 			logger.With(context...).Warnln(tt.args...)
 			logger.With(context...).Errorln(tt.args...)
 			logger.With(context...).DPanicln(tt.args...)
+			logger.With(context...).Logln(InfoLevel, tt.args...)
 
-			expected := make([]observer.LoggedEntry, 5)
-			for i, lvl := range []zapcore.Level{DebugLevel, InfoLevel, WarnLevel, ErrorLevel, DPanicLevel} {
+			expected := make([]observer.LoggedEntry, 6)
+			for i, lvl := range []zapcore.Level{DebugLevel, InfoLevel, WarnLevel, ErrorLevel, DPanicLevel, InfoLevel} {
 				expected[i] = observer.LoggedEntry{
 					Entry:   zapcore.Entry{Message: tt.expect, Level: lvl},
 					Context: expectedFields,