✨ pkg/log/zap: clarify zap level vs. logr verbosity

pkg/log/zap/zap.go

@@ -101,17 +101,19 @@ func newConsoleEncoder(opts ...EncoderConfigOption) zapcore.Encoder {
 	return zapcore.NewConsoleEncoder(encoderConfig)
 }
 
-// Level sets the the minimum enabled logging level e.g Debug, Info
-// See Options.Level
+// Level sets Options.Level, which configures the the minimum enabled logging level e.g Debug, Info.
+// A zap log level should be multiplied by -1 to get the logr verbosity.
+// For example, to get logr verbosity of 3, pass zapcore.Level(-3) to this Opts.
+// See https://pkg.go.dev/github.com/go-logr/zapr for how zap level relates to logr verbosity.
 func Level(level zapcore.LevelEnabler) func(o *Options) {
 	return func(o *Options) {
 		o.Level = level
 	}
 }
 
-// StacktraceLevel configures the logger to record a stack trace for all messages at
-// or above a given level.
-// See Options.StacktraceLevel
+// StacktraceLevel sets Options.StacktraceLevel, which configures the logger to record a stack trace
+// for all messages at or above a given level.
+// See the Level Opts for the relationship of zap log level to logr verbosity.
 func StacktraceLevel(stacktraceLevel zapcore.LevelEnabler) func(o *Options) {
 	return func(o *Options) {
 		o.StacktraceLevel = stacktraceLevel
@@ -151,12 +153,16 @@ type Options struct {
 	//
 	// Deprecated: Use DestWriter instead
 	DestWritter io.Writer
-	// Level configures the verbosity of the logging.  Defaults to Debug when
-	// Development is true and Info otherwise
+	// Level configures the verbosity of the logging.
+	// Defaults to Debug when Development is true and Info otherwise.
+	// A zap log level should be multiplied by -1 to get the logr verbosity.
+	// For example, to get logr verbosity of 3, set this field to zapcore.Level(-3).
+	// See https://pkg.go.dev/github.com/go-logr/zapr for how zap level relates to logr verbosity.
 	Level zapcore.LevelEnabler
 	// StacktraceLevel is the level at and above which stacktraces will
 	// be recorded for all messages. Defaults to Warn when Development
-	// is true and Error otherwise
+	// is true and Error otherwise.
+	// See Level for the relationship of zap log level to logr verbosity.
 	StacktraceLevel zapcore.LevelEnabler
 	// ZapOpts allows passing arbitrary zap.Options to configure on the
 	// underlying Zap logger.

pkg/log/zap/zap_test.go

@@ -472,7 +472,7 @@ var _ = Describe("Zap log level flag options setup", func() {
 		})
 	})
 
-	Context("with encoder options provided programmatically.", func() {
+	Context("with encoder options provided programmatically", func() {
 
 		It("Should set Console Encoder, with given Nanos TimeEncoder option.", func() {
 			logOut := new(bytes.Buffer)
@@ -517,5 +517,35 @@ var _ = Describe("Zap log level flag options setup", func() {
 			Expect(string(outRaw)).Should(ContainSubstring("MillisTimeFormat"))
 		})
 
+		Context("using Level()", func() {
+			var logOut *bytes.Buffer
+
+			BeforeEach(func() {
+				logOut = new(bytes.Buffer)
+			})
+
+			It("logs with negative logr level", func() {
+				By("setting up the logger")
+				logger := New(WriteTo(logOut), Level(zapcore.Level(-3)))
+				logger.V(3).Info("test 3") // Should be logged
+				Expect(string(logOut.Bytes())).To(ContainSubstring(`"msg":"test 3"`))
+				logOut.Truncate(0)
+				logger.V(1).Info("test 1") // Should be logged
+				Expect(string(logOut.Bytes())).To(ContainSubstring(`"msg":"test 1"`))
+				logOut.Truncate(0)
+				logger.V(4).Info("test 4") // Should not be logged
+				Expect(string(logOut.Bytes())).To(BeEmpty())
+				logger.V(-3).Info("test -3") // Log a panic, since V(-1*N) for all N > 0 is not permitted.
+				Expect(string(logOut.Bytes())).To(ContainSubstring(`"level":"dpanic"`))
+			})
+			It("does not log with positive logr level", func() {
+				By("setting up the logger")
+				logger := New(WriteTo(logOut), Level(zapcore.Level(1)))
+				logger.V(1).Info("test 1")
+				Expect(string(logOut.Bytes())).To(BeEmpty())
+				logger.V(3).Info("test 3")
+				Expect(string(logOut.Bytes())).To(BeEmpty())
+			})
+		})
 	})
 })