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 26 "go.uber.org/zap/zapcore"
27 28 "go.uber.org/multierr"
29 )
30 31 const (
32 _oddNumberErrMsg = "Ignored key without a value."
33 _nonStringKeyErrMsg = "Ignored key-value pairs with non-string keys."
34 _multipleErrMsg = "Multiple errors without a key."
35 )
36 37 // A SugaredLogger wraps the base Logger functionality in a slower, but less
38 // verbose, API. Any Logger can be converted to a SugaredLogger with its Sugar
39 // method.
40 //
41 // Unlike the Logger, the SugaredLogger doesn't insist on structured logging.
42 // For each log level, it exposes four methods:
43 //
44 // - methods named after the log level for log.Print-style logging
45 // - methods ending in "w" for loosely-typed structured logging
46 // - methods ending in "f" for log.Printf-style logging
47 // - methods ending in "ln" for log.Println-style logging
48 //
49 // For example, the methods for InfoLevel are:
50 //
51 // Info(...any) Print-style logging
52 // Infow(...any) Structured logging (read as "info with")
53 // Infof(string, ...any) Printf-style logging
54 // Infoln(...any) Println-style logging
55 type SugaredLogger struct {
56 base *Logger
57 }
58 59 // Desugar unwraps a SugaredLogger, exposing the original Logger. Desugaring
60 // is quite inexpensive, so it's reasonable for a single application to use
61 // both Loggers and SugaredLoggers, converting between them on the boundaries
62 // of performance-sensitive code.
63 func (s *SugaredLogger) Desugar() *Logger {
64 base := s.base.clone()
65 base.callerSkip -= 2
66 return base
67 }
68 69 // Named adds a sub-scope to the logger's name. See Logger.Named for details.
70 func (s *SugaredLogger) Named(name string) *SugaredLogger {
71 return &SugaredLogger{base: s.base.Named(name)}
72 }
73 74 // WithOptions clones the current SugaredLogger, applies the supplied Options,
75 // and returns the result. It's safe to use concurrently.
76 func (s *SugaredLogger) WithOptions(opts ...Option) *SugaredLogger {
77 base := s.base.clone()
78 for _, opt := range opts {
79 opt.apply(base)
80 }
81 return &SugaredLogger{base: base}
82 }
83 84 // With adds a variadic number of fields to the logging context. It accepts a
85 // mix of strongly-typed Field objects and loosely-typed key-value pairs. When
86 // processing pairs, the first element of the pair is used as the field key
87 // and the second as the field value.
88 //
89 // For example,
90 //
91 // sugaredLogger.With(
92 // "hello", "world",
93 // "failure", errors.New("oh no"),
94 // Stack(),
95 // "count", 42,
96 // "user", User{Name: "alice"},
97 // )
98 //
99 // is the equivalent of
100 //
101 // unsugared.With(
102 // String("hello", "world"),
103 // String("failure", "oh no"),
104 // Stack(),
105 // Int("count", 42),
106 // Object("user", User{Name: "alice"}),
107 // )
108 //
109 // Note that the keys in key-value pairs should be strings. In development,
110 // passing a non-string key panics. In production, the logger is more
111 // forgiving: a separate error is logged, but the key-value pair is skipped
112 // and execution continues. Passing an orphaned key triggers similar behavior:
113 // panics in development and errors in production.
114 func (s *SugaredLogger) With(args ...interface{}) *SugaredLogger {
115 return &SugaredLogger{base: s.base.With(s.sweetenFields(args)...)}
116 }
117 118 // WithLazy adds a variadic number of fields to the logging context lazily.
119 // The fields are evaluated only if the logger is further chained with [With]
120 // or is written to with any of the log level methods.
121 // Until that occurs, the logger may retain references to objects inside the fields,
122 // and logging will reflect the state of an object at the time of logging,
123 // not the time of WithLazy().
124 //
125 // Similar to [With], fields added to the child don't affect the parent,
126 // and vice versa. Also, the keys in key-value pairs should be strings. In development,
127 // passing a non-string key panics, while in production it logs an error and skips the pair.
128 // Passing an orphaned key has the same behavior.
129 func (s *SugaredLogger) WithLazy(args ...interface{}) *SugaredLogger {
130 return &SugaredLogger{base: s.base.WithLazy(s.sweetenFields(args)...)}
131 }
132 133 // Level reports the minimum enabled level for this logger.
134 //
135 // For NopLoggers, this is [zapcore.InvalidLevel].
136 func (s *SugaredLogger) Level() zapcore.Level {
137 return zapcore.LevelOf(s.base.core)
138 }
139 140 // Log logs the provided arguments at provided level.
141 // Spaces are added between arguments when neither is a string.
142 func (s *SugaredLogger) Log(lvl zapcore.Level, args ...interface{}) {
143 s.log(lvl, "", args, nil)
144 }
145 146 // Debug logs the provided arguments at [DebugLevel].
147 // Spaces are added between arguments when neither is a string.
148 func (s *SugaredLogger) Debug(args ...interface{}) {
149 s.log(DebugLevel, "", args, nil)
150 }
151 152 // Info logs the provided arguments at [InfoLevel].
153 // Spaces are added between arguments when neither is a string.
154 func (s *SugaredLogger) Info(args ...interface{}) {
155 s.log(InfoLevel, "", args, nil)
156 }
157 158 // Warn logs the provided arguments at [WarnLevel].
159 // Spaces are added between arguments when neither is a string.
160 func (s *SugaredLogger) Warn(args ...interface{}) {
161 s.log(WarnLevel, "", args, nil)
162 }
163 164 // Error logs the provided arguments at [ErrorLevel].
165 // Spaces are added between arguments when neither is a string.
166 func (s *SugaredLogger) Error(args ...interface{}) {
167 s.log(ErrorLevel, "", args, nil)
168 }
169 170 // DPanic logs the provided arguments at [DPanicLevel].
171 // In development, the logger then panics. (See [DPanicLevel] for details.)
172 // Spaces are added between arguments when neither is a string.
173 func (s *SugaredLogger) DPanic(args ...interface{}) {
174 s.log(DPanicLevel, "", args, nil)
175 }
176 177 // Panic constructs a message with the provided arguments and panics.
178 // Spaces are added between arguments when neither is a string.
179 func (s *SugaredLogger) Panic(args ...interface{}) {
180 s.log(PanicLevel, "", args, nil)
181 }
182 183 // Fatal constructs a message with the provided arguments and calls os.Exit.
184 // Spaces are added between arguments when neither is a string.
185 func (s *SugaredLogger) Fatal(args ...interface{}) {
186 s.log(FatalLevel, "", args, nil)
187 }
188 189 // Logf formats the message according to the format specifier
190 // and logs it at provided level.
191 func (s *SugaredLogger) Logf(lvl zapcore.Level, template string, args ...interface{}) {
192 s.log(lvl, template, args, nil)
193 }
194 195 // Debugf formats the message according to the format specifier
196 // and logs it at [DebugLevel].
197 func (s *SugaredLogger) Debugf(template string, args ...interface{}) {
198 s.log(DebugLevel, template, args, nil)
199 }
200 201 // Infof formats the message according to the format specifier
202 // and logs it at [InfoLevel].
203 func (s *SugaredLogger) Infof(template string, args ...interface{}) {
204 s.log(InfoLevel, template, args, nil)
205 }
206 207 // Warnf formats the message according to the format specifier
208 // and logs it at [WarnLevel].
209 func (s *SugaredLogger) Warnf(template string, args ...interface{}) {
210 s.log(WarnLevel, template, args, nil)
211 }
212 213 // Errorf formats the message according to the format specifier
214 // and logs it at [ErrorLevel].
215 func (s *SugaredLogger) Errorf(template string, args ...interface{}) {
216 s.log(ErrorLevel, template, args, nil)
217 }
218 219 // DPanicf formats the message according to the format specifier
220 // and logs it at [DPanicLevel].
221 // In development, the logger then panics. (See [DPanicLevel] for details.)
222 func (s *SugaredLogger) DPanicf(template string, args ...interface{}) {
223 s.log(DPanicLevel, template, args, nil)
224 }
225 226 // Panicf formats the message according to the format specifier
227 // and panics.
228 func (s *SugaredLogger) Panicf(template string, args ...interface{}) {
229 s.log(PanicLevel, template, args, nil)
230 }
231 232 // Fatalf formats the message according to the format specifier
233 // and calls os.Exit.
234 func (s *SugaredLogger) Fatalf(template string, args ...interface{}) {
235 s.log(FatalLevel, template, args, nil)
236 }
237 238 // Logw logs a message with some additional context. The variadic key-value
239 // pairs are treated as they are in With.
240 func (s *SugaredLogger) Logw(lvl zapcore.Level, msg string, keysAndValues ...interface{}) {
241 s.log(lvl, msg, nil, keysAndValues)
242 }
243 244 // Debugw logs a message with some additional context. The variadic key-value
245 // pairs are treated as they are in With.
246 //
247 // When debug-level logging is disabled, this is much faster than
248 //
249 // s.With(keysAndValues).Debug(msg)
250 func (s *SugaredLogger) Debugw(msg string, keysAndValues ...interface{}) {
251 s.log(DebugLevel, msg, nil, keysAndValues)
252 }
253 254 // Infow logs a message with some additional context. The variadic key-value
255 // pairs are treated as they are in With.
256 func (s *SugaredLogger) Infow(msg string, keysAndValues ...interface{}) {
257 s.log(InfoLevel, msg, nil, keysAndValues)
258 }
259 260 // Warnw logs a message with some additional context. The variadic key-value
261 // pairs are treated as they are in With.
262 func (s *SugaredLogger) Warnw(msg string, keysAndValues ...interface{}) {
263 s.log(WarnLevel, msg, nil, keysAndValues)
264 }
265 266 // Errorw logs a message with some additional context. The variadic key-value
267 // pairs are treated as they are in With.
268 func (s *SugaredLogger) Errorw(msg string, keysAndValues ...interface{}) {
269 s.log(ErrorLevel, msg, nil, keysAndValues)
270 }
271 272 // DPanicw logs a message with some additional context. In development, the
273 // logger then panics. (See DPanicLevel for details.) The variadic key-value
274 // pairs are treated as they are in With.
275 func (s *SugaredLogger) DPanicw(msg string, keysAndValues ...interface{}) {
276 s.log(DPanicLevel, msg, nil, keysAndValues)
277 }
278 279 // Panicw logs a message with some additional context, then panics. The
280 // variadic key-value pairs are treated as they are in With.
281 func (s *SugaredLogger) Panicw(msg string, keysAndValues ...interface{}) {
282 s.log(PanicLevel, msg, nil, keysAndValues)
283 }
284 285 // Fatalw logs a message with some additional context, then calls os.Exit. The
286 // variadic key-value pairs are treated as they are in With.
287 func (s *SugaredLogger) Fatalw(msg string, keysAndValues ...interface{}) {
288 s.log(FatalLevel, msg, nil, keysAndValues)
289 }
290 291 // Logln logs a message at provided level.
292 // Spaces are always added between arguments.
293 func (s *SugaredLogger) Logln(lvl zapcore.Level, args ...interface{}) {
294 s.logln(lvl, args, nil)
295 }
296 297 // Debugln logs a message at [DebugLevel].
298 // Spaces are always added between arguments.
299 func (s *SugaredLogger) Debugln(args ...interface{}) {
300 s.logln(DebugLevel, args, nil)
301 }
302 303 // Infoln logs a message at [InfoLevel].
304 // Spaces are always added between arguments.
305 func (s *SugaredLogger) Infoln(args ...interface{}) {
306 s.logln(InfoLevel, args, nil)
307 }
308 309 // Warnln logs a message at [WarnLevel].
310 // Spaces are always added between arguments.
311 func (s *SugaredLogger) Warnln(args ...interface{}) {
312 s.logln(WarnLevel, args, nil)
313 }
314 315 // Errorln logs a message at [ErrorLevel].
316 // Spaces are always added between arguments.
317 func (s *SugaredLogger) Errorln(args ...interface{}) {
318 s.logln(ErrorLevel, args, nil)
319 }
320 321 // DPanicln logs a message at [DPanicLevel].
322 // In development, the logger then panics. (See [DPanicLevel] for details.)
323 // Spaces are always added between arguments.
324 func (s *SugaredLogger) DPanicln(args ...interface{}) {
325 s.logln(DPanicLevel, args, nil)
326 }
327 328 // Panicln logs a message at [PanicLevel] and panics.
329 // Spaces are always added between arguments.
330 func (s *SugaredLogger) Panicln(args ...interface{}) {
331 s.logln(PanicLevel, args, nil)
332 }
333 334 // Fatalln logs a message at [FatalLevel] and calls os.Exit.
335 // Spaces are always added between arguments.
336 func (s *SugaredLogger) Fatalln(args ...interface{}) {
337 s.logln(FatalLevel, args, nil)
338 }
339 340 // Sync flushes any buffered log entries.
341 func (s *SugaredLogger) Sync() error {
342 return s.base.Sync()
343 }
344 345 // log message with Sprint, Sprintf, or neither.
346 func (s *SugaredLogger) log(lvl zapcore.Level, template string, fmtArgs []interface{}, context []interface{}) {
347 // If logging at this level is completely disabled, skip the overhead of
348 // string formatting.
349 if lvl < DPanicLevel && !s.base.Core().Enabled(lvl) {
350 return
351 }
352 353 msg := getMessage(template, fmtArgs)
354 if ce := s.base.Check(lvl, msg); ce != nil {
355 ce.Write(s.sweetenFields(context)...)
356 }
357 }
358 359 // logln message with Sprintln
360 func (s *SugaredLogger) logln(lvl zapcore.Level, fmtArgs []interface{}, context []interface{}) {
361 if lvl < DPanicLevel && !s.base.Core().Enabled(lvl) {
362 return
363 }
364 365 msg := getMessageln(fmtArgs)
366 if ce := s.base.Check(lvl, msg); ce != nil {
367 ce.Write(s.sweetenFields(context)...)
368 }
369 }
370 371 // getMessage format with Sprint, Sprintf, or neither.
372 func getMessage(template string, fmtArgs []interface{}) string {
373 if len(fmtArgs) == 0 {
374 return template
375 }
376 377 if template != "" {
378 return fmt.Sprintf(template, fmtArgs...)
379 }
380 381 if len(fmtArgs) == 1 {
382 if str, ok := fmtArgs[0].(string); ok {
383 return str
384 }
385 }
386 return fmt.Sprint(fmtArgs...)
387 }
388 389 // getMessageln format with Sprintln.
390 func getMessageln(fmtArgs []interface{}) string {
391 msg := fmt.Sprintln(fmtArgs...)
392 return msg[:len(msg)-1]
393 }
394 395 func (s *SugaredLogger) sweetenFields(args []interface{}) []Field {
396 if len(args) == 0 {
397 return nil
398 }
399 400 var (
401 // Allocate enough space for the worst case; if users pass only structured
402 // fields, we shouldn't penalize them with extra allocations.
403 fields = make([]Field, 0, len(args))
404 invalid invalidPairs
405 seenError bool
406 )
407 408 for i := 0; i < len(args); {
409 // This is a strongly-typed field. Consume it and move on.
410 if f, ok := args[i].(Field); ok {
411 fields = append(fields, f)
412 i++
413 continue
414 }
415 416 // If it is an error, consume it and move on.
417 if err, ok := args[i].(error); ok {
418 if !seenError {
419 seenError = true
420 fields = append(fields, Error(err))
421 } else {
422 s.base.Error(_multipleErrMsg, Error(err))
423 }
424 i++
425 continue
426 }
427 428 // Make sure this element isn't a dangling key.
429 if i == len(args)-1 {
430 s.base.Error(_oddNumberErrMsg, Any("ignored", args[i]))
431 break
432 }
433 434 // Consume this value and the next, treating them as a key-value pair. If the
435 // key isn't a string, add this pair to the slice of invalid pairs.
436 key, val := args[i], args[i+1]
437 if keyStr, ok := key.(string); !ok {
438 // Subsequent errors are likely, so allocate once up front.
439 if cap(invalid) == 0 {
440 invalid = make(invalidPairs, 0, len(args)/2)
441 }
442 invalid = append(invalid, invalidPair{i, key, val})
443 } else {
444 fields = append(fields, Any(keyStr, val))
445 }
446 i += 2
447 }
448 449 // If we encountered any invalid key-value pairs, log an error.
450 if len(invalid) > 0 {
451 s.base.Error(_nonStringKeyErrMsg, Array("invalid", invalid))
452 }
453 return fields
454 }
455 456 type invalidPair struct {
457 position int
458 key, value interface{}
459 }
460 461 func (p invalidPair) MarshalLogObject(enc zapcore.ObjectEncoder) error {
462 enc.AddInt64("position", int64(p.position))
463 Any("key", p.key).AddTo(enc)
464 Any("value", p.value).AddTo(enc)
465 return nil
466 }
467 468 type invalidPairs []invalidPair
469 470 func (ps invalidPairs) MarshalLogArray(enc zapcore.ArrayEncoder) error {
471 var err error
472 for i := range ps {
473 err = multierr.Append(err, enc.AppendObject(ps[i]))
474 }
475 return err
476 }
477