blob: bbb745db5bdc3ee9c8193390228b1ea5cff0657c [file] [log] [blame]
Don Newton7577f072020-01-06 12:41:11 -05001// 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
David K. Bainbridgee05cf0c2021-08-19 03:16:50 +000035var (
36 _minTimeInt64 = time.Unix(0, math.MinInt64)
37 _maxTimeInt64 = time.Unix(0, math.MaxInt64)
38)
39
Don Newton7577f072020-01-06 12:41:11 -050040// 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
David K. Bainbridgee05cf0c2021-08-19 03:16:50 +000046// 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
Don Newton7577f072020-01-06 12:41:11 -050052// 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
David K. Bainbridgee05cf0c2021-08-19 03:16:50 +000070// 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
Don Newton7577f072020-01-06 12:41:11 -050079// 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
David K. Bainbridgee05cf0c2021-08-19 03:16:50 +000093// 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
Don Newton7577f072020-01-06 12:41:11 -0500102// 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
David K. Bainbridgee05cf0c2021-08-19 03:16:50 +0000109// 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
Don Newton7577f072020-01-06 12:41:11 -0500118// 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
David K. Bainbridgee05cf0c2021-08-19 03:16:50 +0000125// 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
Don Newton7577f072020-01-06 12:41:11 -0500134// 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
David K. Bainbridgee05cf0c2021-08-19 03:16:50 +0000141// 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
Don Newton7577f072020-01-06 12:41:11 -0500150// 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
David K. Bainbridgee05cf0c2021-08-19 03:16:50 +0000155// 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
Don Newton7577f072020-01-06 12:41:11 -0500164// 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
David K. Bainbridgee05cf0c2021-08-19 03:16:50 +0000169// 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
Don Newton7577f072020-01-06 12:41:11 -0500178// 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
David K. Bainbridgee05cf0c2021-08-19 03:16:50 +0000183// 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
Don Newton7577f072020-01-06 12:41:11 -0500192// 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
David K. Bainbridgee05cf0c2021-08-19 03:16:50 +0000197// 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
Don Newton7577f072020-01-06 12:41:11 -0500206// 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
David K. Bainbridgee05cf0c2021-08-19 03:16:50 +0000211// 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
Don Newton7577f072020-01-06 12:41:11 -0500220// 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
David K. Bainbridgee05cf0c2021-08-19 03:16:50 +0000225// 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
Don Newton7577f072020-01-06 12:41:11 -0500234// 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
David K. Bainbridgee05cf0c2021-08-19 03:16:50 +0000239// 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
Don Newton7577f072020-01-06 12:41:11 -0500248// 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
David K. Bainbridgee05cf0c2021-08-19 03:16:50 +0000253// 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
Don Newton7577f072020-01-06 12:41:11 -0500262// 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
David K. Bainbridgee05cf0c2021-08-19 03:16:50 +0000267// 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
Don Newton7577f072020-01-06 12:41:11 -0500276// 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
David K. Bainbridgee05cf0c2021-08-19 03:16:50 +0000281// 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
Don Newton7577f072020-01-06 12:41:11 -0500290// 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
David K. Bainbridgee05cf0c2021-08-19 03:16:50 +0000295// 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
Don Newton7577f072020-01-06 12:41:11 -0500304// 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
David K. Bainbridgee05cf0c2021-08-19 03:16:50 +0000309// 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
Don Newton7577f072020-01-06 12:41:11 -0500318// 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 {
David K. Bainbridgee05cf0c2021-08-19 03:16:50 +0000347 if val.Before(_minTimeInt64) || val.After(_maxTimeInt64) {
348 return Field{Key: key, Type: zapcore.TimeFullType, Interface: val}
349 }
Don Newton7577f072020-01-06 12:41:11 -0500350 return Field{Key: key, Type: zapcore.TimeType, Integer: val.UnixNano(), Interface: val.Location()}
351}
352
David K. Bainbridgee05cf0c2021-08-19 03:16:50 +0000353// 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
Don Newton7577f072020-01-06 12:41:11 -0500362// 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 {
David K. Bainbridgee05cf0c2021-08-19 03:16:50 +0000367 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 {
Don Newton7577f072020-01-06 12:41:11 -0500373 // 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.
David K. Bainbridgee05cf0c2021-08-19 03:16:50 +0000377 return String(key, takeStacktrace(skip+1)) // skip StackSkip
Don Newton7577f072020-01-06 12:41:11 -0500378}
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
David K. Bainbridgee05cf0c2021-08-19 03:16:50 +0000386// 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
Don Newton7577f072020-01-06 12:41:11 -0500395// 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
David K. Bainbridgee05cf0c2021-08-19 03:16:50 +0000403// 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
Don Newton7577f072020-01-06 12:41:11 -0500413// 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)
David K. Bainbridgee05cf0c2021-08-19 03:16:50 +0000428 case *bool:
429 return Boolp(key, val)
Don Newton7577f072020-01-06 12:41:11 -0500430 case []bool:
431 return Bools(key, val)
432 case complex128:
433 return Complex128(key, val)
David K. Bainbridgee05cf0c2021-08-19 03:16:50 +0000434 case *complex128:
435 return Complex128p(key, val)
Don Newton7577f072020-01-06 12:41:11 -0500436 case []complex128:
437 return Complex128s(key, val)
438 case complex64:
439 return Complex64(key, val)
David K. Bainbridgee05cf0c2021-08-19 03:16:50 +0000440 case *complex64:
441 return Complex64p(key, val)
Don Newton7577f072020-01-06 12:41:11 -0500442 case []complex64:
443 return Complex64s(key, val)
444 case float64:
445 return Float64(key, val)
David K. Bainbridgee05cf0c2021-08-19 03:16:50 +0000446 case *float64:
447 return Float64p(key, val)
Don Newton7577f072020-01-06 12:41:11 -0500448 case []float64:
449 return Float64s(key, val)
450 case float32:
451 return Float32(key, val)
David K. Bainbridgee05cf0c2021-08-19 03:16:50 +0000452 case *float32:
453 return Float32p(key, val)
Don Newton7577f072020-01-06 12:41:11 -0500454 case []float32:
455 return Float32s(key, val)
456 case int:
457 return Int(key, val)
David K. Bainbridgee05cf0c2021-08-19 03:16:50 +0000458 case *int:
459 return Intp(key, val)
Don Newton7577f072020-01-06 12:41:11 -0500460 case []int:
461 return Ints(key, val)
462 case int64:
463 return Int64(key, val)
David K. Bainbridgee05cf0c2021-08-19 03:16:50 +0000464 case *int64:
465 return Int64p(key, val)
Don Newton7577f072020-01-06 12:41:11 -0500466 case []int64:
467 return Int64s(key, val)
468 case int32:
469 return Int32(key, val)
David K. Bainbridgee05cf0c2021-08-19 03:16:50 +0000470 case *int32:
471 return Int32p(key, val)
Don Newton7577f072020-01-06 12:41:11 -0500472 case []int32:
473 return Int32s(key, val)
474 case int16:
475 return Int16(key, val)
David K. Bainbridgee05cf0c2021-08-19 03:16:50 +0000476 case *int16:
477 return Int16p(key, val)
Don Newton7577f072020-01-06 12:41:11 -0500478 case []int16:
479 return Int16s(key, val)
480 case int8:
481 return Int8(key, val)
David K. Bainbridgee05cf0c2021-08-19 03:16:50 +0000482 case *int8:
483 return Int8p(key, val)
Don Newton7577f072020-01-06 12:41:11 -0500484 case []int8:
485 return Int8s(key, val)
486 case string:
487 return String(key, val)
David K. Bainbridgee05cf0c2021-08-19 03:16:50 +0000488 case *string:
489 return Stringp(key, val)
Don Newton7577f072020-01-06 12:41:11 -0500490 case []string:
491 return Strings(key, val)
492 case uint:
493 return Uint(key, val)
David K. Bainbridgee05cf0c2021-08-19 03:16:50 +0000494 case *uint:
495 return Uintp(key, val)
Don Newton7577f072020-01-06 12:41:11 -0500496 case []uint:
497 return Uints(key, val)
498 case uint64:
499 return Uint64(key, val)
David K. Bainbridgee05cf0c2021-08-19 03:16:50 +0000500 case *uint64:
501 return Uint64p(key, val)
Don Newton7577f072020-01-06 12:41:11 -0500502 case []uint64:
503 return Uint64s(key, val)
504 case uint32:
505 return Uint32(key, val)
David K. Bainbridgee05cf0c2021-08-19 03:16:50 +0000506 case *uint32:
507 return Uint32p(key, val)
Don Newton7577f072020-01-06 12:41:11 -0500508 case []uint32:
509 return Uint32s(key, val)
510 case uint16:
511 return Uint16(key, val)
David K. Bainbridgee05cf0c2021-08-19 03:16:50 +0000512 case *uint16:
513 return Uint16p(key, val)
Don Newton7577f072020-01-06 12:41:11 -0500514 case []uint16:
515 return Uint16s(key, val)
516 case uint8:
517 return Uint8(key, val)
David K. Bainbridgee05cf0c2021-08-19 03:16:50 +0000518 case *uint8:
519 return Uint8p(key, val)
Don Newton7577f072020-01-06 12:41:11 -0500520 case []byte:
521 return Binary(key, val)
522 case uintptr:
523 return Uintptr(key, val)
David K. Bainbridgee05cf0c2021-08-19 03:16:50 +0000524 case *uintptr:
525 return Uintptrp(key, val)
Don Newton7577f072020-01-06 12:41:11 -0500526 case []uintptr:
527 return Uintptrs(key, val)
528 case time.Time:
529 return Time(key, val)
David K. Bainbridgee05cf0c2021-08-19 03:16:50 +0000530 case *time.Time:
531 return Timep(key, val)
Don Newton7577f072020-01-06 12:41:11 -0500532 case []time.Time:
533 return Times(key, val)
534 case time.Duration:
535 return Duration(key, val)
David K. Bainbridgee05cf0c2021-08-19 03:16:50 +0000536 case *time.Duration:
537 return Durationp(key, val)
Don Newton7577f072020-01-06 12:41:11 -0500538 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}