1 // 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 21 package zap
22 23 import (
24 "fmt"
25 "io"
26 "os"
27 "strings"
28 29 "go.uber.org/zap/internal/bufferpool"
30 "go.uber.org/zap/internal/stacktrace"
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.
41 type Logger struct {
42 core zapcore.Core
43 44 development bool
45 addCaller bool
46 onPanic zapcore.CheckWriteHook // default is WriteThenPanic
47 onFatal zapcore.CheckWriteHook // default is WriteThenFatal
48 49 name string
50 errorOutput zapcore.WriteSyncer
51 52 addStack zapcore.LevelEnabler
53 54 callerSkip int
55 56 clock zapcore.Clock
57 }
58 59 // New constructs a new Logger from the provided zapcore.Core and Options. If
60 // the passed zapcore.Core is nil, it falls back to using a no-op
61 // implementation.
62 //
63 // This is the most flexible way to construct a Logger, but also the most
64 // verbose. For typical use cases, the highly-opinionated presets
65 // (NewProduction, NewDevelopment, and NewExample) or the Config struct are
66 // more convenient.
67 //
68 // For sample code, see the package-level AdvancedConfiguration example.
69 func New(core zapcore.Core, options ...Option) *Logger {
70 if core == nil {
71 return NewNop()
72 }
73 log := &Logger{
74 core: core,
75 errorOutput: zapcore.Lock(os.Stderr),
76 addStack: zapcore.FatalLevel + 1,
77 clock: zapcore.DefaultClock,
78 }
79 return log.WithOptions(options...)
80 }
81 82 // NewNop returns a no-op Logger. It never writes out logs or internal errors,
83 // and it never runs user-defined hooks.
84 //
85 // Using WithOptions to replace the Core or error output of a no-op Logger can
86 // re-enable logging.
87 func NewNop() *Logger {
88 return &Logger{
89 core: zapcore.NewNopCore(),
90 errorOutput: zapcore.AddSync(io.Discard),
91 addStack: zapcore.FatalLevel + 1,
92 clock: zapcore.DefaultClock,
93 }
94 }
95 96 // NewProduction builds a sensible production Logger that writes InfoLevel and
97 // above logs to standard error as JSON.
98 //
99 // It's a shortcut for NewProductionConfig().Build(...Option).
100 func NewProduction(options ...Option) (*Logger, error) {
101 return NewProductionConfig().Build(options...)
102 }
103 104 // NewDevelopment builds a development Logger that writes DebugLevel and above
105 // logs to standard error in a human-friendly format.
106 //
107 // It's a shortcut for NewDevelopmentConfig().Build(...Option).
108 func NewDevelopment(options ...Option) (*Logger, error) {
109 return NewDevelopmentConfig().Build(options...)
110 }
111 112 // Must is a helper that wraps a call to a function returning (*Logger, error)
113 // and panics if the error is non-nil. It is intended for use in variable
114 // initialization such as:
115 //
116 // var logger = zap.Must(zap.NewProduction())
117 func Must(logger *Logger, err error) *Logger {
118 if err != nil {
119 panic(err)
120 }
121 122 return logger
123 }
124 125 // NewExample builds a Logger that's designed for use in zap's testable
126 // examples. It writes DebugLevel and above logs to standard out as JSON, but
127 // omits the timestamp and calling function to keep example output
128 // short and deterministic.
129 func NewExample(options ...Option) *Logger {
130 encoderCfg := zapcore.EncoderConfig{
131 MessageKey: "msg",
132 LevelKey: "level",
133 NameKey: "logger",
134 EncodeLevel: zapcore.LowercaseLevelEncoder,
135 EncodeTime: zapcore.ISO8601TimeEncoder,
136 EncodeDuration: zapcore.StringDurationEncoder,
137 }
138 core := zapcore.NewCore(zapcore.NewJSONEncoder(encoderCfg), os.Stdout, DebugLevel)
139 return New(core).WithOptions(options...)
140 }
141 142 // Sugar wraps the Logger to provide a more ergonomic, but slightly slower,
143 // API. Sugaring a Logger is quite inexpensive, so it's reasonable for a
144 // single application to use both Loggers and SugaredLoggers, converting
145 // between them on the boundaries of performance-sensitive code.
146 func (log *Logger) Sugar() *SugaredLogger {
147 core := log.clone()
148 core.callerSkip += 2
149 return &SugaredLogger{core}
150 }
151 152 // Named adds a new path segment to the logger's name. Segments are joined by
153 // periods. By default, Loggers are unnamed.
154 func (log *Logger) Named(s string) *Logger {
155 if s == "" {
156 return log
157 }
158 l := log.clone()
159 if log.name == "" {
160 l.name = s
161 } else {
162 l.name = strings.Join([]string{l.name, s}, ".")
163 }
164 return l
165 }
166 167 // WithOptions clones the current Logger, applies the supplied Options, and
168 // returns the resulting Logger. It's safe to use concurrently.
169 func (log *Logger) WithOptions(opts ...Option) *Logger {
170 c := log.clone()
171 for _, opt := range opts {
172 opt.apply(c)
173 }
174 return c
175 }
176 177 // With creates a child logger and adds structured context to it. Fields added
178 // to the child don't affect the parent, and vice versa. Any fields that
179 // require evaluation (such as Objects) are evaluated upon invocation of With.
180 func (log *Logger) With(fields ...Field) *Logger {
181 if len(fields) == 0 {
182 return log
183 }
184 l := log.clone()
185 l.core = l.core.With(fields)
186 return l
187 }
188 189 // WithLazy creates a child logger and adds structured context to it lazily.
190 //
191 // The fields are evaluated only if the logger is further chained with [With]
192 // or is written to with any of the log level methods.
193 // Until that occurs, the logger may retain references to objects inside the fields,
194 // and logging will reflect the state of an object at the time of logging,
195 // not the time of WithLazy().
196 //
197 // WithLazy provides a worthwhile performance optimization for contextual loggers
198 // when the likelihood of using the child logger is low,
199 // such as error paths and rarely taken branches.
200 //
201 // Similar to [With], fields added to the child don't affect the parent, and vice versa.
202 func (log *Logger) WithLazy(fields ...Field) *Logger {
203 if len(fields) == 0 {
204 return log
205 }
206 return log.WithOptions(WrapCore(func(core zapcore.Core) zapcore.Core {
207 return zapcore.NewLazyWith(core, fields)
208 }))
209 }
210 211 // Level reports the minimum enabled level for this logger.
212 //
213 // For NopLoggers, this is [zapcore.InvalidLevel].
214 func (log *Logger) Level() zapcore.Level {
215 return zapcore.LevelOf(log.core)
216 }
217 218 // Check returns a CheckedEntry if logging a message at the specified level
219 // is enabled. It's a completely optional optimization; in high-performance
220 // applications, Check can help avoid allocating a slice to hold fields.
221 func (log *Logger) Check(lvl zapcore.Level, msg string) *zapcore.CheckedEntry {
222 return log.check(lvl, msg)
223 }
224 225 // Log logs a message at the specified level. The message includes any fields
226 // passed at the log site, as well as any fields accumulated on the logger.
227 // Any Fields that require evaluation (such as Objects) are evaluated upon
228 // invocation of Log.
229 func (log *Logger) Log(lvl zapcore.Level, msg string, fields ...Field) {
230 if ce := log.check(lvl, msg); ce != nil {
231 ce.Write(fields...)
232 }
233 }
234 235 // Debug logs a message at DebugLevel. The message includes any fields passed
236 // at the log site, as well as any fields accumulated on the logger.
237 func (log *Logger) Debug(msg string, fields ...Field) {
238 if ce := log.check(DebugLevel, msg); ce != nil {
239 ce.Write(fields...)
240 }
241 }
242 243 // Info logs a message at InfoLevel. The message includes any fields passed
244 // at the log site, as well as any fields accumulated on the logger.
245 func (log *Logger) Info(msg string, fields ...Field) {
246 if ce := log.check(InfoLevel, msg); ce != nil {
247 ce.Write(fields...)
248 }
249 }
250 251 // Warn logs a message at WarnLevel. The message includes any fields passed
252 // at the log site, as well as any fields accumulated on the logger.
253 func (log *Logger) Warn(msg string, fields ...Field) {
254 if ce := log.check(WarnLevel, msg); ce != nil {
255 ce.Write(fields...)
256 }
257 }
258 259 // Error logs a message at ErrorLevel. The message includes any fields passed
260 // at the log site, as well as any fields accumulated on the logger.
261 func (log *Logger) Error(msg string, fields ...Field) {
262 if ce := log.check(ErrorLevel, msg); ce != nil {
263 ce.Write(fields...)
264 }
265 }
266 267 // DPanic logs a message at DPanicLevel. The message includes any fields
268 // passed at the log site, as well as any fields accumulated on the logger.
269 //
270 // If the logger is in development mode, it then panics (DPanic means
271 // "development panic"). This is useful for catching errors that are
272 // recoverable, but shouldn't ever happen.
273 func (log *Logger) DPanic(msg string, fields ...Field) {
274 if ce := log.check(DPanicLevel, msg); ce != nil {
275 ce.Write(fields...)
276 }
277 }
278 279 // Panic logs a message at PanicLevel. The message includes any fields passed
280 // at the log site, as well as any fields accumulated on the logger.
281 //
282 // The logger then panics, even if logging at PanicLevel is disabled.
283 func (log *Logger) Panic(msg string, fields ...Field) {
284 if ce := log.check(PanicLevel, msg); ce != nil {
285 ce.Write(fields...)
286 }
287 }
288 289 // Fatal logs a message at FatalLevel. The message includes any fields passed
290 // at the log site, as well as any fields accumulated on the logger.
291 //
292 // The logger then calls os.Exit(1), even if logging at FatalLevel is
293 // disabled.
294 func (log *Logger) Fatal(msg string, fields ...Field) {
295 if ce := log.check(FatalLevel, msg); ce != nil {
296 ce.Write(fields...)
297 }
298 }
299 300 // Sync calls the underlying Core's Sync method, flushing any buffered log
301 // entries. Applications should take care to call Sync before exiting.
302 func (log *Logger) Sync() error {
303 return log.core.Sync()
304 }
305 306 // Core returns the Logger's underlying zapcore.Core.
307 func (log *Logger) Core() zapcore.Core {
308 return log.core
309 }
310 311 // Name returns the Logger's underlying name,
312 // or an empty string if the logger is unnamed.
313 func (log *Logger) Name() string {
314 return log.name
315 }
316 317 func (log *Logger) clone() *Logger {
318 clone := *log
319 return &clone
320 }
321 322 func (log *Logger) check(lvl zapcore.Level, msg string) *zapcore.CheckedEntry {
323 // Logger.check must always be called directly by a method in the
324 // Logger interface (e.g., Check, Info, Fatal).
325 // This skips Logger.check and the Info/Fatal/Check/etc. method that
326 // called it.
327 const callerSkipOffset = 2
328 329 // Check the level first to reduce the cost of disabled log calls.
330 // Since Panic and higher may exit, we skip the optimization for those levels.
331 if lvl < zapcore.DPanicLevel && !log.core.Enabled(lvl) {
332 return nil
333 }
334 335 // Create basic checked entry thru the core; this will be non-nil if the
336 // log message will actually be written somewhere.
337 ent := zapcore.Entry{
338 LoggerName: log.name,
339 Time: log.clock.Now(),
340 Level: lvl,
341 Message: msg,
342 }
343 ce := log.core.Check(ent, nil)
344 willWrite := ce != nil
345 346 // Set up any required terminal behavior.
347 switch ent.Level {
348 case zapcore.PanicLevel:
349 ce = ce.After(ent, terminalHookOverride(zapcore.WriteThenPanic, log.onPanic))
350 case zapcore.FatalLevel:
351 ce = ce.After(ent, terminalHookOverride(zapcore.WriteThenFatal, log.onFatal))
352 case zapcore.DPanicLevel:
353 if log.development {
354 ce = ce.After(ent, terminalHookOverride(zapcore.WriteThenPanic, log.onPanic))
355 }
356 }
357 358 // Only do further annotation if we're going to write this message; checked
359 // entries that exist only for terminal behavior don't benefit from
360 // annotation.
361 if !willWrite {
362 return ce
363 }
364 365 // Thread the error output through to the CheckedEntry.
366 ce.ErrorOutput = log.errorOutput
367 368 addStack := log.addStack.Enabled(ce.Level)
369 if !log.addCaller && !addStack {
370 return ce
371 }
372 373 // Adding the caller or stack trace requires capturing the callers of
374 // this function. We'll share information between these two.
375 stackDepth := stacktrace.First
376 if addStack {
377 stackDepth = stacktrace.Full
378 }
379 stack := stacktrace.Capture(log.callerSkip+callerSkipOffset, stackDepth)
380 defer stack.Free()
381 382 if stack.Count() == 0 {
383 if log.addCaller {
384 fmt.Fprintf(log.errorOutput, "%v Logger.check error: failed to get caller\n", ent.Time.UTC())
385 _ = log.errorOutput.Sync()
386 }
387 return ce
388 }
389 390 frame, more := stack.Next()
391 392 if log.addCaller {
393 ce.Caller = zapcore.EntryCaller{
394 Defined: frame.PC != 0,
395 PC: frame.PC,
396 File: frame.File,
397 Line: frame.Line,
398 Function: frame.Function,
399 }
400 }
401 402 if addStack {
403 buffer := bufferpool.Get()
404 defer buffer.Free()
405 406 stackfmt := stacktrace.NewFormatter(buffer)
407 408 // We've already extracted the first frame, so format that
409 // separately and defer to stackfmt for the rest.
410 stackfmt.FormatFrame(frame)
411 if more {
412 stackfmt.FormatStack(stack)
413 }
414 ce.Stack = buffer.String()
415 }
416 417 return ce
418 }
419 420 func terminalHookOverride(defaultHook, override zapcore.CheckWriteHook) zapcore.CheckWriteHook {
421 // A nil or WriteThenNoop hook will lead to continued execution after
422 // a Panic or Fatal log entry, which is unexpected. For example,
423 //
424 // f, err := os.Open(..)
425 // if err != nil {
426 // log.Fatal("cannot open", zap.Error(err))
427 // }
428 // fmt.Println(f.Name())
429 //
430 // The f.Name() will panic if we continue execution after the log.Fatal.
431 if override == nil || override == zapcore.WriteThenNoop {
432 return defaultHook
433 }
434 return override
435 }
436