Skip to content

Commit 4a895a2

Browse files
abhinavabhinav
authored
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
1 parent 19a5d8a commit 4a895a2

16 files changed

+279
-14
lines changed

‎internal/level_enabler.go

+35
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
// Copyright (c) 2022 Uber Technologies, Inc.
2+
//
3+
// Permission is hereby granted, free of charge, to any person obtaining a copy
4+
// of this software and associated documentation files (the "Software"), to deal
5+
// in the Software without restriction, including without limitation the rights
6+
// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
7+
// copies of the Software, and to permit persons to whom the Software is
8+
// furnished to do so, subject to the following conditions:
9+
//
10+
// The above copyright notice and this permission notice shall be included in
11+
// all copies or substantial portions of the Software.
12+
//
13+
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
14+
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
15+
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
16+
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
17+
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
18+
// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
19+
// THE SOFTWARE.
20+
21+
package internal
22+
23+
import "go.uber.org/zap/zapcore"
24+
25+
// LeveledEnabler is an interface satisfied by LevelEnablers that are able to
26+
// report their own level.
27+
//
28+
// This interface is defined to use more conveniently in tests and non-zapcore
29+
// packages.
30+
// This cannot be imported from zapcore because of the cyclic dependency.
31+
type LeveledEnabler interface {
32+
zapcore.LevelEnabler
33+
34+
Level() zapcore.Level
35+
}

‎level.go

+3
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ package zap
2222

2323
import (
2424
"go.uber.org/atomic"
25+
"go.uber.org/zap/internal"
2526
"go.uber.org/zap/zapcore"
2627
)
2728

@@ -70,6 +71,8 @@ type AtomicLevel struct {
7071
l *atomic.Int32
7172
}
7273

74+
var _ internal.LeveledEnabler = AtomicLevel{}
75+
7376
// NewAtomicLevel creates an AtomicLevel with InfoLevel and above logging
7477
// enabled.
7578
func NewAtomicLevel() AtomicLevel {

‎zapcore/core.go

+9
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,15 @@ type ioCore struct {
6969
out WriteSyncer
7070
}
7171

72+
var (
73+
_ Core = (*ioCore)(nil)
74+
_ leveledEnabler = (*ioCore)(nil)
75+
)
76+
77+
func (c *ioCore) Level() Level {
78+
return LevelOf(c.LevelEnabler)
79+
}
80+
7281
func (c *ioCore) With(fields []Field) Core {
7382
clone := c.clone()
7483
addFields(clone.enc, fields)

‎zapcore/core_test.go

+4
Original file line numberDiff line numberDiff line change
@@ -82,6 +82,10 @@ func TestIOCore(t *testing.T) {
8282
).With([]Field{makeInt64Field("k", 1)})
8383
defer assert.NoError(t, core.Sync(), "Expected Syncing a temp file to succeed.")
8484

85+
t.Run("LevelOf", func(t *testing.T) {
86+
assert.Equal(t, InfoLevel, LevelOf(core), "Incorrect Core Level")
87+
})
88+
8589
if ce := core.Check(Entry{Level: DebugLevel, Message: "debug"}, nil); ce != nil {
8690
ce.Write(makeInt64Field("k", 2))
8791
}

‎zapcore/hook.go

+9
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,11 @@ type hooked struct {
2727
funcs []func(Entry) error
2828
}
2929

30+
var (
31+
_ Core = (*hooked)(nil)
32+
_ leveledEnabler = (*hooked)(nil)
33+
)
34+
3035
// RegisterHooks wraps a Core and runs a collection of user-defined callback
3136
// hooks each time a message is logged. Execution of the callbacks is blocking.
3237
//
@@ -40,6 +45,10 @@ func RegisterHooks(core Core, hooks ...func(Entry) error) Core {
4045
}
4146
}
4247

48+
func (h *hooked) Level() Level {
49+
return LevelOf(h.Core)
50+
}
51+
4352
func (h *hooked) Check(ent Entry, ce *CheckedEntry) *CheckedEntry {
4453
// Let the wrapped Core decide whether to log this message or not. This
4554
// also gives the downstream a chance to register itself directly with the

‎zapcore/hook_test.go

+9
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ import (
2727
"go.uber.org/zap/zaptest/observer"
2828

2929
"github.com/stretchr/testify/assert"
30+
"github.com/stretchr/testify/require"
3031
)
3132

3233
func TestHooks(t *testing.T) {
@@ -42,6 +43,10 @@ func TestHooks(t *testing.T) {
4243

4344
for _, tt := range tests {
4445
fac, logs := observer.New(tt.coreLevel)
46+
47+
// sanity check
48+
require.Equal(t, tt.coreLevel, LevelOf(fac), "Original logger has the wrong level")
49+
4550
intField := makeInt64Field("foo", 42)
4651
ent := Entry{Message: "bar", Level: tt.entryLevel}
4752

@@ -57,6 +62,10 @@ func TestHooks(t *testing.T) {
5762
ce.Write()
5863
}
5964

65+
t.Run("LevelOf", func(t *testing.T) {
66+
assert.Equal(t, tt.coreLevel, LevelOf(h), "Wrapped logger has the wrong log level")
67+
})
68+
6069
if tt.expectCall {
6170
assert.Equal(t, 1, called, "Expected to call hook once.")
6271
assert.Equal(

‎zapcore/increase_level.go

+9
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,11 @@ type levelFilterCore struct {
2727
level LevelEnabler
2828
}
2929

30+
var (
31+
_ Core = (*levelFilterCore)(nil)
32+
_ leveledEnabler = (*levelFilterCore)(nil)
33+
)
34+
3035
// NewIncreaseLevelCore creates a core that can be used to increase the level of
3136
// an existing Core. It cannot be used to decrease the logging level, as it acts
3237
// 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 {
4550
return c.level.Enabled(lvl)
4651
}
4752

53+
func (c *levelFilterCore) Level() Level {
54+
return LevelOf(c.level)
55+
}
56+
4857
func (c *levelFilterCore) With(fields []Field) Core {
4958
return &levelFilterCore{c.core.With(fields), c.level}
5059
}

‎zapcore/increase_level_test.go

+7
Original file line numberDiff line numberDiff line change
@@ -82,6 +82,9 @@ func TestIncreaseLevel(t *testing.T) {
8282
t.Run(msg, func(t *testing.T) {
8383
logger, logs := observer.New(tt.coreLevel)
8484

85+
// sanity check
86+
require.Equal(t, tt.coreLevel, LevelOf(logger), "Original logger has the wrong level")
87+
8588
filteredLogger, err := NewIncreaseLevelCore(logger, tt.increaseLevel)
8689
if tt.wantErr {
8790
require.Error(t, err)
@@ -95,6 +98,10 @@ func TestIncreaseLevel(t *testing.T) {
9598

9699
require.NoError(t, err)
97100

101+
t.Run("LevelOf", func(t *testing.T) {
102+
assert.Equal(t, tt.increaseLevel, LevelOf(filteredLogger), "Filtered logger has the wrong level")
103+
})
104+
98105
for l := DebugLevel; l <= FatalLevel; l++ {
99106
enabled := filteredLogger.Enabled(l)
100107
entry := Entry{Level: l}

‎zapcore/level.go

+42
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,11 @@ const (
5353

5454
_minLevel = DebugLevel
5555
_maxLevel = FatalLevel
56+
57+
// InvalidLevel is an invalid value for Level.
58+
//
59+
// Core implementations may panic if they see messages of this level.
60+
InvalidLevel = _maxLevel + 1
5661
)
5762

5863
// ParseLevel parses a level based on the lower-case or all-caps ASCII
@@ -67,6 +72,43 @@ func ParseLevel(text string) (Level, error) {
6772
return level, err
6873
}
6974

75+
type leveledEnabler interface {
76+
LevelEnabler
77+
78+
Level() Level
79+
}
80+
81+
// LevelOf reports the minimum enabled log level for the given LevelEnabler
82+
// from Zap's supported log levels, or [InvalidLevel] if none of them are
83+
// enabled.
84+
//
85+
// A LevelEnabler may implement a 'Level() Level' method to override the
86+
// behavior of this function.
87+
//
88+
// func (c *core) Level() Level {
89+
// return c.currentLevel
90+
// }
91+
//
92+
// It is recommended that [Core] implementations that wrap other cores use
93+
// LevelOf to retrieve the level of the wrapped core. For example,
94+
//
95+
// func (c *coreWrapper) Level() Level {
96+
// return zapcore.LevelOf(c.wrappedCore)
97+
// }
98+
func LevelOf(enab LevelEnabler) Level {
99+
if lvler, ok := enab.(leveledEnabler); ok {
100+
return lvler.Level()
101+
}
102+
103+
for lvl := _minLevel; lvl <= _maxLevel; lvl++ {
104+
if enab.Enabled(lvl) {
105+
return lvl
106+
}
107+
}
108+
109+
return InvalidLevel
110+
}
111+
70112
// String returns a lower-case ASCII representation of the log level.
71113
func (l Level) String() string {
72114
switch l {

‎zapcore/level_test.go

+58-8
Original file line numberDiff line numberDiff line change
@@ -31,14 +31,15 @@ import (
3131

3232
func TestLevelString(t *testing.T) {
3333
tests := map[Level]string{
34-
DebugLevel: "debug",
35-
InfoLevel: "info",
36-
WarnLevel: "warn",
37-
ErrorLevel: "error",
38-
DPanicLevel: "dpanic",
39-
PanicLevel: "panic",
40-
FatalLevel: "fatal",
41-
Level(-42): "Level(-42)",
34+
DebugLevel: "debug",
35+
InfoLevel: "info",
36+
WarnLevel: "warn",
37+
ErrorLevel: "error",
38+
DPanicLevel: "dpanic",
39+
PanicLevel: "panic",
40+
FatalLevel: "fatal",
41+
Level(-42): "Level(-42)",
42+
InvalidLevel: "Level(6)", // InvalidLevel does not have a name
4243
}
4344

4445
for lvl, stringLevel := range tests {
@@ -197,3 +198,52 @@ func TestLevelAsFlagValue(t *testing.T) {
197198
"Unexpected error output from invalid flag input.",
198199
)
199200
}
201+
202+
// enablerWithCustomLevel is a LevelEnabler that implements a custom Level
203+
// method.
204+
type enablerWithCustomLevel struct{ lvl Level }
205+
206+
var _ leveledEnabler = (*enablerWithCustomLevel)(nil)
207+
208+
func (l *enablerWithCustomLevel) Enabled(lvl Level) bool {
209+
return l.lvl.Enabled(lvl)
210+
}
211+
212+
func (l *enablerWithCustomLevel) Level() Level {
213+
return l.lvl
214+
}
215+
216+
func TestLevelOf(t *testing.T) {
217+
tests := []struct {
218+
desc string
219+
give LevelEnabler
220+
want Level
221+
}{
222+
{desc: "debug", give: DebugLevel, want: DebugLevel},
223+
{desc: "info", give: InfoLevel, want: InfoLevel},
224+
{desc: "warn", give: WarnLevel, want: WarnLevel},
225+
{desc: "error", give: ErrorLevel, want: ErrorLevel},
226+
{desc: "dpanic", give: DPanicLevel, want: DPanicLevel},
227+
{desc: "panic", give: PanicLevel, want: PanicLevel},
228+
{desc: "fatal", give: FatalLevel, want: FatalLevel},
229+
{
230+
desc: "leveledEnabler",
231+
give: &enablerWithCustomLevel{lvl: InfoLevel},
232+
want: InfoLevel,
233+
},
234+
{
235+
desc: "noop",
236+
give: NewNopCore(), // always disabled
237+
want: InvalidLevel,
238+
},
239+
}
240+
241+
for _, tt := range tests {
242+
tt := tt
243+
t.Run(tt.desc, func(t *testing.T) {
244+
t.Parallel()
245+
246+
assert.Equal(t, tt.want, LevelOf(tt.give), "Reported level did not match.")
247+
})
248+
}
249+
}

‎zapcore/sampler.go

+10-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Copyright (c) 2016 Uber Technologies, Inc.
1+
// Copyright (c) 2016-2022 Uber Technologies, Inc.
22
//
33
// Permission is hereby granted, free of charge, to any person obtaining a copy
44
// of this software and associated documentation files (the "Software"), to deal
@@ -175,6 +175,11 @@ type sampler struct {
175175
hook func(Entry, SamplingDecision)
176176
}
177177

178+
var (
179+
_ Core = (*sampler)(nil)
180+
_ leveledEnabler = (*sampler)(nil)
181+
)
182+
178183
// NewSampler creates a Core that samples incoming entries, which
179184
// caps the CPU and I/O load of logging while attempting to preserve a
180185
// representative subset of your logs.
@@ -192,6 +197,10 @@ func NewSampler(core Core, tick time.Duration, first, thereafter int) Core {
192197
return NewSamplerWithOptions(core, tick, first, thereafter)
193198
}
194199

200+
func (s *sampler) Level() Level {
201+
return LevelOf(s.Core)
202+
}
203+
195204
func (s *sampler) With(fields []Field) Core {
196205
return &sampler{
197206
Core: s.Core.With(fields),

‎zapcore/sampler_test.go

+14-2
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Copyright (c) 2016 Uber Technologies, Inc.
1+
// Copyright (c) 2016-2022 Uber Technologies, Inc.
22
//
33
// Permission is hereby granted, free of charge, to any person obtaining a copy
44
// of this software and associated documentation files (the "Software"), to deal
@@ -88,6 +88,19 @@ func TestSampler(t *testing.T) {
8888
}
8989
}
9090

91+
func TestLevelOfSampler(t *testing.T) {
92+
levels := []Level{DebugLevel, InfoLevel, WarnLevel, ErrorLevel, DPanicLevel, PanicLevel, FatalLevel}
93+
for _, lvl := range levels {
94+
lvl := lvl
95+
t.Run(lvl.String(), func(t *testing.T) {
96+
t.Parallel()
97+
98+
sampler, _ := fakeSampler(lvl, time.Minute, 2, 3)
99+
assert.Equal(t, lvl, LevelOf(sampler), "Sampler level did not match.")
100+
})
101+
}
102+
}
103+
91104
func TestSamplerDisabledLevels(t *testing.T) {
92105
sampler, logs := fakeSampler(InfoLevel, time.Minute, 1, 100)
93106

@@ -232,7 +245,6 @@ func TestSamplerConcurrent(t *testing.T) {
232245
int(dropped.Load()),
233246
"Unexpected number of logs dropped",
234247
)
235-
236248
}
237249

238250
func TestSamplerRaces(t *testing.T) {

0 commit comments

Comments
 (0)