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 35// Skip constructs a no-op field, which is often useful when handling invalid 36// inputs in other Field constructors. 37func Skip() Field { 38 return Field{Type: zapcore.SkipType} 39} 40 41// nilField returns a field which will marshal explicitly as nil. See motivation 42// in https://github.com/uber-go/zap/issues/753 . If we ever make breaking 43// changes and add zapcore.NilType and zapcore.ObjectEncoder.AddNil, the 44// implementation here should be changed to reflect that. 45func nilField(key string) Field { return Reflect(key, nil) } 46 47// Binary constructs a field that carries an opaque binary blob. 48// 49// Binary data is serialized in an encoding-appropriate format. For example, 50// zap's JSON encoder base64-encodes binary blobs. To log UTF-8 encoded text, 51// use ByteString. 52func Binary(key string, val []byte) Field { 53 return Field{Key: key, Type: zapcore.BinaryType, Interface: val} 54} 55 56// Bool constructs a field that carries a bool. 57func Bool(key string, val bool) Field { 58 var ival int64 59 if val { 60 ival = 1 61 } 62 return Field{Key: key, Type: zapcore.BoolType, Integer: ival} 63} 64 65// Boolp constructs a field that carries a *bool. The returned Field will safely 66// and explicitly represent `nil` when appropriate. 67func Boolp(key string, val *bool) Field { 68 if val == nil { 69 return nilField(key) 70 } 71 return Bool(key, *val) 72} 73 74// ByteString constructs a field that carries UTF-8 encoded text as a []byte. 75// To log opaque binary blobs (which aren't necessarily valid UTF-8), use 76// Binary. 77func ByteString(key string, val []byte) Field { 78 return Field{Key: key, Type: zapcore.ByteStringType, Interface: val} 79} 80 81// Complex128 constructs a field that carries a complex number. Unlike most 82// numeric fields, this costs an allocation (to convert the complex128 to 83// interface{}). 84func Complex128(key string, val complex128) Field { 85 return Field{Key: key, Type: zapcore.Complex128Type, Interface: val} 86} 87 88// Complex128p constructs a field that carries a *complex128. The returned Field will safely 89// and explicitly represent `nil` when appropriate. 90func Complex128p(key string, val *complex128) Field { 91 if val == nil { 92 return nilField(key) 93 } 94 return Complex128(key, *val) 95} 96 97// Complex64 constructs a field that carries a complex number. Unlike most 98// numeric fields, this costs an allocation (to convert the complex64 to 99// interface{}). 100func Complex64(key string, val complex64) Field { 101 return Field{Key: key, Type: zapcore.Complex64Type, Interface: val} 102} 103 104// Complex64p constructs a field that carries a *complex64. The returned Field will safely 105// and explicitly represent `nil` when appropriate. 106func Complex64p(key string, val *complex64) Field { 107 if val == nil { 108 return nilField(key) 109 } 110 return Complex64(key, *val) 111} 112 113// Float64 constructs a field that carries a float64. The way the 114// floating-point value is represented is encoder-dependent, so marshaling is 115// necessarily lazy. 116func Float64(key string, val float64) Field { 117 return Field{Key: key, Type: zapcore.Float64Type, Integer: int64(math.Float64bits(val))} 118} 119 120// Float64p constructs a field that carries a *float64. The returned Field will safely 121// and explicitly represent `nil` when appropriate. 122func Float64p(key string, val *float64) Field { 123 if val == nil { 124 return nilField(key) 125 } 126 return Float64(key, *val) 127} 128 129// Float32 constructs a field that carries a float32. The way the 130// floating-point value is represented is encoder-dependent, so marshaling is 131// necessarily lazy. 132func Float32(key string, val float32) Field { 133 return Field{Key: key, Type: zapcore.Float32Type, Integer: int64(math.Float32bits(val))} 134} 135 136// Float32p constructs a field that carries a *float32. The returned Field will safely 137// and explicitly represent `nil` when appropriate. 138func Float32p(key string, val *float32) Field { 139 if val == nil { 140 return nilField(key) 141 } 142 return Float32(key, *val) 143} 144 145// Int constructs a field with the given key and value. 146func Int(key string, val int) Field { 147 return Int64(key, int64(val)) 148} 149 150// Intp constructs a field that carries a *int. The returned Field will safely 151// and explicitly represent `nil` when appropriate. 152func Intp(key string, val *int) Field { 153 if val == nil { 154 return nilField(key) 155 } 156 return Int(key, *val) 157} 158 159// Int64 constructs a field with the given key and value. 160func Int64(key string, val int64) Field { 161 return Field{Key: key, Type: zapcore.Int64Type, Integer: val} 162} 163 164// Int64p constructs a field that carries a *int64. The returned Field will safely 165// and explicitly represent `nil` when appropriate. 166func Int64p(key string, val *int64) Field { 167 if val == nil { 168 return nilField(key) 169 } 170 return Int64(key, *val) 171} 172 173// Int32 constructs a field with the given key and value. 174func Int32(key string, val int32) Field { 175 return Field{Key: key, Type: zapcore.Int32Type, Integer: int64(val)} 176} 177 178// Int32p constructs a field that carries a *int32. The returned Field will safely 179// and explicitly represent `nil` when appropriate. 180func Int32p(key string, val *int32) Field { 181 if val == nil { 182 return nilField(key) 183 } 184 return Int32(key, *val) 185} 186 187// Int16 constructs a field with the given key and value. 188func Int16(key string, val int16) Field { 189 return Field{Key: key, Type: zapcore.Int16Type, Integer: int64(val)} 190} 191 192// Int16p constructs a field that carries a *int16. The returned Field will safely 193// and explicitly represent `nil` when appropriate. 194func Int16p(key string, val *int16) Field { 195 if val == nil { 196 return nilField(key) 197 } 198 return Int16(key, *val) 199} 200 201// Int8 constructs a field with the given key and value. 202func Int8(key string, val int8) Field { 203 return Field{Key: key, Type: zapcore.Int8Type, Integer: int64(val)} 204} 205 206// Int8p constructs a field that carries a *int8. The returned Field will safely 207// and explicitly represent `nil` when appropriate. 208func Int8p(key string, val *int8) Field { 209 if val == nil { 210 return nilField(key) 211 } 212 return Int8(key, *val) 213} 214 215// String constructs a field with the given key and value. 216func String(key string, val string) Field { 217 return Field{Key: key, Type: zapcore.StringType, String: val} 218} 219 220// Stringp constructs a field that carries a *string. The returned Field will safely 221// and explicitly represent `nil` when appropriate. 222func Stringp(key string, val *string) Field { 223 if val == nil { 224 return nilField(key) 225 } 226 return String(key, *val) 227} 228 229// Uint constructs a field with the given key and value. 230func Uint(key string, val uint) Field { 231 return Uint64(key, uint64(val)) 232} 233 234// Uintp constructs a field that carries a *uint. The returned Field will safely 235// and explicitly represent `nil` when appropriate. 236func Uintp(key string, val *uint) Field { 237 if val == nil { 238 return nilField(key) 239 } 240 return Uint(key, *val) 241} 242 243// Uint64 constructs a field with the given key and value. 244func Uint64(key string, val uint64) Field { 245 return Field{Key: key, Type: zapcore.Uint64Type, Integer: int64(val)} 246} 247 248// Uint64p constructs a field that carries a *uint64. The returned Field will safely 249// and explicitly represent `nil` when appropriate. 250func Uint64p(key string, val *uint64) Field { 251 if val == nil { 252 return nilField(key) 253 } 254 return Uint64(key, *val) 255} 256 257// Uint32 constructs a field with the given key and value. 258func Uint32(key string, val uint32) Field { 259 return Field{Key: key, Type: zapcore.Uint32Type, Integer: int64(val)} 260} 261 262// Uint32p constructs a field that carries a *uint32. The returned Field will safely 263// and explicitly represent `nil` when appropriate. 264func Uint32p(key string, val *uint32) Field { 265 if val == nil { 266 return nilField(key) 267 } 268 return Uint32(key, *val) 269} 270 271// Uint16 constructs a field with the given key and value. 272func Uint16(key string, val uint16) Field { 273 return Field{Key: key, Type: zapcore.Uint16Type, Integer: int64(val)} 274} 275 276// Uint16p constructs a field that carries a *uint16. The returned Field will safely 277// and explicitly represent `nil` when appropriate. 278func Uint16p(key string, val *uint16) Field { 279 if val == nil { 280 return nilField(key) 281 } 282 return Uint16(key, *val) 283} 284 285// Uint8 constructs a field with the given key and value. 286func Uint8(key string, val uint8) Field { 287 return Field{Key: key, Type: zapcore.Uint8Type, Integer: int64(val)} 288} 289 290// Uint8p constructs a field that carries a *uint8. The returned Field will safely 291// and explicitly represent `nil` when appropriate. 292func Uint8p(key string, val *uint8) Field { 293 if val == nil { 294 return nilField(key) 295 } 296 return Uint8(key, *val) 297} 298 299// Uintptr constructs a field with the given key and value. 300func Uintptr(key string, val uintptr) Field { 301 return Field{Key: key, Type: zapcore.UintptrType, Integer: int64(val)} 302} 303 304// Uintptrp constructs a field that carries a *uintptr. The returned Field will safely 305// and explicitly represent `nil` when appropriate. 306func Uintptrp(key string, val *uintptr) Field { 307 if val == nil { 308 return nilField(key) 309 } 310 return Uintptr(key, *val) 311} 312 313// Reflect constructs a field with the given key and an arbitrary object. It uses 314// an encoding-appropriate, reflection-based function to lazily serialize nearly 315// any object into the logging context, but it's relatively slow and 316// allocation-heavy. Outside tests, Any is always a better choice. 317// 318// If encoding fails (e.g., trying to serialize a map[int]string to JSON), Reflect 319// includes the error message in the final log output. 320func Reflect(key string, val interface{}) Field { 321 return Field{Key: key, Type: zapcore.ReflectType, Interface: val} 322} 323 324// Namespace creates a named, isolated scope within the logger's context. All 325// subsequent fields will be added to the new namespace. 326// 327// This helps prevent key collisions when injecting loggers into sub-components 328// or third-party libraries. 329func Namespace(key string) Field { 330 return Field{Key: key, Type: zapcore.NamespaceType} 331} 332 333// Stringer constructs a field with the given key and the output of the value's 334// String method. The Stringer's String method is called lazily. 335func Stringer(key string, val fmt.Stringer) Field { 336 return Field{Key: key, Type: zapcore.StringerType, Interface: val} 337} 338 339// Time constructs a Field with the given key and value. The encoder 340// controls how the time is serialized. 341func Time(key string, val time.Time) Field { 342 return Field{Key: key, Type: zapcore.TimeType, Integer: val.UnixNano(), Interface: val.Location()} 343} 344 345// Timep constructs a field that carries a *time.Time. The returned Field will safely 346// and explicitly represent `nil` when appropriate. 347func Timep(key string, val *time.Time) Field { 348 if val == nil { 349 return nilField(key) 350 } 351 return Time(key, *val) 352} 353 354// Stack constructs a field that stores a stacktrace of the current goroutine 355// under provided key. Keep in mind that taking a stacktrace is eager and 356// expensive (relatively speaking); this function both makes an allocation and 357// takes about two microseconds. 358func Stack(key string) Field { 359 // Returning the stacktrace as a string costs an allocation, but saves us 360 // from expanding the zapcore.Field union struct to include a byte slice. Since 361 // taking a stacktrace is already so expensive (~10us), the extra allocation 362 // is okay. 363 return String(key, takeStacktrace()) 364} 365 366// Duration constructs a field with the given key and value. The encoder 367// controls how the duration is serialized. 368func Duration(key string, val time.Duration) Field { 369 return Field{Key: key, Type: zapcore.DurationType, Integer: int64(val)} 370} 371 372// Durationp constructs a field that carries a *time.Duration. The returned Field will safely 373// and explicitly represent `nil` when appropriate. 374func Durationp(key string, val *time.Duration) Field { 375 if val == nil { 376 return nilField(key) 377 } 378 return Duration(key, *val) 379} 380 381// Object constructs a field with the given key and ObjectMarshaler. It 382// provides a flexible, but still type-safe and efficient, way to add map- or 383// struct-like user-defined types to the logging context. The struct's 384// MarshalLogObject method is called lazily. 385func Object(key string, val zapcore.ObjectMarshaler) Field { 386 return Field{Key: key, Type: zapcore.ObjectMarshalerType, Interface: val} 387} 388 389// Any takes a key and an arbitrary value and chooses the best way to represent 390// them as a field, falling back to a reflection-based approach only if 391// necessary. 392// 393// Since byte/uint8 and rune/int32 are aliases, Any can't differentiate between 394// them. To minimize surprises, []byte values are treated as binary blobs, byte 395// values are treated as uint8, and runes are always treated as integers. 396func Any(key string, value interface{}) Field { 397 switch val := value.(type) { 398 case zapcore.ObjectMarshaler: 399 return Object(key, val) 400 case zapcore.ArrayMarshaler: 401 return Array(key, val) 402 case bool: 403 return Bool(key, val) 404 case *bool: 405 return Boolp(key, val) 406 case []bool: 407 return Bools(key, val) 408 case complex128: 409 return Complex128(key, val) 410 case *complex128: 411 return Complex128p(key, val) 412 case []complex128: 413 return Complex128s(key, val) 414 case complex64: 415 return Complex64(key, val) 416 case *complex64: 417 return Complex64p(key, val) 418 case []complex64: 419 return Complex64s(key, val) 420 case float64: 421 return Float64(key, val) 422 case *float64: 423 return Float64p(key, val) 424 case []float64: 425 return Float64s(key, val) 426 case float32: 427 return Float32(key, val) 428 case *float32: 429 return Float32p(key, val) 430 case []float32: 431 return Float32s(key, val) 432 case int: 433 return Int(key, val) 434 case *int: 435 return Intp(key, val) 436 case []int: 437 return Ints(key, val) 438 case int64: 439 return Int64(key, val) 440 case *int64: 441 return Int64p(key, val) 442 case []int64: 443 return Int64s(key, val) 444 case int32: 445 return Int32(key, val) 446 case *int32: 447 return Int32p(key, val) 448 case []int32: 449 return Int32s(key, val) 450 case int16: 451 return Int16(key, val) 452 case *int16: 453 return Int16p(key, val) 454 case []int16: 455 return Int16s(key, val) 456 case int8: 457 return Int8(key, val) 458 case *int8: 459 return Int8p(key, val) 460 case []int8: 461 return Int8s(key, val) 462 case string: 463 return String(key, val) 464 case *string: 465 return Stringp(key, val) 466 case []string: 467 return Strings(key, val) 468 case uint: 469 return Uint(key, val) 470 case *uint: 471 return Uintp(key, val) 472 case []uint: 473 return Uints(key, val) 474 case uint64: 475 return Uint64(key, val) 476 case *uint64: 477 return Uint64p(key, val) 478 case []uint64: 479 return Uint64s(key, val) 480 case uint32: 481 return Uint32(key, val) 482 case *uint32: 483 return Uint32p(key, val) 484 case []uint32: 485 return Uint32s(key, val) 486 case uint16: 487 return Uint16(key, val) 488 case *uint16: 489 return Uint16p(key, val) 490 case []uint16: 491 return Uint16s(key, val) 492 case uint8: 493 return Uint8(key, val) 494 case *uint8: 495 return Uint8p(key, val) 496 case []byte: 497 return Binary(key, val) 498 case uintptr: 499 return Uintptr(key, val) 500 case *uintptr: 501 return Uintptrp(key, val) 502 case []uintptr: 503 return Uintptrs(key, val) 504 case time.Time: 505 return Time(key, val) 506 case *time.Time: 507 return Timep(key, val) 508 case []time.Time: 509 return Times(key, val) 510 case time.Duration: 511 return Duration(key, val) 512 case *time.Duration: 513 return Durationp(key, val) 514 case []time.Duration: 515 return Durations(key, val) 516 case error: 517 return NamedError(key, val) 518 case []error: 519 return Errors(key, val) 520 case fmt.Stringer: 521 return Stringer(key, val) 522 default: 523 return Reflect(key, val) 524 } 525} 526