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

27
	"go.uber.org/zap/zapcore"
28
)
29

30
// Array constructs a field with the given key and ArrayMarshaler. It provides
31
// a flexible, but still type-safe and efficient, way to add array-like types
32
// to the logging context. The struct's MarshalLogArray method is called lazily.
33
func Array(key string, val zapcore.ArrayMarshaler) Field {
34
	return Field{Key: key, Type: zapcore.ArrayMarshalerType, Interface: val}
35
}
36

37
// Bools constructs a field that carries a slice of bools.
38
func Bools(key string, bs []bool) Field {
39
	return Array(key, bools(bs))
40
}
41

42
// ByteStrings constructs a field that carries a slice of []byte, each of which
43
// must be UTF-8 encoded text.
44
func ByteStrings(key string, bss [][]byte) Field {
45
	return Array(key, byteStringsArray(bss))
46
}
47

48
// Complex128s constructs a field that carries a slice of complex numbers.
49
func Complex128s(key string, nums []complex128) Field {
50
	return Array(key, complex128s(nums))
51
}
52

53
// Complex64s constructs a field that carries a slice of complex numbers.
54
func Complex64s(key string, nums []complex64) Field {
55
	return Array(key, complex64s(nums))
56
}
57

58
// Durations constructs a field that carries a slice of time.Durations.
59
func Durations(key string, ds []time.Duration) Field {
60
	return Array(key, durations(ds))
61
}
62

63
// Float64s constructs a field that carries a slice of floats.
64
func Float64s(key string, nums []float64) Field {
65
	return Array(key, float64s(nums))
66
}
67

68
// Float32s constructs a field that carries a slice of floats.
69
func Float32s(key string, nums []float32) Field {
70
	return Array(key, float32s(nums))
71
}
72

73
// Ints constructs a field that carries a slice of integers.
74
func Ints(key string, nums []int) Field {
75
	return Array(key, ints(nums))
76
}
77

78
// Int64s constructs a field that carries a slice of integers.
79
func Int64s(key string, nums []int64) Field {
80
	return Array(key, int64s(nums))
81
}
82

83
// Int32s constructs a field that carries a slice of integers.
84
func Int32s(key string, nums []int32) Field {
85
	return Array(key, int32s(nums))
86
}
87

88
// Int16s constructs a field that carries a slice of integers.
89
func Int16s(key string, nums []int16) Field {
90
	return Array(key, int16s(nums))
91
}
92

93
// Int8s constructs a field that carries a slice of integers.
94
func Int8s(key string, nums []int8) Field {
95
	return Array(key, int8s(nums))
96
}
97

98
// Objects constructs a field with the given key, holding a list of the
99
// provided objects that can be marshaled by Zap.
100
//
101
// Note that these objects must implement zapcore.ObjectMarshaler directly.
102
// That is, if you're trying to marshal a []Request, the MarshalLogObject
103
// method must be declared on the Request type, not its pointer (*Request).
104
// If it's on the pointer, use ObjectValues.
105
//
106
// Given an object that implements MarshalLogObject on the value receiver, you
107
// can log a slice of those objects with Objects like so:
108
//
109
//	type Author struct{ ... }
110
//	func (a Author) MarshalLogObject(enc zapcore.ObjectEncoder) error
111
//
112
//	var authors []Author = ...
113
//	logger.Info("loading article", zap.Objects("authors", authors))
114
//
115
// Similarly, given a type that implements MarshalLogObject on its pointer
116
// receiver, you can log a slice of pointers to that object with Objects like
117
// so:
118
//
119
//	type Request struct{ ... }
120
//	func (r *Request) MarshalLogObject(enc zapcore.ObjectEncoder) error
121
//
122
//	var requests []*Request = ...
123
//	logger.Info("sending requests", zap.Objects("requests", requests))
124
//
125
// If instead, you have a slice of values of such an object, use the
126
// ObjectValues constructor.
127
//
128
//	var requests []Request = ...
129
//	logger.Info("sending requests", zap.ObjectValues("requests", requests))
130
func Objects[T zapcore.ObjectMarshaler](key string, values []T) Field {
131
	return Array(key, objects[T](values))
132
}
133

134
type objects[T zapcore.ObjectMarshaler] []T
135

136
func (os objects[T]) MarshalLogArray(arr zapcore.ArrayEncoder) error {
137
	for _, o := range os {
138
		if err := arr.AppendObject(o); err != nil {
139
			return err
140
		}
141
	}
142
	return nil
143
}
144

145
// ObjectMarshalerPtr is a constraint that specifies that the given type
146
// implements zapcore.ObjectMarshaler on a pointer receiver.
147
type ObjectMarshalerPtr[T any] interface {
148
	*T
149
	zapcore.ObjectMarshaler
150
}
151

152
// ObjectValues constructs a field with the given key, holding a list of the
153
// provided objects, where pointers to these objects can be marshaled by Zap.
154
//
155
// Note that pointers to these objects must implement zapcore.ObjectMarshaler.
156
// That is, if you're trying to marshal a []Request, the MarshalLogObject
157
// method must be declared on the *Request type, not the value (Request).
158
// If it's on the value, use Objects.
159
//
160
// Given an object that implements MarshalLogObject on the pointer receiver,
161
// you can log a slice of those objects with ObjectValues like so:
162
//
163
//	type Request struct{ ... }
164
//	func (r *Request) MarshalLogObject(enc zapcore.ObjectEncoder) error
165
//
166
//	var requests []Request = ...
167
//	logger.Info("sending requests", zap.ObjectValues("requests", requests))
168
//
169
// If instead, you have a slice of pointers of such an object, use the Objects
170
// field constructor.
171
//
172
//	var requests []*Request = ...
173
//	logger.Info("sending requests", zap.Objects("requests", requests))
174
func ObjectValues[T any, P ObjectMarshalerPtr[T]](key string, values []T) Field {
175
	return Array(key, objectValues[T, P](values))
176
}
177

178
type objectValues[T any, P ObjectMarshalerPtr[T]] []T
179

180
func (os objectValues[T, P]) MarshalLogArray(arr zapcore.ArrayEncoder) error {
181
	for i := range os {
182
		// It is necessary for us to explicitly reference the "P" type.
183
		// We cannot simply pass "&os[i]" to AppendObject because its type
184
		// is "*T", which the type system does not consider as
185
		// implementing ObjectMarshaler.
186
		// Only the type "P" satisfies ObjectMarshaler, which we have
187
		// to convert "*T" to explicitly.
188
		var p P = &os[i]
189
		if err := arr.AppendObject(p); err != nil {
190
			return err
191
		}
192
	}
193
	return nil
194
}
195

196
// Strings constructs a field that carries a slice of strings.
197
func Strings(key string, ss []string) Field {
198
	return Array(key, stringArray(ss))
199
}
200

201
// Stringers constructs a field with the given key, holding a list of the
202
// output provided by the value's String method
203
//
204
// Given an object that implements String on the value receiver, you
205
// can log a slice of those objects with Objects like so:
206
//
207
//	type Request struct{ ... }
208
//	func (a Request) String() string
209
//
210
//	var requests []Request = ...
211
//	logger.Info("sending requests", zap.Stringers("requests", requests))
212
//
213
// Note that these objects must implement fmt.Stringer directly.
214
// That is, if you're trying to marshal a []Request, the String method
215
// must be declared on the Request type, not its pointer (*Request).
216
func Stringers[T fmt.Stringer](key string, values []T) Field {
217
	return Array(key, stringers[T](values))
218
}
219

220
type stringers[T fmt.Stringer] []T
221

222
func (os stringers[T]) MarshalLogArray(arr zapcore.ArrayEncoder) error {
223
	for _, o := range os {
224
		arr.AppendString(o.String())
225
	}
226
	return nil
227
}
228

229
// Times constructs a field that carries a slice of time.Times.
230
func Times(key string, ts []time.Time) Field {
231
	return Array(key, times(ts))
232
}
233

234
// Uints constructs a field that carries a slice of unsigned integers.
235
func Uints(key string, nums []uint) Field {
236
	return Array(key, uints(nums))
237
}
238

239
// Uint64s constructs a field that carries a slice of unsigned integers.
240
func Uint64s(key string, nums []uint64) Field {
241
	return Array(key, uint64s(nums))
242
}
243

244
// Uint32s constructs a field that carries a slice of unsigned integers.
245
func Uint32s(key string, nums []uint32) Field {
246
	return Array(key, uint32s(nums))
247
}
248

249
// Uint16s constructs a field that carries a slice of unsigned integers.
250
func Uint16s(key string, nums []uint16) Field {
251
	return Array(key, uint16s(nums))
252
}
253

254
// Uint8s constructs a field that carries a slice of unsigned integers.
255
func Uint8s(key string, nums []uint8) Field {
256
	return Array(key, uint8s(nums))
257
}
258

259
// Uintptrs constructs a field that carries a slice of pointer addresses.
260
func Uintptrs(key string, us []uintptr) Field {
261
	return Array(key, uintptrs(us))
262
}
263

264
// Errors constructs a field that carries a slice of errors.
265
func Errors(key string, errs []error) Field {
266
	return Array(key, errArray(errs))
267
}
268

269
type bools []bool
270

271
func (bs bools) MarshalLogArray(arr zapcore.ArrayEncoder) error {
272
	for i := range bs {
273
		arr.AppendBool(bs[i])
274
	}
275
	return nil
276
}
277

278
type byteStringsArray [][]byte
279

280
func (bss byteStringsArray) MarshalLogArray(arr zapcore.ArrayEncoder) error {
281
	for i := range bss {
282
		arr.AppendByteString(bss[i])
283
	}
284
	return nil
285
}
286

287
type complex128s []complex128
288

289
func (nums complex128s) MarshalLogArray(arr zapcore.ArrayEncoder) error {
290
	for i := range nums {
291
		arr.AppendComplex128(nums[i])
292
	}
293
	return nil
294
}
295

296
type complex64s []complex64
297

298
func (nums complex64s) MarshalLogArray(arr zapcore.ArrayEncoder) error {
299
	for i := range nums {
300
		arr.AppendComplex64(nums[i])
301
	}
302
	return nil
303
}
304

305
type durations []time.Duration
306

307
func (ds durations) MarshalLogArray(arr zapcore.ArrayEncoder) error {
308
	for i := range ds {
309
		arr.AppendDuration(ds[i])
310
	}
311
	return nil
312
}
313

314
type float64s []float64
315

316
func (nums float64s) MarshalLogArray(arr zapcore.ArrayEncoder) error {
317
	for i := range nums {
318
		arr.AppendFloat64(nums[i])
319
	}
320
	return nil
321
}
322

323
type float32s []float32
324

325
func (nums float32s) MarshalLogArray(arr zapcore.ArrayEncoder) error {
326
	for i := range nums {
327
		arr.AppendFloat32(nums[i])
328
	}
329
	return nil
330
}
331

332
type ints []int
333

334
func (nums ints) MarshalLogArray(arr zapcore.ArrayEncoder) error {
335
	for i := range nums {
336
		arr.AppendInt(nums[i])
337
	}
338
	return nil
339
}
340

341
type int64s []int64
342

343
func (nums int64s) MarshalLogArray(arr zapcore.ArrayEncoder) error {
344
	for i := range nums {
345
		arr.AppendInt64(nums[i])
346
	}
347
	return nil
348
}
349

350
type int32s []int32
351

352
func (nums int32s) MarshalLogArray(arr zapcore.ArrayEncoder) error {
353
	for i := range nums {
354
		arr.AppendInt32(nums[i])
355
	}
356
	return nil
357
}
358

359
type int16s []int16
360

361
func (nums int16s) MarshalLogArray(arr zapcore.ArrayEncoder) error {
362
	for i := range nums {
363
		arr.AppendInt16(nums[i])
364
	}
365
	return nil
366
}
367

368
type int8s []int8
369

370
func (nums int8s) MarshalLogArray(arr zapcore.ArrayEncoder) error {
371
	for i := range nums {
372
		arr.AppendInt8(nums[i])
373
	}
374
	return nil
375
}
376

377
type stringArray []string
378

379
func (ss stringArray) MarshalLogArray(arr zapcore.ArrayEncoder) error {
380
	for i := range ss {
381
		arr.AppendString(ss[i])
382
	}
383
	return nil
384
}
385

386
type times []time.Time
387

388
func (ts times) MarshalLogArray(arr zapcore.ArrayEncoder) error {
389
	for i := range ts {
390
		arr.AppendTime(ts[i])
391
	}
392
	return nil
393
}
394

395
type uints []uint
396

397
func (nums uints) MarshalLogArray(arr zapcore.ArrayEncoder) error {
398
	for i := range nums {
399
		arr.AppendUint(nums[i])
400
	}
401
	return nil
402
}
403

404
type uint64s []uint64
405

406
func (nums uint64s) MarshalLogArray(arr zapcore.ArrayEncoder) error {
407
	for i := range nums {
408
		arr.AppendUint64(nums[i])
409
	}
410
	return nil
411
}
412

413
type uint32s []uint32
414

415
func (nums uint32s) MarshalLogArray(arr zapcore.ArrayEncoder) error {
416
	for i := range nums {
417
		arr.AppendUint32(nums[i])
418
	}
419
	return nil
420
}
421

422
type uint16s []uint16
423

424
func (nums uint16s) MarshalLogArray(arr zapcore.ArrayEncoder) error {
425
	for i := range nums {
426
		arr.AppendUint16(nums[i])
427
	}
428
	return nil
429
}
430

431
type uint8s []uint8
432

433
func (nums uint8s) MarshalLogArray(arr zapcore.ArrayEncoder) error {
434
	for i := range nums {
435
		arr.AppendUint8(nums[i])
436
	}
437
	return nil
438
}
439

440
type uintptrs []uintptr
441

442
func (nums uintptrs) MarshalLogArray(arr zapcore.ArrayEncoder) error {
443
	for i := range nums {
444
		arr.AppendUintptr(nums[i])
445
	}
446
	return nil
447
}
448

449