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 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 © 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} 306