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
	"math"
26
	"time"
27

28
	"go.uber.org/zap/internal/stacktrace"
29
	"go.uber.org/zap/zapcore"
30
)
31

32
// Field is an alias for Field. Aliasing this type dramatically
33
// improves the navigability of this package's API documentation.
34
type Field = zapcore.Field
35

36
var (
37
	_minTimeInt64 = time.Unix(0, math.MinInt64)
38
	_maxTimeInt64 = time.Unix(0, math.MaxInt64)
39
)
40

41
// Skip constructs a no-op field, which is often useful when handling invalid
42
// inputs in other Field constructors.
43
func Skip() Field {
44
	return Field{Type: zapcore.SkipType}
45
}
46

47
// nilField returns a field which will marshal explicitly as nil. See motivation
48
// in https://github.com/uber-go/zap/issues/753 . If we ever make breaking
49
// changes and add zapcore.NilType and zapcore.ObjectEncoder.AddNil, the
50
// implementation here should be changed to reflect that.
51
func nilField(key string) Field { return Reflect(key, nil) }
52

53
// Binary constructs a field that carries an opaque binary blob.
54
//
55
// Binary data is serialized in an encoding-appropriate format. For example,
56
// zap's JSON encoder base64-encodes binary blobs. To log UTF-8 encoded text,
57
// use ByteString.
58
func Binary(key string, val []byte) Field {
59
	return Field{Key: key, Type: zapcore.BinaryType, Interface: val}
60
}
61

62
// Bool constructs a field that carries a bool.
63
func Bool(key string, val bool) Field {
64
	var ival int64
65
	if val {
66
		ival = 1
67
	}
68
	return Field{Key: key, Type: zapcore.BoolType, Integer: ival}
69
}
70

71
// Boolp constructs a field that carries a *bool. The returned Field will safely
72
// and explicitly represent `nil` when appropriate.
73
func Boolp(key string, val *bool) Field {
74
	if val == nil {
75
		return nilField(key)
76
	}
77
	return Bool(key, *val)
78
}
79

80
// ByteString constructs a field that carries UTF-8 encoded text as a []byte.
81
// To log opaque binary blobs (which aren't necessarily valid UTF-8), use
82
// Binary.
83
func ByteString(key string, val []byte) Field {
84
	return Field{Key: key, Type: zapcore.ByteStringType, Interface: val}
85
}
86

87
// Complex128 constructs a field that carries a complex number. Unlike most
88
// numeric fields, this costs an allocation (to convert the complex128 to
89
// interface{}).
90
func Complex128(key string, val complex128) Field {
91
	return Field{Key: key, Type: zapcore.Complex128Type, Interface: val}
92
}
93

94
// Complex128p constructs a field that carries a *complex128. The returned Field will safely
95
// and explicitly represent `nil` when appropriate.
96
func Complex128p(key string, val *complex128) Field {
97
	if val == nil {
98
		return nilField(key)
99
	}
100
	return Complex128(key, *val)
101
}
102

103
// Complex64 constructs a field that carries a complex number. Unlike most
104
// numeric fields, this costs an allocation (to convert the complex64 to
105
// interface{}).
106
func Complex64(key string, val complex64) Field {
107
	return Field{Key: key, Type: zapcore.Complex64Type, Interface: val}
108
}
109

110
// Complex64p constructs a field that carries a *complex64. The returned Field will safely
111
// and explicitly represent `nil` when appropriate.
112
func Complex64p(key string, val *complex64) Field {
113
	if val == nil {
114
		return nilField(key)
115
	}
116
	return Complex64(key, *val)
117
}
118

119
// Float64 constructs a field that carries a float64. The way the
120
// floating-point value is represented is encoder-dependent, so marshaling is
121
// necessarily lazy.
122
func Float64(key string, val float64) Field {
123
	return Field{Key: key, Type: zapcore.Float64Type, Integer: int64(math.Float64bits(val))}
124
}
125

126
// Float64p constructs a field that carries a *float64. The returned Field will safely
127
// and explicitly represent `nil` when appropriate.
128
func Float64p(key string, val *float64) Field {
129
	if val == nil {
130
		return nilField(key)
131
	}
132
	return Float64(key, *val)
133
}
134

135
// Float32 constructs a field that carries a float32. The way the
136
// floating-point value is represented is encoder-dependent, so marshaling is
137
// necessarily lazy.
138
func Float32(key string, val float32) Field {
139
	return Field{Key: key, Type: zapcore.Float32Type, Integer: int64(math.Float32bits(val))}
140
}
141

142
// Float32p constructs a field that carries a *float32. The returned Field will safely
143
// and explicitly represent `nil` when appropriate.
144
func Float32p(key string, val *float32) Field {
145
	if val == nil {
146
		return nilField(key)
147
	}
148
	return Float32(key, *val)
149
}
150

151
// Int constructs a field with the given key and value.
152
func Int(key string, val int) Field {
153
	return Int64(key, int64(val))
154
}
155

156
// Intp constructs a field that carries a *int. The returned Field will safely
157
// and explicitly represent `nil` when appropriate.
158
func Intp(key string, val *int) Field {
159
	if val == nil {
160
		return nilField(key)
161
	}
162
	return Int(key, *val)
163
}
164

165
// Int64 constructs a field with the given key and value.
166
func Int64(key string, val int64) Field {
167
	return Field{Key: key, Type: zapcore.Int64Type, Integer: val}
168
}
169

170
// Int64p constructs a field that carries a *int64. The returned Field will safely
171
// and explicitly represent `nil` when appropriate.
172
func Int64p(key string, val *int64) Field {
173
	if val == nil {
174
		return nilField(key)
175
	}
176
	return Int64(key, *val)
177
}
178

179
// Int32 constructs a field with the given key and value.
180
func Int32(key string, val int32) Field {
181
	return Field{Key: key, Type: zapcore.Int32Type, Integer: int64(val)}
182
}
183

184
// Int32p constructs a field that carries a *int32. The returned Field will safely
185
// and explicitly represent `nil` when appropriate.
186
func Int32p(key string, val *int32) Field {
187
	if val == nil {
188
		return nilField(key)
189
	}
190
	return Int32(key, *val)
191
}
192

193
// Int16 constructs a field with the given key and value.
194
func Int16(key string, val int16) Field {
195
	return Field{Key: key, Type: zapcore.Int16Type, Integer: int64(val)}
196
}
197

198
// Int16p constructs a field that carries a *int16. The returned Field will safely
199
// and explicitly represent `nil` when appropriate.
200
func Int16p(key string, val *int16) Field {
201
	if val == nil {
202
		return nilField(key)
203
	}
204
	return Int16(key, *val)
205
}
206

207
// Int8 constructs a field with the given key and value.
208
func Int8(key string, val int8) Field {
209
	return Field{Key: key, Type: zapcore.Int8Type, Integer: int64(val)}
210
}
211

212
// Int8p constructs a field that carries a *int8. The returned Field will safely
213
// and explicitly represent `nil` when appropriate.
214
func Int8p(key string, val *int8) Field {
215
	if val == nil {
216
		return nilField(key)
217
	}
218
	return Int8(key, *val)
219
}
220

221
// String constructs a field with the given key and value.
222
func String(key string, val string) Field {
223
	return Field{Key: key, Type: zapcore.StringType, String: val}
224
}
225

226
// Stringp constructs a field that carries a *string. The returned Field will safely
227
// and explicitly represent `nil` when appropriate.
228
func Stringp(key string, val *string) Field {
229
	if val == nil {
230
		return nilField(key)
231
	}
232
	return String(key, *val)
233
}
234

235
// Uint constructs a field with the given key and value.
236
func Uint(key string, val uint) Field {
237
	return Uint64(key, uint64(val))
238
}
239

240
// Uintp constructs a field that carries a *uint. The returned Field will safely
241
// and explicitly represent `nil` when appropriate.
242
func Uintp(key string, val *uint) Field {
243
	if val == nil {
244
		return nilField(key)
245
	}
246
	return Uint(key, *val)
247
}
248

249
// Uint64 constructs a field with the given key and value.
250
func Uint64(key string, val uint64) Field {
251
	return Field{Key: key, Type: zapcore.Uint64Type, Integer: int64(val)}
252
}
253

254
// Uint64p constructs a field that carries a *uint64. The returned Field will safely
255
// and explicitly represent `nil` when appropriate.
256
func Uint64p(key string, val *uint64) Field {
257
	if val == nil {
258
		return nilField(key)
259
	}
260
	return Uint64(key, *val)
261
}
262

263
// Uint32 constructs a field with the given key and value.
264
func Uint32(key string, val uint32) Field {
265
	return Field{Key: key, Type: zapcore.Uint32Type, Integer: int64(val)}
266
}
267

268
// Uint32p constructs a field that carries a *uint32. The returned Field will safely
269
// and explicitly represent `nil` when appropriate.
270
func Uint32p(key string, val *uint32) Field {
271
	if val == nil {
272
		return nilField(key)
273
	}
274
	return Uint32(key, *val)
275
}
276

277
// Uint16 constructs a field with the given key and value.
278
func Uint16(key string, val uint16) Field {
279
	return Field{Key: key, Type: zapcore.Uint16Type, Integer: int64(val)}
280
}
281

282
// Uint16p constructs a field that carries a *uint16. The returned Field will safely
283
// and explicitly represent `nil` when appropriate.
284
func Uint16p(key string, val *uint16) Field {
285
	if val == nil {
286
		return nilField(key)
287
	}
288
	return Uint16(key, *val)
289
}
290

291
// Uint8 constructs a field with the given key and value.
292
func Uint8(key string, val uint8) Field {
293
	return Field{Key: key, Type: zapcore.Uint8Type, Integer: int64(val)}
294
}
295

296
// Uint8p constructs a field that carries a *uint8. The returned Field will safely
297
// and explicitly represent `nil` when appropriate.
298
func Uint8p(key string, val *uint8) Field {
299
	if val == nil {
300
		return nilField(key)
301
	}
302
	return Uint8(key, *val)
303
}
304

305
// Uintptr constructs a field with the given key and value.
306
func Uintptr(key string, val uintptr) Field {
307
	return Field{Key: key, Type: zapcore.UintptrType, Integer: int64(val)}
308
}
309

310
// Uintptrp constructs a field that carries a *uintptr. The returned Field will safely
311
// and explicitly represent `nil` when appropriate.
312
func Uintptrp(key string, val *uintptr) Field {
313
	if val == nil {
314
		return nilField(key)
315
	}
316
	return Uintptr(key, *val)
317
}
318

319
// Reflect constructs a field with the given key and an arbitrary object. It uses
320
// an encoding-appropriate, reflection-based function to lazily serialize nearly
321
// any object into the logging context, but it's relatively slow and
322
// allocation-heavy. Outside tests, Any is always a better choice.
323
//
324
// If encoding fails (e.g., trying to serialize a map[int]string to JSON), Reflect
325
// includes the error message in the final log output.
326
func Reflect(key string, val interface{}) Field {
327
	return Field{Key: key, Type: zapcore.ReflectType, Interface: val}
328
}
329

330
// Namespace creates a named, isolated scope within the logger's context. All
331
// subsequent fields will be added to the new namespace.
332
//
333
// This helps prevent key collisions when injecting loggers into sub-components
334
// or third-party libraries.
335
func Namespace(key string) Field {
336
	return Field{Key: key, Type: zapcore.NamespaceType}
337
}
338

339
// Stringer constructs a field with the given key and the output of the value's
340
// String method. The Stringer's String method is called lazily.
341
func Stringer(key string, val fmt.Stringer) Field {
342
	return Field{Key: key, Type: zapcore.StringerType, Interface: val}
343
}
344

345
// Time constructs a Field with the given key and value. The encoder
346
// controls how the time is serialized.
347
func Time(key string, val time.Time) Field {
348
	if val.Before(_minTimeInt64) || val.After(_maxTimeInt64) {
349
		return Field{Key: key, Type: zapcore.TimeFullType, Interface: val}
350
	}
351
	return Field{Key: key, Type: zapcore.TimeType, Integer: val.UnixNano(), Interface: val.Location()}
352
}
353

354
// Timep constructs a field that carries a *time.Time. The returned Field will safely
355
// and explicitly represent `nil` when appropriate.
356
func Timep(key string, val *time.Time) Field {
357
	if val == nil {
358
		return nilField(key)
359
	}
360
	return Time(key, *val)
361
}
362

363
// Stack constructs a field that stores a stacktrace of the current goroutine
364
// under provided key. Keep in mind that taking a stacktrace is eager and
365
// expensive (relatively speaking); this function both makes an allocation and
366
// takes about two microseconds.
367
func Stack(key string) Field {
368
	return StackSkip(key, 1) // skip Stack
369
}
370

371
// StackSkip constructs a field similarly to Stack, but also skips the given
372
// number of frames from the top of the stacktrace.
373
func StackSkip(key string, skip int) Field {
374
	// Returning the stacktrace as a string costs an allocation, but saves us
375
	// from expanding the zapcore.Field union struct to include a byte slice. Since
376
	// taking a stacktrace is already so expensive (~10us), the extra allocation
377
	// is okay.
378
	return String(key, stacktrace.Take(skip+1)) // skip StackSkip
379
}
380

381
// Duration constructs a field with the given key and value. The encoder
382
// controls how the duration is serialized.
383
func Duration(key string, val time.Duration) Field {
384
	return Field{Key: key, Type: zapcore.DurationType, Integer: int64(val)}
385
}
386

387
// Durationp constructs a field that carries a *time.Duration. The returned Field will safely
388
// and explicitly represent `nil` when appropriate.
389
func Durationp(key string, val *time.Duration) Field {
390
	if val == nil {
391
		return nilField(key)
392
	}
393
	return Duration(key, *val)
394
}
395

396
// Object constructs a field with the given key and ObjectMarshaler. It
397
// provides a flexible, but still type-safe and efficient, way to add map- or
398
// struct-like user-defined types to the logging context. The struct's
399
// MarshalLogObject method is called lazily.
400
func Object(key string, val zapcore.ObjectMarshaler) Field {
401
	return Field{Key: key, Type: zapcore.ObjectMarshalerType, Interface: val}
402
}
403

404
// Inline constructs a Field that is similar to Object, but it
405
// will add the elements of the provided ObjectMarshaler to the
406
// current namespace.
407
func Inline(val zapcore.ObjectMarshaler) Field {
408
	return zapcore.Field{
409
		Type:      zapcore.InlineMarshalerType,
410
		Interface: val,
411
	}
412
}
413

414
// Dict constructs a field containing the provided key-value pairs.
415
// It acts similar to [Object], but with the fields specified as arguments.
416
func Dict(key string, val ...Field) Field {
417
	return dictField(key, val)
418
}
419

420
// We need a function with the signature (string, T) for zap.Any.
421
func dictField(key string, val []Field) Field {
422
	return Object(key, dictObject(val))
423
}
424

425
type dictObject []Field
426

427
func (d dictObject) MarshalLogObject(enc zapcore.ObjectEncoder) error {
428
	for _, f := range d {
429
		f.AddTo(enc)
430
	}
431
	return nil
432
}
433

434
// We discovered an issue where zap.Any can cause a performance degradation
435
// when used in new goroutines.
436
//
437
// This happens because the compiler assigns 4.8kb (one zap.Field per arm of
438
// switch statement) of stack space for zap.Any when it takes the form:
439
//
440
//	switch v := v.(type) {
441
//	case string:
442
//		return String(key, v)
443
//	case int:
444
//		return Int(key, v)
445
//		// ...
446
//	default:
447
//		return Reflect(key, v)
448
//	}
449
//
450
// To avoid this, we use the type switch to assign a value to a single local variable
451
// and then call a function on it.
452
// The local variable is just a function reference so it doesn't allocate
453
// when converted to an interface{}.
454
//
455
// A fair bit of experimentation went into this.
456
// See also:
457
//
458
// - https://github.com/uber-go/zap/pull/1301
459
// - https://github.com/uber-go/zap/pull/1303
460
// - https://github.com/uber-go/zap/pull/1304
461
// - https://github.com/uber-go/zap/pull/1305
462
// - https://github.com/uber-go/zap/pull/1308
463
//
464
// See https://github.com/golang/go/issues/62077 for upstream issue.
465
type anyFieldC[T any] func(string, T) Field
466

467
func (f anyFieldC[T]) Any(key string, val any) Field {
468
	v, _ := val.(T)
469
	// val is guaranteed to be a T, except when it's nil.
470
	return f(key, v)
471
}
472

473
// Any takes a key and an arbitrary value and chooses the best way to represent
474
// them as a field, falling back to a reflection-based approach only if
475
// necessary.
476
//
477
// Since byte/uint8 and rune/int32 are aliases, Any can't differentiate between
478
// them. To minimize surprises, []byte values are treated as binary blobs, byte
479
// values are treated as uint8, and runes are always treated as integers.
480
func Any(key string, value interface{}) Field {
481
	var c interface{ Any(string, any) Field }
482

483
	switch value.(type) {
484
	case zapcore.ObjectMarshaler:
485
		c = anyFieldC[zapcore.ObjectMarshaler](Object)
486
	case zapcore.ArrayMarshaler:
487
		c = anyFieldC[zapcore.ArrayMarshaler](Array)
488
	case []Field:
489
		c = anyFieldC[[]Field](dictField)
490
	case bool:
491
		c = anyFieldC[bool](Bool)
492
	case *bool:
493
		c = anyFieldC[*bool](Boolp)
494
	case []bool:
495
		c = anyFieldC[[]bool](Bools)
496
	case complex128:
497
		c = anyFieldC[complex128](Complex128)
498
	case *complex128:
499
		c = anyFieldC[*complex128](Complex128p)
500
	case []complex128:
501
		c = anyFieldC[[]complex128](Complex128s)
502
	case complex64:
503
		c = anyFieldC[complex64](Complex64)
504
	case *complex64:
505
		c = anyFieldC[*complex64](Complex64p)
506
	case []complex64:
507
		c = anyFieldC[[]complex64](Complex64s)
508
	case float64:
509
		c = anyFieldC[float64](Float64)
510
	case *float64:
511
		c = anyFieldC[*float64](Float64p)
512
	case []float64:
513
		c = anyFieldC[[]float64](Float64s)
514
	case float32:
515
		c = anyFieldC[float32](Float32)
516
	case *float32:
517
		c = anyFieldC[*float32](Float32p)
518
	case []float32:
519
		c = anyFieldC[[]float32](Float32s)
520
	case int:
521
		c = anyFieldC[int](Int)
522
	case *int:
523
		c = anyFieldC[*int](Intp)
524
	case []int:
525
		c = anyFieldC[[]int](Ints)
526
	case int64:
527
		c = anyFieldC[int64](Int64)
528
	case *int64:
529
		c = anyFieldC[*int64](Int64p)
530
	case []int64:
531
		c = anyFieldC[[]int64](Int64s)
532
	case int32:
533
		c = anyFieldC[int32](Int32)
534
	case *int32:
535
		c = anyFieldC[*int32](Int32p)
536
	case []int32:
537
		c = anyFieldC[[]int32](Int32s)
538
	case int16:
539
		c = anyFieldC[int16](Int16)
540
	case *int16:
541
		c = anyFieldC[*int16](Int16p)
542
	case []int16:
543
		c = anyFieldC[[]int16](Int16s)
544
	case int8:
545
		c = anyFieldC[int8](Int8)
546
	case *int8:
547
		c = anyFieldC[*int8](Int8p)
548
	case []int8:
549
		c = anyFieldC[[]int8](Int8s)
550
	case string:
551
		c = anyFieldC[string](String)
552
	case *string:
553
		c = anyFieldC[*string](Stringp)
554
	case []string:
555
		c = anyFieldC[[]string](Strings)
556
	case uint:
557
		c = anyFieldC[uint](Uint)
558
	case *uint:
559
		c = anyFieldC[*uint](Uintp)
560
	case []uint:
561
		c = anyFieldC[[]uint](Uints)
562
	case uint64:
563
		c = anyFieldC[uint64](Uint64)
564
	case *uint64:
565
		c = anyFieldC[*uint64](Uint64p)
566
	case []uint64:
567
		c = anyFieldC[[]uint64](Uint64s)
568
	case uint32:
569
		c = anyFieldC[uint32](Uint32)
570
	case *uint32:
571
		c = anyFieldC[*uint32](Uint32p)
572
	case []uint32:
573
		c = anyFieldC[[]uint32](Uint32s)
574
	case uint16:
575
		c = anyFieldC[uint16](Uint16)
576
	case *uint16:
577
		c = anyFieldC[*uint16](Uint16p)
578
	case []uint16:
579
		c = anyFieldC[[]uint16](Uint16s)
580
	case uint8:
581
		c = anyFieldC[uint8](Uint8)
582
	case *uint8:
583
		c = anyFieldC[*uint8](Uint8p)
584
	case []byte:
585
		c = anyFieldC[[]byte](Binary)
586
	case uintptr:
587
		c = anyFieldC[uintptr](Uintptr)
588
	case *uintptr:
589
		c = anyFieldC[*uintptr](Uintptrp)
590
	case []uintptr:
591
		c = anyFieldC[[]uintptr](Uintptrs)
592
	case time.Time:
593
		c = anyFieldC[time.Time](Time)
594
	case *time.Time:
595
		c = anyFieldC[*time.Time](Timep)
596
	case []time.Time:
597
		c = anyFieldC[[]time.Time](Times)
598
	case time.Duration:
599
		c = anyFieldC[time.Duration](Duration)
600
	case *time.Duration:
601
		c = anyFieldC[*time.Duration](Durationp)
602
	case []time.Duration:
603
		c = anyFieldC[[]time.Duration](Durations)
604
	case error:
605
		c = anyFieldC[error](NamedError)
606
	case []error:
607
		c = anyFieldC[[]error](Errors)
608
	case fmt.Stringer:
609
		c = anyFieldC[fmt.Stringer](Stringer)
610
	default:
611
		c = anyFieldC[any](Reflect)
612
	}
613

614
	return c.Any(key, value)
615
}
616

617