blob: dc8f6e3a4bd61648a2b14cbd138d08ac3d5d235e [file] [log] [blame]
Matteo Scandoloa4285862020-12-01 18:10:10 -08001// Copyright (c) 2016 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
21package zap
22
23import (
24 "fmt"
25 "io/ioutil"
26 "os"
27 "runtime"
28 "strings"
29 "time"
30
31 "go.uber.org/zap/zapcore"
32)
33
34// A Logger provides fast, leveled, structured logging. All methods are safe
35// for concurrent use.
36//
37// The Logger is designed for contexts in which every microsecond and every
38// allocation matters, so its API intentionally favors performance and type
39// safety over brevity. For most applications, the SugaredLogger strikes a
40// better balance between performance and ergonomics.
41type Logger struct {
42 core zapcore.Core
43
44 development bool
45 name string
46 errorOutput zapcore.WriteSyncer
47
48 addCaller bool
49 addStack zapcore.LevelEnabler
50
51 callerSkip int
52}
53
54// New constructs a new Logger from the provided zapcore.Core and Options. If
55// the passed zapcore.Core is nil, it falls back to using a no-op
56// implementation.
57//
58// This is the most flexible way to construct a Logger, but also the most
59// verbose. For typical use cases, the highly-opinionated presets
60// (NewProduction, NewDevelopment, and NewExample) or the Config struct are
61// more convenient.
62//
63// For sample code, see the package-level AdvancedConfiguration example.
64func New(core zapcore.Core, options ...Option) *Logger {
65 if core == nil {
66 return NewNop()
67 }
68 log := &Logger{
69 core: core,
70 errorOutput: zapcore.Lock(os.Stderr),
71 addStack: zapcore.FatalLevel + 1,
72 }
73 return log.WithOptions(options...)
74}
75
76// NewNop returns a no-op Logger. It never writes out logs or internal errors,
77// and it never runs user-defined hooks.
78//
79// Using WithOptions to replace the Core or error output of a no-op Logger can
80// re-enable logging.
81func NewNop() *Logger {
82 return &Logger{
83 core: zapcore.NewNopCore(),
84 errorOutput: zapcore.AddSync(ioutil.Discard),
85 addStack: zapcore.FatalLevel + 1,
86 }
87}
88
89// NewProduction builds a sensible production Logger that writes InfoLevel and
90// above logs to standard error as JSON.
91//
92// It's a shortcut for NewProductionConfig().Build(...Option).
93func NewProduction(options ...Option) (*Logger, error) {
94 return NewProductionConfig().Build(options...)
95}
96
97// NewDevelopment builds a development Logger that writes DebugLevel and above
98// logs to standard error in a human-friendly format.
99//
100// It's a shortcut for NewDevelopmentConfig().Build(...Option).
101func NewDevelopment(options ...Option) (*Logger, error) {
102 return NewDevelopmentConfig().Build(options...)
103}
104
105// NewExample builds a Logger that's designed for use in zap's testable
106// examples. It writes DebugLevel and above logs to standard out as JSON, but
107// omits the timestamp and calling function to keep example output
108// short and deterministic.
109func NewExample(options ...Option) *Logger {
110 encoderCfg := zapcore.EncoderConfig{
111 MessageKey: "msg",
112 LevelKey: "level",
113 NameKey: "logger",
114 EncodeLevel: zapcore.LowercaseLevelEncoder,
115 EncodeTime: zapcore.ISO8601TimeEncoder,
116 EncodeDuration: zapcore.StringDurationEncoder,
117 }
118 core := zapcore.NewCore(zapcore.NewJSONEncoder(encoderCfg), os.Stdout, DebugLevel)
119 return New(core).WithOptions(options...)
120}
121
122// Sugar wraps the Logger to provide a more ergonomic, but slightly slower,
123// API. Sugaring a Logger is quite inexpensive, so it's reasonable for a
124// single application to use both Loggers and SugaredLoggers, converting
125// between them on the boundaries of performance-sensitive code.
126func (log *Logger) Sugar() *SugaredLogger {
127 core := log.clone()
128 core.callerSkip += 2
129 return &SugaredLogger{core}
130}
131
132// Named adds a new path segment to the logger's name. Segments are joined by
133// periods. By default, Loggers are unnamed.
134func (log *Logger) Named(s string) *Logger {
135 if s == "" {
136 return log
137 }
138 l := log.clone()
139 if log.name == "" {
140 l.name = s
141 } else {
142 l.name = strings.Join([]string{l.name, s}, ".")
143 }
144 return l
145}
146
147// WithOptions clones the current Logger, applies the supplied Options, and
148// returns the resulting Logger. It's safe to use concurrently.
149func (log *Logger) WithOptions(opts ...Option) *Logger {
150 c := log.clone()
151 for _, opt := range opts {
152 opt.apply(c)
153 }
154 return c
155}
156
157// With creates a child logger and adds structured context to it. Fields added
158// to the child don't affect the parent, and vice versa.
159func (log *Logger) With(fields ...Field) *Logger {
160 if len(fields) == 0 {
161 return log
162 }
163 l := log.clone()
164 l.core = l.core.With(fields)
165 return l
166}
167
168// Check returns a CheckedEntry if logging a message at the specified level
169// is enabled. It's a completely optional optimization; in high-performance
170// applications, Check can help avoid allocating a slice to hold fields.
171func (log *Logger) Check(lvl zapcore.Level, msg string) *zapcore.CheckedEntry {
172 return log.check(lvl, msg)
173}
174
175// Debug logs a message at DebugLevel. The message includes any fields passed
176// at the log site, as well as any fields accumulated on the logger.
177func (log *Logger) Debug(msg string, fields ...Field) {
178 if ce := log.check(DebugLevel, msg); ce != nil {
179 ce.Write(fields...)
180 }
181}
182
183// Info logs a message at InfoLevel. The message includes any fields passed
184// at the log site, as well as any fields accumulated on the logger.
185func (log *Logger) Info(msg string, fields ...Field) {
186 if ce := log.check(InfoLevel, msg); ce != nil {
187 ce.Write(fields...)
188 }
189}
190
191// Warn logs a message at WarnLevel. The message includes any fields passed
192// at the log site, as well as any fields accumulated on the logger.
193func (log *Logger) Warn(msg string, fields ...Field) {
194 if ce := log.check(WarnLevel, msg); ce != nil {
195 ce.Write(fields...)
196 }
197}
198
199// Error logs a message at ErrorLevel. The message includes any fields passed
200// at the log site, as well as any fields accumulated on the logger.
201func (log *Logger) Error(msg string, fields ...Field) {
202 if ce := log.check(ErrorLevel, msg); ce != nil {
203 ce.Write(fields...)
204 }
205}
206
207// DPanic logs a message at DPanicLevel. The message includes any fields
208// passed at the log site, as well as any fields accumulated on the logger.
209//
210// If the logger is in development mode, it then panics (DPanic means
211// "development panic"). This is useful for catching errors that are
212// recoverable, but shouldn't ever happen.
213func (log *Logger) DPanic(msg string, fields ...Field) {
214 if ce := log.check(DPanicLevel, msg); ce != nil {
215 ce.Write(fields...)
216 }
217}
218
219// Panic logs a message at PanicLevel. The message includes any fields passed
220// at the log site, as well as any fields accumulated on the logger.
221//
222// The logger then panics, even if logging at PanicLevel is disabled.
223func (log *Logger) Panic(msg string, fields ...Field) {
224 if ce := log.check(PanicLevel, msg); ce != nil {
225 ce.Write(fields...)
226 }
227}
228
229// Fatal logs a message at FatalLevel. The message includes any fields passed
230// at the log site, as well as any fields accumulated on the logger.
231//
232// The logger then calls os.Exit(1), even if logging at FatalLevel is
233// disabled.
234func (log *Logger) Fatal(msg string, fields ...Field) {
235 if ce := log.check(FatalLevel, msg); ce != nil {
236 ce.Write(fields...)
237 }
238}
239
240// Sync calls the underlying Core's Sync method, flushing any buffered log
241// entries. Applications should take care to call Sync before exiting.
242func (log *Logger) Sync() error {
243 return log.core.Sync()
244}
245
246// Core returns the Logger's underlying zapcore.Core.
247func (log *Logger) Core() zapcore.Core {
248 return log.core
249}
250
251func (log *Logger) clone() *Logger {
252 copy := *log
253 return &copy
254}
255
256func (log *Logger) check(lvl zapcore.Level, msg string) *zapcore.CheckedEntry {
257 // check must always be called directly by a method in the Logger interface
258 // (e.g., Check, Info, Fatal).
259 const callerSkipOffset = 2
260
261 // Create basic checked entry thru the core; this will be non-nil if the
262 // log message will actually be written somewhere.
263 ent := zapcore.Entry{
264 LoggerName: log.name,
265 Time: time.Now(),
266 Level: lvl,
267 Message: msg,
268 }
269 ce := log.core.Check(ent, nil)
270 willWrite := ce != nil
271
272 // Set up any required terminal behavior.
273 switch ent.Level {
274 case zapcore.PanicLevel:
275 ce = ce.Should(ent, zapcore.WriteThenPanic)
276 case zapcore.FatalLevel:
277 ce = ce.Should(ent, zapcore.WriteThenFatal)
278 case zapcore.DPanicLevel:
279 if log.development {
280 ce = ce.Should(ent, zapcore.WriteThenPanic)
281 }
282 }
283
284 // Only do further annotation if we're going to write this message; checked
285 // entries that exist only for terminal behavior don't benefit from
286 // annotation.
287 if !willWrite {
288 return ce
289 }
290
291 // Thread the error output through to the CheckedEntry.
292 ce.ErrorOutput = log.errorOutput
293 if log.addCaller {
294 ce.Entry.Caller = zapcore.NewEntryCaller(runtime.Caller(log.callerSkip + callerSkipOffset))
295 if !ce.Entry.Caller.Defined {
296 fmt.Fprintf(log.errorOutput, "%v Logger.check error: failed to get caller\n", time.Now().UTC())
297 log.errorOutput.Sync()
298 }
299 }
300 if log.addStack.Enabled(ce.Entry.Level) {
301 ce.Entry.Stack = Stack("").String
302 }
303
304 return ce
305}