blob: bbb745db5bdc3ee9c8193390228b1ea5cff0657c [file] [log] [blame]
William Kurkianea869482019-04-09 15:16:11 -04001// 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 "math"
26 "time"
27
28 "go.uber.org/zap/zapcore"
29)
30
31// Field is an alias for Field. Aliasing this type dramatically
32// improves the navigability of this package's API documentation.
33type Field = zapcore.Field
34
khenaidoo106c61a2021-08-11 18:05:46 -040035var (
36 _minTimeInt64 = time.Unix(0, math.MinInt64)
37 _maxTimeInt64 = time.Unix(0, math.MaxInt64)
38)
39
William Kurkianea869482019-04-09 15:16:11 -040040// Skip constructs a no-op field, which is often useful when handling invalid
41// inputs in other Field constructors.
42func Skip() Field {
43 return Field{Type: zapcore.SkipType}
44}
45
khenaidoo106c61a2021-08-11 18:05:46 -040046// nilField returns a field which will marshal explicitly as nil. See motivation
47// in https://github.com/uber-go/zap/issues/753 . If we ever make breaking
48// changes and add zapcore.NilType and zapcore.ObjectEncoder.AddNil, the
49// implementation here should be changed to reflect that.
50func nilField(key string) Field { return Reflect(key, nil) }
51
William Kurkianea869482019-04-09 15:16:11 -040052// Binary constructs a field that carries an opaque binary blob.
53//
54// Binary data is serialized in an encoding-appropriate format. For example,
55// zap's JSON encoder base64-encodes binary blobs. To log UTF-8 encoded text,
56// use ByteString.
57func Binary(key string, val []byte) Field {
58 return Field{Key: key, Type: zapcore.BinaryType, Interface: val}
59}
60
61// Bool constructs a field that carries a bool.
62func Bool(key string, val bool) Field {
63 var ival int64
64 if val {
65 ival = 1
66 }
67 return Field{Key: key, Type: zapcore.BoolType, Integer: ival}
68}
69
khenaidoo106c61a2021-08-11 18:05:46 -040070// Boolp constructs a field that carries a *bool. The returned Field will safely
71// and explicitly represent `nil` when appropriate.
72func Boolp(key string, val *bool) Field {
73 if val == nil {
74 return nilField(key)
75 }
76 return Bool(key, *val)
77}
78
William Kurkianea869482019-04-09 15:16:11 -040079// ByteString constructs a field that carries UTF-8 encoded text as a []byte.
80// To log opaque binary blobs (which aren't necessarily valid UTF-8), use
81// Binary.
82func ByteString(key string, val []byte) Field {
83 return Field{Key: key, Type: zapcore.ByteStringType, Interface: val}
84}
85
86// Complex128 constructs a field that carries a complex number. Unlike most
87// numeric fields, this costs an allocation (to convert the complex128 to
88// interface{}).
89func Complex128(key string, val complex128) Field {
90 return Field{Key: key, Type: zapcore.Complex128Type, Interface: val}
91}
92
khenaidoo106c61a2021-08-11 18:05:46 -040093// Complex128p constructs a field that carries a *complex128. The returned Field will safely
94// and explicitly represent `nil` when appropriate.
95func Complex128p(key string, val *complex128) Field {
96 if val == nil {
97 return nilField(key)
98 }
99 return Complex128(key, *val)
100}
101
William Kurkianea869482019-04-09 15:16:11 -0400102// Complex64 constructs a field that carries a complex number. Unlike most
103// numeric fields, this costs an allocation (to convert the complex64 to
104// interface{}).
105func Complex64(key string, val complex64) Field {
106 return Field{Key: key, Type: zapcore.Complex64Type, Interface: val}
107}
108
khenaidoo106c61a2021-08-11 18:05:46 -0400109// Complex64p constructs a field that carries a *complex64. The returned Field will safely
110// and explicitly represent `nil` when appropriate.
111func Complex64p(key string, val *complex64) Field {
112 if val == nil {
113 return nilField(key)
114 }
115 return Complex64(key, *val)
116}
117
William Kurkianea869482019-04-09 15:16:11 -0400118// Float64 constructs a field that carries a float64. The way the
119// floating-point value is represented is encoder-dependent, so marshaling is
120// necessarily lazy.
121func Float64(key string, val float64) Field {
122 return Field{Key: key, Type: zapcore.Float64Type, Integer: int64(math.Float64bits(val))}
123}
124
khenaidoo106c61a2021-08-11 18:05:46 -0400125// Float64p constructs a field that carries a *float64. The returned Field will safely
126// and explicitly represent `nil` when appropriate.
127func Float64p(key string, val *float64) Field {
128 if val == nil {
129 return nilField(key)
130 }
131 return Float64(key, *val)
132}
133
William Kurkianea869482019-04-09 15:16:11 -0400134// Float32 constructs a field that carries a float32. The way the
135// floating-point value is represented is encoder-dependent, so marshaling is
136// necessarily lazy.
137func Float32(key string, val float32) Field {
138 return Field{Key: key, Type: zapcore.Float32Type, Integer: int64(math.Float32bits(val))}
139}
140
khenaidoo106c61a2021-08-11 18:05:46 -0400141// Float32p constructs a field that carries a *float32. The returned Field will safely
142// and explicitly represent `nil` when appropriate.
143func Float32p(key string, val *float32) Field {
144 if val == nil {
145 return nilField(key)
146 }
147 return Float32(key, *val)
148}
149
William Kurkianea869482019-04-09 15:16:11 -0400150// Int constructs a field with the given key and value.
151func Int(key string, val int) Field {
152 return Int64(key, int64(val))
153}
154
khenaidoo106c61a2021-08-11 18:05:46 -0400155// Intp constructs a field that carries a *int. The returned Field will safely
156// and explicitly represent `nil` when appropriate.
157func Intp(key string, val *int) Field {
158 if val == nil {
159 return nilField(key)
160 }
161 return Int(key, *val)
162}
163
William Kurkianea869482019-04-09 15:16:11 -0400164// Int64 constructs a field with the given key and value.
165func Int64(key string, val int64) Field {
166 return Field{Key: key, Type: zapcore.Int64Type, Integer: val}
167}
168
khenaidoo106c61a2021-08-11 18:05:46 -0400169// Int64p constructs a field that carries a *int64. The returned Field will safely
170// and explicitly represent `nil` when appropriate.
171func Int64p(key string, val *int64) Field {
172 if val == nil {
173 return nilField(key)
174 }
175 return Int64(key, *val)
176}
177
William Kurkianea869482019-04-09 15:16:11 -0400178// Int32 constructs a field with the given key and value.
179func Int32(key string, val int32) Field {
180 return Field{Key: key, Type: zapcore.Int32Type, Integer: int64(val)}
181}
182
khenaidoo106c61a2021-08-11 18:05:46 -0400183// Int32p constructs a field that carries a *int32. The returned Field will safely
184// and explicitly represent `nil` when appropriate.
185func Int32p(key string, val *int32) Field {
186 if val == nil {
187 return nilField(key)
188 }
189 return Int32(key, *val)
190}
191
William Kurkianea869482019-04-09 15:16:11 -0400192// Int16 constructs a field with the given key and value.
193func Int16(key string, val int16) Field {
194 return Field{Key: key, Type: zapcore.Int16Type, Integer: int64(val)}
195}
196
khenaidoo106c61a2021-08-11 18:05:46 -0400197// Int16p constructs a field that carries a *int16. The returned Field will safely
198// and explicitly represent `nil` when appropriate.
199func Int16p(key string, val *int16) Field {
200 if val == nil {
201 return nilField(key)
202 }
203 return Int16(key, *val)
204}
205
William Kurkianea869482019-04-09 15:16:11 -0400206// Int8 constructs a field with the given key and value.
207func Int8(key string, val int8) Field {
208 return Field{Key: key, Type: zapcore.Int8Type, Integer: int64(val)}
209}
210
khenaidoo106c61a2021-08-11 18:05:46 -0400211// Int8p constructs a field that carries a *int8. The returned Field will safely
212// and explicitly represent `nil` when appropriate.
213func Int8p(key string, val *int8) Field {
214 if val == nil {
215 return nilField(key)
216 }
217 return Int8(key, *val)
218}
219
William Kurkianea869482019-04-09 15:16:11 -0400220// String constructs a field with the given key and value.
221func String(key string, val string) Field {
222 return Field{Key: key, Type: zapcore.StringType, String: val}
223}
224
khenaidoo106c61a2021-08-11 18:05:46 -0400225// Stringp constructs a field that carries a *string. The returned Field will safely
226// and explicitly represent `nil` when appropriate.
227func Stringp(key string, val *string) Field {
228 if val == nil {
229 return nilField(key)
230 }
231 return String(key, *val)
232}
233
William Kurkianea869482019-04-09 15:16:11 -0400234// Uint constructs a field with the given key and value.
235func Uint(key string, val uint) Field {
236 return Uint64(key, uint64(val))
237}
238
khenaidoo106c61a2021-08-11 18:05:46 -0400239// Uintp constructs a field that carries a *uint. The returned Field will safely
240// and explicitly represent `nil` when appropriate.
241func Uintp(key string, val *uint) Field {
242 if val == nil {
243 return nilField(key)
244 }
245 return Uint(key, *val)
246}
247
William Kurkianea869482019-04-09 15:16:11 -0400248// Uint64 constructs a field with the given key and value.
249func Uint64(key string, val uint64) Field {
250 return Field{Key: key, Type: zapcore.Uint64Type, Integer: int64(val)}
251}
252
khenaidoo106c61a2021-08-11 18:05:46 -0400253// Uint64p constructs a field that carries a *uint64. The returned Field will safely
254// and explicitly represent `nil` when appropriate.
255func Uint64p(key string, val *uint64) Field {
256 if val == nil {
257 return nilField(key)
258 }
259 return Uint64(key, *val)
260}
261
William Kurkianea869482019-04-09 15:16:11 -0400262// Uint32 constructs a field with the given key and value.
263func Uint32(key string, val uint32) Field {
264 return Field{Key: key, Type: zapcore.Uint32Type, Integer: int64(val)}
265}
266
khenaidoo106c61a2021-08-11 18:05:46 -0400267// Uint32p constructs a field that carries a *uint32. The returned Field will safely
268// and explicitly represent `nil` when appropriate.
269func Uint32p(key string, val *uint32) Field {
270 if val == nil {
271 return nilField(key)
272 }
273 return Uint32(key, *val)
274}
275
William Kurkianea869482019-04-09 15:16:11 -0400276// Uint16 constructs a field with the given key and value.
277func Uint16(key string, val uint16) Field {
278 return Field{Key: key, Type: zapcore.Uint16Type, Integer: int64(val)}
279}
280
khenaidoo106c61a2021-08-11 18:05:46 -0400281// Uint16p constructs a field that carries a *uint16. The returned Field will safely
282// and explicitly represent `nil` when appropriate.
283func Uint16p(key string, val *uint16) Field {
284 if val == nil {
285 return nilField(key)
286 }
287 return Uint16(key, *val)
288}
289
William Kurkianea869482019-04-09 15:16:11 -0400290// Uint8 constructs a field with the given key and value.
291func Uint8(key string, val uint8) Field {
292 return Field{Key: key, Type: zapcore.Uint8Type, Integer: int64(val)}
293}
294
khenaidoo106c61a2021-08-11 18:05:46 -0400295// Uint8p constructs a field that carries a *uint8. The returned Field will safely
296// and explicitly represent `nil` when appropriate.
297func Uint8p(key string, val *uint8) Field {
298 if val == nil {
299 return nilField(key)
300 }
301 return Uint8(key, *val)
302}
303
William Kurkianea869482019-04-09 15:16:11 -0400304// Uintptr constructs a field with the given key and value.
305func Uintptr(key string, val uintptr) Field {
306 return Field{Key: key, Type: zapcore.UintptrType, Integer: int64(val)}
307}
308
khenaidoo106c61a2021-08-11 18:05:46 -0400309// Uintptrp constructs a field that carries a *uintptr. The returned Field will safely
310// and explicitly represent `nil` when appropriate.
311func Uintptrp(key string, val *uintptr) Field {
312 if val == nil {
313 return nilField(key)
314 }
315 return Uintptr(key, *val)
316}
317
William Kurkianea869482019-04-09 15:16:11 -0400318// Reflect constructs a field with the given key and an arbitrary object. It uses
319// an encoding-appropriate, reflection-based function to lazily serialize nearly
320// any object into the logging context, but it's relatively slow and
321// allocation-heavy. Outside tests, Any is always a better choice.
322//
323// If encoding fails (e.g., trying to serialize a map[int]string to JSON), Reflect
324// includes the error message in the final log output.
325func Reflect(key string, val interface{}) Field {
326 return Field{Key: key, Type: zapcore.ReflectType, Interface: val}
327}
328
329// Namespace creates a named, isolated scope within the logger's context. All
330// subsequent fields will be added to the new namespace.
331//
332// This helps prevent key collisions when injecting loggers into sub-components
333// or third-party libraries.
334func Namespace(key string) Field {
335 return Field{Key: key, Type: zapcore.NamespaceType}
336}
337
338// Stringer constructs a field with the given key and the output of the value's
339// String method. The Stringer's String method is called lazily.
340func Stringer(key string, val fmt.Stringer) Field {
341 return Field{Key: key, Type: zapcore.StringerType, Interface: val}
342}
343
344// Time constructs a Field with the given key and value. The encoder
345// controls how the time is serialized.
346func Time(key string, val time.Time) Field {
khenaidoo106c61a2021-08-11 18:05:46 -0400347 if val.Before(_minTimeInt64) || val.After(_maxTimeInt64) {
348 return Field{Key: key, Type: zapcore.TimeFullType, Interface: val}
349 }
William Kurkianea869482019-04-09 15:16:11 -0400350 return Field{Key: key, Type: zapcore.TimeType, Integer: val.UnixNano(), Interface: val.Location()}
351}
352
khenaidoo106c61a2021-08-11 18:05:46 -0400353// Timep constructs a field that carries a *time.Time. The returned Field will safely
354// and explicitly represent `nil` when appropriate.
355func Timep(key string, val *time.Time) Field {
356 if val == nil {
357 return nilField(key)
358 }
359 return Time(key, *val)
360}
361
William Kurkianea869482019-04-09 15:16:11 -0400362// Stack constructs a field that stores a stacktrace of the current goroutine
363// under provided key. Keep in mind that taking a stacktrace is eager and
364// expensive (relatively speaking); this function both makes an allocation and
365// takes about two microseconds.
366func Stack(key string) Field {
khenaidoo106c61a2021-08-11 18:05:46 -0400367 return StackSkip(key, 1) // skip Stack
368}
369
370// StackSkip constructs a field similarly to Stack, but also skips the given
371// number of frames from the top of the stacktrace.
372func StackSkip(key string, skip int) Field {
William Kurkianea869482019-04-09 15:16:11 -0400373 // Returning the stacktrace as a string costs an allocation, but saves us
374 // from expanding the zapcore.Field union struct to include a byte slice. Since
375 // taking a stacktrace is already so expensive (~10us), the extra allocation
376 // is okay.
khenaidoo106c61a2021-08-11 18:05:46 -0400377 return String(key, takeStacktrace(skip+1)) // skip StackSkip
William Kurkianea869482019-04-09 15:16:11 -0400378}
379
380// Duration constructs a field with the given key and value. The encoder
381// controls how the duration is serialized.
382func Duration(key string, val time.Duration) Field {
383 return Field{Key: key, Type: zapcore.DurationType, Integer: int64(val)}
384}
385
khenaidoo106c61a2021-08-11 18:05:46 -0400386// Durationp constructs a field that carries a *time.Duration. The returned Field will safely
387// and explicitly represent `nil` when appropriate.
388func Durationp(key string, val *time.Duration) Field {
389 if val == nil {
390 return nilField(key)
391 }
392 return Duration(key, *val)
393}
394
William Kurkianea869482019-04-09 15:16:11 -0400395// Object constructs a field with the given key and ObjectMarshaler. It
396// provides a flexible, but still type-safe and efficient, way to add map- or
397// struct-like user-defined types to the logging context. The struct's
398// MarshalLogObject method is called lazily.
399func Object(key string, val zapcore.ObjectMarshaler) Field {
400 return Field{Key: key, Type: zapcore.ObjectMarshalerType, Interface: val}
401}
402
khenaidoo106c61a2021-08-11 18:05:46 -0400403// Inline constructs a Field that is similar to Object, but it
404// will add the elements of the provided ObjectMarshaler to the
405// current namespace.
406func Inline(val zapcore.ObjectMarshaler) Field {
407 return zapcore.Field{
408 Type: zapcore.InlineMarshalerType,
409 Interface: val,
410 }
411}
412
William Kurkianea869482019-04-09 15:16:11 -0400413// Any takes a key and an arbitrary value and chooses the best way to represent
414// them as a field, falling back to a reflection-based approach only if
415// necessary.
416//
417// Since byte/uint8 and rune/int32 are aliases, Any can't differentiate between
418// them. To minimize surprises, []byte values are treated as binary blobs, byte
419// values are treated as uint8, and runes are always treated as integers.
420func Any(key string, value interface{}) Field {
421 switch val := value.(type) {
422 case zapcore.ObjectMarshaler:
423 return Object(key, val)
424 case zapcore.ArrayMarshaler:
425 return Array(key, val)
426 case bool:
427 return Bool(key, val)
khenaidoo106c61a2021-08-11 18:05:46 -0400428 case *bool:
429 return Boolp(key, val)
William Kurkianea869482019-04-09 15:16:11 -0400430 case []bool:
431 return Bools(key, val)
432 case complex128:
433 return Complex128(key, val)
khenaidoo106c61a2021-08-11 18:05:46 -0400434 case *complex128:
435 return Complex128p(key, val)
William Kurkianea869482019-04-09 15:16:11 -0400436 case []complex128:
437 return Complex128s(key, val)
438 case complex64:
439 return Complex64(key, val)
khenaidoo106c61a2021-08-11 18:05:46 -0400440 case *complex64:
441 return Complex64p(key, val)
William Kurkianea869482019-04-09 15:16:11 -0400442 case []complex64:
443 return Complex64s(key, val)
444 case float64:
445 return Float64(key, val)
khenaidoo106c61a2021-08-11 18:05:46 -0400446 case *float64:
447 return Float64p(key, val)
William Kurkianea869482019-04-09 15:16:11 -0400448 case []float64:
449 return Float64s(key, val)
450 case float32:
451 return Float32(key, val)
khenaidoo106c61a2021-08-11 18:05:46 -0400452 case *float32:
453 return Float32p(key, val)
William Kurkianea869482019-04-09 15:16:11 -0400454 case []float32:
455 return Float32s(key, val)
456 case int:
457 return Int(key, val)
khenaidoo106c61a2021-08-11 18:05:46 -0400458 case *int:
459 return Intp(key, val)
William Kurkianea869482019-04-09 15:16:11 -0400460 case []int:
461 return Ints(key, val)
462 case int64:
463 return Int64(key, val)
khenaidoo106c61a2021-08-11 18:05:46 -0400464 case *int64:
465 return Int64p(key, val)
William Kurkianea869482019-04-09 15:16:11 -0400466 case []int64:
467 return Int64s(key, val)
468 case int32:
469 return Int32(key, val)
khenaidoo106c61a2021-08-11 18:05:46 -0400470 case *int32:
471 return Int32p(key, val)
William Kurkianea869482019-04-09 15:16:11 -0400472 case []int32:
473 return Int32s(key, val)
474 case int16:
475 return Int16(key, val)
khenaidoo106c61a2021-08-11 18:05:46 -0400476 case *int16:
477 return Int16p(key, val)
William Kurkianea869482019-04-09 15:16:11 -0400478 case []int16:
479 return Int16s(key, val)
480 case int8:
481 return Int8(key, val)
khenaidoo106c61a2021-08-11 18:05:46 -0400482 case *int8:
483 return Int8p(key, val)
William Kurkianea869482019-04-09 15:16:11 -0400484 case []int8:
485 return Int8s(key, val)
486 case string:
487 return String(key, val)
khenaidoo106c61a2021-08-11 18:05:46 -0400488 case *string:
489 return Stringp(key, val)
William Kurkianea869482019-04-09 15:16:11 -0400490 case []string:
491 return Strings(key, val)
492 case uint:
493 return Uint(key, val)
khenaidoo106c61a2021-08-11 18:05:46 -0400494 case *uint:
495 return Uintp(key, val)
William Kurkianea869482019-04-09 15:16:11 -0400496 case []uint:
497 return Uints(key, val)
498 case uint64:
499 return Uint64(key, val)
khenaidoo106c61a2021-08-11 18:05:46 -0400500 case *uint64:
501 return Uint64p(key, val)
William Kurkianea869482019-04-09 15:16:11 -0400502 case []uint64:
503 return Uint64s(key, val)
504 case uint32:
505 return Uint32(key, val)
khenaidoo106c61a2021-08-11 18:05:46 -0400506 case *uint32:
507 return Uint32p(key, val)
William Kurkianea869482019-04-09 15:16:11 -0400508 case []uint32:
509 return Uint32s(key, val)
510 case uint16:
511 return Uint16(key, val)
khenaidoo106c61a2021-08-11 18:05:46 -0400512 case *uint16:
513 return Uint16p(key, val)
William Kurkianea869482019-04-09 15:16:11 -0400514 case []uint16:
515 return Uint16s(key, val)
516 case uint8:
517 return Uint8(key, val)
khenaidoo106c61a2021-08-11 18:05:46 -0400518 case *uint8:
519 return Uint8p(key, val)
William Kurkianea869482019-04-09 15:16:11 -0400520 case []byte:
521 return Binary(key, val)
522 case uintptr:
523 return Uintptr(key, val)
khenaidoo106c61a2021-08-11 18:05:46 -0400524 case *uintptr:
525 return Uintptrp(key, val)
William Kurkianea869482019-04-09 15:16:11 -0400526 case []uintptr:
527 return Uintptrs(key, val)
528 case time.Time:
529 return Time(key, val)
khenaidoo106c61a2021-08-11 18:05:46 -0400530 case *time.Time:
531 return Timep(key, val)
William Kurkianea869482019-04-09 15:16:11 -0400532 case []time.Time:
533 return Times(key, val)
534 case time.Duration:
535 return Duration(key, val)
khenaidoo106c61a2021-08-11 18:05:46 -0400536 case *time.Duration:
537 return Durationp(key, val)
William Kurkianea869482019-04-09 15:16:11 -0400538 case []time.Duration:
539 return Durations(key, val)
540 case error:
541 return NamedError(key, val)
542 case []error:
543 return Errors(key, val)
544 case fmt.Stringer:
545 return Stringer(key, val)
546 default:
547 return Reflect(key, val)
548 }
549}