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	"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
35var (
36	_minTimeInt64 = time.Unix(0, math.MinInt64)
37	_maxTimeInt64 = time.Unix(0, math.MaxInt64)
38)
39
40// 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
46// 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
52// 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
70// 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
79// 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
93// 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
102// 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
109// 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
118// 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
125// 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
134// 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
141// 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
150// 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
155// 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
164// 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
169// 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
178// 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
183// 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
192// 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
197// 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
206// 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
211// 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
220// 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
225// 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
234// 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
239// 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
248// 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
253// 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
262// 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
267// 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
276// 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
281// 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
290// 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
295// 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
304// 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
309// 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
318// 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 {
347	if val.Before(_minTimeInt64) || val.After(_maxTimeInt64) {
348		return Field{Key: key, Type: zapcore.TimeFullType, Interface: val}
349	}
350	return Field{Key: key, Type: zapcore.TimeType, Integer: val.UnixNano(), Interface: val.Location()}
351}
352
353// 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
362// 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 {
367	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 {
373	// 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.
377	return String(key, takeStacktrace(skip+1)) // skip StackSkip
378}
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
386// 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
395// 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
403// 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
413// 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)
428	case *bool:
429		return Boolp(key, val)
430	case []bool:
431		return Bools(key, val)
432	case complex128:
433		return Complex128(key, val)
434	case *complex128:
435		return Complex128p(key, val)
436	case []complex128:
437		return Complex128s(key, val)
438	case complex64:
439		return Complex64(key, val)
440	case *complex64:
441		return Complex64p(key, val)
442	case []complex64:
443		return Complex64s(key, val)
444	case float64:
445		return Float64(key, val)
446	case *float64:
447		return Float64p(key, val)
448	case []float64:
449		return Float64s(key, val)
450	case float32:
451		return Float32(key, val)
452	case *float32:
453		return Float32p(key, val)
454	case []float32:
455		return Float32s(key, val)
456	case int:
457		return Int(key, val)
458	case *int:
459		return Intp(key, val)
460	case []int:
461		return Ints(key, val)
462	case int64:
463		return Int64(key, val)
464	case *int64:
465		return Int64p(key, val)
466	case []int64:
467		return Int64s(key, val)
468	case int32:
469		return Int32(key, val)
470	case *int32:
471		return Int32p(key, val)
472	case []int32:
473		return Int32s(key, val)
474	case int16:
475		return Int16(key, val)
476	case *int16:
477		return Int16p(key, val)
478	case []int16:
479		return Int16s(key, val)
480	case int8:
481		return Int8(key, val)
482	case *int8:
483		return Int8p(key, val)
484	case []int8:
485		return Int8s(key, val)
486	case string:
487		return String(key, val)
488	case *string:
489		return Stringp(key, val)
490	case []string:
491		return Strings(key, val)
492	case uint:
493		return Uint(key, val)
494	case *uint:
495		return Uintp(key, val)
496	case []uint:
497		return Uints(key, val)
498	case uint64:
499		return Uint64(key, val)
500	case *uint64:
501		return Uint64p(key, val)
502	case []uint64:
503		return Uint64s(key, val)
504	case uint32:
505		return Uint32(key, val)
506	case *uint32:
507		return Uint32p(key, val)
508	case []uint32:
509		return Uint32s(key, val)
510	case uint16:
511		return Uint16(key, val)
512	case *uint16:
513		return Uint16p(key, val)
514	case []uint16:
515		return Uint16s(key, val)
516	case uint8:
517		return Uint8(key, val)
518	case *uint8:
519		return Uint8p(key, val)
520	case []byte:
521		return Binary(key, val)
522	case uintptr:
523		return Uintptr(key, val)
524	case *uintptr:
525		return Uintptrp(key, val)
526	case []uintptr:
527		return Uintptrs(key, val)
528	case time.Time:
529		return Time(key, val)
530	case *time.Time:
531		return Timep(key, val)
532	case []time.Time:
533		return Times(key, val)
534	case time.Duration:
535		return Duration(key, val)
536	case *time.Duration:
537		return Durationp(key, val)
538	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}
550