zapcore: Add LevelOf(LevelEnabler), UnknownLevel (#1147)

Add a new function LevelOf that reports the minimum enabled log level
for a LevelEnabler.
This works by looping through all known Zap levels in-order,
returning the newly introduced UnknownLevel if none of the known levels
are enabled.
A LevelEnabler or Core implementation may implement the Level() Level
method to override and optimize this behavior.
AtomicLevel already implemented this method.
This change adds the method to all Core implementations shipped with
Zap.
Note:
UnknownLevel is set at FatalLevel+1 to account for the possibility that
users of Zap are using DebugLevel-1 as their own custom log level--even
though this isn't supported, it's preferable not to break these users.
Users are less likely to use FatalLevel+1 since Fatal means "exit the
application."
Refs #1144
Supersedes #1143, which was not backwards compatible
Refs GO-1586

internal/level_enabler.go

@@ -0,0 +1,35 @@
+// Copyright (c) 2022 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 internal
+
+import "go.uber.org/zap/zapcore"
+
+// LeveledEnabler is an interface satisfied by LevelEnablers that are able to
+// report their own level.
+//
+// This interface is defined to use more conveniently in tests and non-zapcore
+// packages.
+// This cannot be imported from zapcore because of the cyclic dependency.
+type LeveledEnabler interface {
+	zapcore.LevelEnabler
+
+	Level() zapcore.Level
+}

level.go

@@ -22,6 +22,7 @@ package zap
 
 import (
 	"go.uber.org/atomic"
+	"go.uber.org/zap/internal"
 	"go.uber.org/zap/zapcore"
 )
 
@@ -70,6 +71,8 @@ type AtomicLevel struct {
 	l *atomic.Int32
 }
 
+var _ internal.LeveledEnabler = AtomicLevel{}
+
 // NewAtomicLevel creates an AtomicLevel with InfoLevel and above logging
 // enabled.
 func NewAtomicLevel() AtomicLevel {

zapcore/core.go

@@ -69,6 +69,15 @@ type ioCore struct {
 	out WriteSyncer
 }
 
+var (
+	_ Core           = (*ioCore)(nil)
+	_ leveledEnabler = (*ioCore)(nil)
+)
+
+func (c *ioCore) Level() Level {
+	return LevelOf(c.LevelEnabler)
+}
+
 func (c *ioCore) With(fields []Field) Core {
 	clone := c.clone()
 	addFields(clone.enc, fields)

zapcore/core_test.go

@@ -82,6 +82,10 @@ func TestIOCore(t *testing.T) {
 	).With([]Field{makeInt64Field("k", 1)})
 	defer assert.NoError(t, core.Sync(), "Expected Syncing a temp file to succeed.")
 
+	t.Run("LevelOf", func(t *testing.T) {
+		assert.Equal(t, InfoLevel, LevelOf(core), "Incorrect Core Level")
+	})
+
 	if ce := core.Check(Entry{Level: DebugLevel, Message: "debug"}, nil); ce != nil {
 		ce.Write(makeInt64Field("k", 2))
 	}

zapcore/hook.go

@@ -27,6 +27,11 @@ type hooked struct {
 	funcs []func(Entry) error
 }
 
+var (
+	_ Core           = (*hooked)(nil)
+	_ leveledEnabler = (*hooked)(nil)
+)
+
 // RegisterHooks wraps a Core and runs a collection of user-defined callback
 // hooks each time a message is logged. Execution of the callbacks is blocking.
 //
@@ -40,6 +45,10 @@ func RegisterHooks(core Core, hooks ...func(Entry) error) Core {
 	}
 }
 
+func (h *hooked) Level() Level {
+	return LevelOf(h.Core)
+}
+
 func (h *hooked) Check(ent Entry, ce *CheckedEntry) *CheckedEntry {
 	// Let the wrapped Core decide whether to log this message or not. This
 	// also gives the downstream a chance to register itself directly with the

zapcore/hook_test.go

@@ -27,6 +27,7 @@ import (
 	"go.uber.org/zap/zaptest/observer"
 
 	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
 )
 
 func TestHooks(t *testing.T) {
@@ -42,6 +43,10 @@ func TestHooks(t *testing.T) {
 
 	for _, tt := range tests {
 		fac, logs := observer.New(tt.coreLevel)
+
+		// sanity check
+		require.Equal(t, tt.coreLevel, LevelOf(fac), "Original logger has the wrong level")
+
 		intField := makeInt64Field("foo", 42)
 		ent := Entry{Message: "bar", Level: tt.entryLevel}
 
@@ -57,6 +62,10 @@ func TestHooks(t *testing.T) {
 			ce.Write()
 		}
 
+		t.Run("LevelOf", func(t *testing.T) {
+			assert.Equal(t, tt.coreLevel, LevelOf(h), "Wrapped logger has the wrong log level")
+		})
+
 		if tt.expectCall {
 			assert.Equal(t, 1, called, "Expected to call hook once.")
 			assert.Equal(

zapcore/increase_level.go

@@ -27,6 +27,11 @@ type levelFilterCore struct {
 	level LevelEnabler
 }
 
+var (
+	_ Core           = (*levelFilterCore)(nil)
+	_ leveledEnabler = (*levelFilterCore)(nil)
+)
+
 // NewIncreaseLevelCore creates a core that can be used to increase the level of
 // an existing Core. It cannot be used to decrease the logging level, as it acts
 // as a filter before calling the underlying core. If level decreases the log level,
@@ -45,6 +50,10 @@ func (c *levelFilterCore) Enabled(lvl Level) bool {
 	return c.level.Enabled(lvl)
 }
 
+func (c *levelFilterCore) Level() Level {
+	return LevelOf(c.level)
+}
+
 func (c *levelFilterCore) With(fields []Field) Core {
 	return &levelFilterCore{c.core.With(fields), c.level}
 }

zapcore/increase_level_test.go

@@ -82,6 +82,9 @@ func TestIncreaseLevel(t *testing.T) {
 		t.Run(msg, func(t *testing.T) {
 			logger, logs := observer.New(tt.coreLevel)
 
+			// sanity check
+			require.Equal(t, tt.coreLevel, LevelOf(logger), "Original logger has the wrong level")
+
 			filteredLogger, err := NewIncreaseLevelCore(logger, tt.increaseLevel)
 			if tt.wantErr {
 				require.Error(t, err)
@@ -95,6 +98,10 @@ func TestIncreaseLevel(t *testing.T) {
 
 			require.NoError(t, err)
 
+			t.Run("LevelOf", func(t *testing.T) {
+				assert.Equal(t, tt.increaseLevel, LevelOf(filteredLogger), "Filtered logger has the wrong level")
+			})
+
 			for l := DebugLevel; l <= FatalLevel; l++ {
 				enabled := filteredLogger.Enabled(l)
 				entry := Entry{Level: l}

zapcore/level.go

@@ -53,6 +53,11 @@ const (
 
 	_minLevel = DebugLevel
 	_maxLevel = FatalLevel
+
+	// InvalidLevel is an invalid value for Level.
+	//
+	// Core implementations may panic if they see messages of this level.
+	InvalidLevel = _maxLevel + 1
 )
 
 // ParseLevel parses a level based on the lower-case or all-caps ASCII
@@ -67,6 +72,43 @@ func ParseLevel(text string) (Level, error) {
 	return level, err
 }
 
+type leveledEnabler interface {
+	LevelEnabler
+
+	Level() Level
+}
+
+// LevelOf reports the minimum enabled log level for the given LevelEnabler
+// from Zap's supported log levels, or [InvalidLevel] if none of them are
+// enabled.
+//
+// A LevelEnabler may implement a 'Level() Level' method to override the
+// behavior of this function.
+//
+//	func (c *core) Level() Level {
+//		return c.currentLevel
+//	}
+//
+// It is recommended that [Core] implementations that wrap other cores use
+// LevelOf to retrieve the level of the wrapped core. For example,
+//
+//	func (c *coreWrapper) Level() Level {
+//		return zapcore.LevelOf(c.wrappedCore)
+//	}
+func LevelOf(enab LevelEnabler) Level {
+	if lvler, ok := enab.(leveledEnabler); ok {
+		return lvler.Level()
+	}
+
+	for lvl := _minLevel; lvl <= _maxLevel; lvl++ {
+		if enab.Enabled(lvl) {
+			return lvl
+		}
+	}
+
+	return InvalidLevel
+}
+
 // String returns a lower-case ASCII representation of the log level.
 func (l Level) String() string {
 	switch l {

zapcore/level_test.go

@@ -31,14 +31,15 @@ import (
 
 func TestLevelString(t *testing.T) {
 	tests := map[Level]string{
-		DebugLevel:  "debug",
-		InfoLevel:   "info",
-		WarnLevel:   "warn",
-		ErrorLevel:  "error",
-		DPanicLevel: "dpanic",
-		PanicLevel:  "panic",
-		FatalLevel:  "fatal",
-		Level(-42):  "Level(-42)",
+		DebugLevel:   "debug",
+		InfoLevel:    "info",
+		WarnLevel:    "warn",
+		ErrorLevel:   "error",
+		DPanicLevel:  "dpanic",
+		PanicLevel:   "panic",
+		FatalLevel:   "fatal",
+		Level(-42):   "Level(-42)",
+		InvalidLevel: "Level(6)", // InvalidLevel does not have a name
 	}
 
 	for lvl, stringLevel := range tests {
@@ -197,3 +198,52 @@ func TestLevelAsFlagValue(t *testing.T) {
 		"Unexpected error output from invalid flag input.",
 	)
 }
+
+// enablerWithCustomLevel is a LevelEnabler that implements a custom Level
+// method.
+type enablerWithCustomLevel struct{ lvl Level }
+
+var _ leveledEnabler = (*enablerWithCustomLevel)(nil)
+
+func (l *enablerWithCustomLevel) Enabled(lvl Level) bool {
+	return l.lvl.Enabled(lvl)
+}
+
+func (l *enablerWithCustomLevel) Level() Level {
+	return l.lvl
+}
+
+func TestLevelOf(t *testing.T) {
+	tests := []struct {
+		desc string
+		give LevelEnabler
+		want Level
+	}{
+		{desc: "debug", give: DebugLevel, want: DebugLevel},
+		{desc: "info", give: InfoLevel, want: InfoLevel},
+		{desc: "warn", give: WarnLevel, want: WarnLevel},
+		{desc: "error", give: ErrorLevel, want: ErrorLevel},
+		{desc: "dpanic", give: DPanicLevel, want: DPanicLevel},
+		{desc: "panic", give: PanicLevel, want: PanicLevel},
+		{desc: "fatal", give: FatalLevel, want: FatalLevel},
+		{
+			desc: "leveledEnabler",
+			give: &enablerWithCustomLevel{lvl: InfoLevel},
+			want: InfoLevel,
+		},
+		{
+			desc: "noop",
+			give: NewNopCore(), // always disabled
+			want: InvalidLevel,
+		},
+	}
+
+	for _, tt := range tests {
+		tt := tt
+		t.Run(tt.desc, func(t *testing.T) {
+			t.Parallel()
+
+			assert.Equal(t, tt.want, LevelOf(tt.give), "Reported level did not match.")
+		})
+	}
+}

zapcore/sampler.go

@@ -1,4 +1,4 @@
-// Copyright (c) 2016 Uber Technologies, Inc.
+// Copyright (c) 2016-2022 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
@@ -175,6 +175,11 @@ type sampler struct {
 	hook              func(Entry, SamplingDecision)
 }
 
+var (
+	_ Core           = (*sampler)(nil)
+	_ leveledEnabler = (*sampler)(nil)
+)
+
 // NewSampler creates a Core that samples incoming entries, which
 // caps the CPU and I/O load of logging while attempting to preserve a
 // representative subset of your logs.
@@ -192,6 +197,10 @@ func NewSampler(core Core, tick time.Duration, first, thereafter int) Core {
 	return NewSamplerWithOptions(core, tick, first, thereafter)
 }
 
+func (s *sampler) Level() Level {
+	return LevelOf(s.Core)
+}
+
 func (s *sampler) With(fields []Field) Core {
 	return &sampler{
 		Core:       s.Core.With(fields),

zapcore/sampler_test.go

@@ -1,4 +1,4 @@
-// Copyright (c) 2016 Uber Technologies, Inc.
+// Copyright (c) 2016-2022 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
@@ -88,6 +88,19 @@ func TestSampler(t *testing.T) {
 	}
 }
 
+func TestLevelOfSampler(t *testing.T) {
+	levels := []Level{DebugLevel, InfoLevel, WarnLevel, ErrorLevel, DPanicLevel, PanicLevel, FatalLevel}
+	for _, lvl := range levels {
+		lvl := lvl
+		t.Run(lvl.String(), func(t *testing.T) {
+			t.Parallel()
+
+			sampler, _ := fakeSampler(lvl, time.Minute, 2, 3)
+			assert.Equal(t, lvl, LevelOf(sampler), "Sampler level did not match.")
+		})
+	}
+}
+
 func TestSamplerDisabledLevels(t *testing.T) {
 	sampler, logs := fakeSampler(InfoLevel, time.Minute, 1, 100)
 
@@ -232,7 +245,6 @@ func TestSamplerConcurrent(t *testing.T) {
 		int(dropped.Load()),
 		"Unexpected number of logs dropped",
 	)
-
 }
 
 func TestSamplerRaces(t *testing.T) {