event.go

Documentation: github.com/rs/zerolog

     1  package zerolog
     2  
     3  import (
     4  	"fmt"
     5  	"net"
     6  	"os"
     7  	"runtime"
     8  	"sync"
     9  	"time"
    10  )
    11  
    12  var eventPool = &sync.Pool{
    13  	New: func() interface{} {
    14  		return &Event{
    15  			buf: make([]byte, 0, 500),
    16  		}
    17  	},
    18  }
    19  
    20  // Event represents a log event. It is instanced by one of the level method of
    21  // Logger and finalized by the Msg or Msgf method.
    22  type Event struct {
    23  	buf       []byte
    24  	w         LevelWriter
    25  	level     Level
    26  	done      func(msg string)
    27  	stack     bool   // enable error stack trace
    28  	ch        []Hook // hooks from context
    29  	skipFrame int    // The number of additional frames to skip when printing the caller.
    30  }
    31  
    32  func putEvent(e *Event) {
    33  	// Proper usage of a sync.Pool requires each entry to have approximately
    34  	// the same memory cost. To obtain this property when the stored type
    35  	// contains a variably-sized buffer, we add a hard limit on the maximum buffer
    36  	// to place back in the pool.
    37  	//
    38  	// See https://golang.org/issue/23199
    39  	const maxSize = 1 << 16 // 64KiB
    40  	if cap(e.buf) > maxSize {
    41  		return
    42  	}
    43  	eventPool.Put(e)
    44  }
    45  
    46  // LogObjectMarshaler provides a strongly-typed and encoding-agnostic interface
    47  // to be implemented by types used with Event/Context's Object methods.
    48  type LogObjectMarshaler interface {
    49  	MarshalZerologObject(e *Event)
    50  }
    51  
    52  // LogArrayMarshaler provides a strongly-typed and encoding-agnostic interface
    53  // to be implemented by types used with Event/Context's Array methods.
    54  type LogArrayMarshaler interface {
    55  	MarshalZerologArray(a *Array)
    56  }
    57  
    58  func newEvent(w LevelWriter, level Level) *Event {
    59  	e := eventPool.Get().(*Event)
    60  	e.buf = e.buf[:0]
    61  	e.ch = nil
    62  	e.buf = enc.AppendBeginMarker(e.buf)
    63  	e.w = w
    64  	e.level = level
    65  	e.stack = false
    66  	e.skipFrame = 0
    67  	return e
    68  }
    69  
    70  func (e *Event) write() (err error) {
    71  	if e == nil {
    72  		return nil
    73  	}
    74  	if e.level != Disabled {
    75  		e.buf = enc.AppendEndMarker(e.buf)
    76  		e.buf = enc.AppendLineBreak(e.buf)
    77  		if e.w != nil {
    78  			_, err = e.w.WriteLevel(e.level, e.buf)
    79  		}
    80  	}
    81  	putEvent(e)
    82  	return
    83  }
    84  
    85  // Enabled return false if the *Event is going to be filtered out by
    86  // log level or sampling.
    87  func (e *Event) Enabled() bool {
    88  	return e != nil && e.level != Disabled
    89  }
    90  
    91  // Discard disables the event so Msg(f) won't print it.
    92  func (e *Event) Discard() *Event {
    93  	if e == nil {
    94  		return e
    95  	}
    96  	e.level = Disabled
    97  	return nil
    98  }
    99  
   100  // Msg sends the *Event with msg added as the message field if not empty.
   101  //
   102  // NOTICE: once this method is called, the *Event should be disposed.
   103  // Calling Msg twice can have unexpected result.
   104  func (e *Event) Msg(msg string) {
   105  	if e == nil {
   106  		return
   107  	}
   108  	e.msg(msg)
   109  }
   110  
   111  // Send is equivalent to calling Msg("").
   112  //
   113  // NOTICE: once this method is called, the *Event should be disposed.
   114  func (e *Event) Send() {
   115  	if e == nil {
   116  		return
   117  	}
   118  	e.msg("")
   119  }
   120  
   121  // Msgf sends the event with formatted msg added as the message field if not empty.
   122  //
   123  // NOTICE: once this method is called, the *Event should be disposed.
   124  // Calling Msgf twice can have unexpected result.
   125  func (e *Event) Msgf(format string, v ...interface{}) {
   126  	if e == nil {
   127  		return
   128  	}
   129  	e.msg(fmt.Sprintf(format, v...))
   130  }
   131  
   132  func (e *Event) MsgFunc(createMsg func() string) {
   133  	if e == nil {
   134  		return
   135  	}
   136  	e.msg(createMsg())
   137  }
   138  
   139  func (e *Event) msg(msg string) {
   140  	for _, hook := range e.ch {
   141  		hook.Run(e, e.level, msg)
   142  	}
   143  	if msg != "" {
   144  		e.buf = enc.AppendString(enc.AppendKey(e.buf, MessageFieldName), msg)
   145  	}
   146  	if e.done != nil {
   147  		defer e.done(msg)
   148  	}
   149  	if err := e.write(); err != nil {
   150  		if ErrorHandler != nil {
   151  			ErrorHandler(err)
   152  		} else {
   153  			fmt.Fprintf(os.Stderr, "zerolog: could not write event: %v\n", err)
   154  		}
   155  	}
   156  }
   157  
   158  // Fields is a helper function to use a map or slice to set fields using type assertion.
   159  // Only map[string]interface{} and []interface{} are accepted. []interface{} must
   160  // alternate string keys and arbitrary values, and extraneous ones are ignored.
   161  func (e *Event) Fields(fields interface{}) *Event {
   162  	if e == nil {
   163  		return e
   164  	}
   165  	e.buf = appendFields(e.buf, fields)
   166  	return e
   167  }
   168  
   169  // Dict adds the field key with a dict to the event context.
   170  // Use zerolog.Dict() to create the dictionary.
   171  func (e *Event) Dict(key string, dict *Event) *Event {
   172  	if e == nil {
   173  		return e
   174  	}
   175  	dict.buf = enc.AppendEndMarker(dict.buf)
   176  	e.buf = append(enc.AppendKey(e.buf, key), dict.buf...)
   177  	putEvent(dict)
   178  	return e
   179  }
   180  
   181  // Dict creates an Event to be used with the *Event.Dict method.
   182  // Call usual field methods like Str, Int etc to add fields to this
   183  // event and give it as argument the *Event.Dict method.
   184  func Dict() *Event {
   185  	return newEvent(nil, 0)
   186  }
   187  
   188  // Array adds the field key with an array to the event context.
   189  // Use zerolog.Arr() to create the array or pass a type that
   190  // implement the LogArrayMarshaler interface.
   191  func (e *Event) Array(key string, arr LogArrayMarshaler) *Event {
   192  	if e == nil {
   193  		return e
   194  	}
   195  	e.buf = enc.AppendKey(e.buf, key)
   196  	var a *Array
   197  	if aa, ok := arr.(*Array); ok {
   198  		a = aa
   199  	} else {
   200  		a = Arr()
   201  		arr.MarshalZerologArray(a)
   202  	}
   203  	e.buf = a.write(e.buf)
   204  	return e
   205  }
   206  
   207  func (e *Event) appendObject(obj LogObjectMarshaler) {
   208  	e.buf = enc.AppendBeginMarker(e.buf)
   209  	obj.MarshalZerologObject(e)
   210  	e.buf = enc.AppendEndMarker(e.buf)
   211  }
   212  
   213  // Object marshals an object that implement the LogObjectMarshaler interface.
   214  func (e *Event) Object(key string, obj LogObjectMarshaler) *Event {
   215  	if e == nil {
   216  		return e
   217  	}
   218  	e.buf = enc.AppendKey(e.buf, key)
   219  	if obj == nil {
   220  		e.buf = enc.AppendNil(e.buf)
   221  
   222  		return e
   223  	}
   224  
   225  	e.appendObject(obj)
   226  	return e
   227  }
   228  
   229  // Func allows an anonymous func to run only if the event is enabled.
   230  func (e *Event) Func(f func(e *Event)) *Event {
   231  	if e != nil && e.Enabled() {
   232  		f(e)
   233  	}
   234  	return e
   235  }
   236  
   237  // EmbedObject marshals an object that implement the LogObjectMarshaler interface.
   238  func (e *Event) EmbedObject(obj LogObjectMarshaler) *Event {
   239  	if e == nil {
   240  		return e
   241  	}
   242  	if obj == nil {
   243  		return e
   244  	}
   245  	obj.MarshalZerologObject(e)
   246  	return e
   247  }
   248  
   249  // Str adds the field key with val as a string to the *Event context.
   250  func (e *Event) Str(key, val string) *Event {
   251  	if e == nil {
   252  		return e
   253  	}
   254  	e.buf = enc.AppendString(enc.AppendKey(e.buf, key), val)
   255  	return e
   256  }
   257  
   258  // Strs adds the field key with vals as a []string to the *Event context.
   259  func (e *Event) Strs(key string, vals []string) *Event {
   260  	if e == nil {
   261  		return e
   262  	}
   263  	e.buf = enc.AppendStrings(enc.AppendKey(e.buf, key), vals)
   264  	return e
   265  }
   266  
   267  // Stringer adds the field key with val.String() (or null if val is nil)
   268  // to the *Event context.
   269  func (e *Event) Stringer(key string, val fmt.Stringer) *Event {
   270  	if e == nil {
   271  		return e
   272  	}
   273  	e.buf = enc.AppendStringer(enc.AppendKey(e.buf, key), val)
   274  	return e
   275  }
   276  
   277  // Stringers adds the field key with vals where each individual val
   278  // is used as val.String() (or null if val is empty) to the *Event
   279  // context.
   280  func (e *Event) Stringers(key string, vals []fmt.Stringer) *Event {
   281  	if e == nil {
   282  		return e
   283  	}
   284  	e.buf = enc.AppendStringers(enc.AppendKey(e.buf, key), vals)
   285  	return e
   286  }
   287  
   288  // Bytes adds the field key with val as a string to the *Event context.
   289  //
   290  // Runes outside of normal ASCII ranges will be hex-encoded in the resulting
   291  // JSON.
   292  func (e *Event) Bytes(key string, val []byte) *Event {
   293  	if e == nil {
   294  		return e
   295  	}
   296  	e.buf = enc.AppendBytes(enc.AppendKey(e.buf, key), val)
   297  	return e
   298  }
   299  
   300  // Hex adds the field key with val as a hex string to the *Event context.
   301  func (e *Event) Hex(key string, val []byte) *Event {
   302  	if e == nil {
   303  		return e
   304  	}
   305  	e.buf = enc.AppendHex(enc.AppendKey(e.buf, key), val)
   306  	return e
   307  }
   308  
   309  // RawJSON adds already encoded JSON to the log line under key.
   310  //
   311  // No sanity check is performed on b; it must not contain carriage returns and
   312  // be valid JSON.
   313  func (e *Event) RawJSON(key string, b []byte) *Event {
   314  	if e == nil {
   315  		return e
   316  	}
   317  	e.buf = appendJSON(enc.AppendKey(e.buf, key), b)
   318  	return e
   319  }
   320  
   321  // AnErr adds the field key with serialized err to the *Event context.
   322  // If err is nil, no field is added.
   323  func (e *Event) AnErr(key string, err error) *Event {
   324  	if e == nil {
   325  		return e
   326  	}
   327  	switch m := ErrorMarshalFunc(err).(type) {
   328  	case nil:
   329  		return e
   330  	case LogObjectMarshaler:
   331  		return e.Object(key, m)
   332  	case error:
   333  		if m == nil || isNilValue(m) {
   334  			return e
   335  		} else {
   336  			return e.Str(key, m.Error())
   337  		}
   338  	case string:
   339  		return e.Str(key, m)
   340  	default:
   341  		return e.Interface(key, m)
   342  	}
   343  }
   344  
   345  // Errs adds the field key with errs as an array of serialized errors to the
   346  // *Event context.
   347  func (e *Event) Errs(key string, errs []error) *Event {
   348  	if e == nil {
   349  		return e
   350  	}
   351  	arr := Arr()
   352  	for _, err := range errs {
   353  		switch m := ErrorMarshalFunc(err).(type) {
   354  		case LogObjectMarshaler:
   355  			arr = arr.Object(m)
   356  		case error:
   357  			arr = arr.Err(m)
   358  		case string:
   359  			arr = arr.Str(m)
   360  		default:
   361  			arr = arr.Interface(m)
   362  		}
   363  	}
   364  
   365  	return e.Array(key, arr)
   366  }
   367  
   368  // Err adds the field "error" with serialized err to the *Event context.
   369  // If err is nil, no field is added.
   370  //
   371  // To customize the key name, change zerolog.ErrorFieldName.
   372  //
   373  // If Stack() has been called before and zerolog.ErrorStackMarshaler is defined,
   374  // the err is passed to ErrorStackMarshaler and the result is appended to the
   375  // zerolog.ErrorStackFieldName.
   376  func (e *Event) Err(err error) *Event {
   377  	if e == nil {
   378  		return e
   379  	}
   380  	if e.stack && ErrorStackMarshaler != nil {
   381  		switch m := ErrorStackMarshaler(err).(type) {
   382  		case nil:
   383  		case LogObjectMarshaler:
   384  			e.Object(ErrorStackFieldName, m)
   385  		case error:
   386  			if m != nil && !isNilValue(m) {
   387  				e.Str(ErrorStackFieldName, m.Error())
   388  			}
   389  		case string:
   390  			e.Str(ErrorStackFieldName, m)
   391  		default:
   392  			e.Interface(ErrorStackFieldName, m)
   393  		}
   394  	}
   395  	return e.AnErr(ErrorFieldName, err)
   396  }
   397  
   398  // Stack enables stack trace printing for the error passed to Err().
   399  //
   400  // ErrorStackMarshaler must be set for this method to do something.
   401  func (e *Event) Stack() *Event {
   402  	if e != nil {
   403  		e.stack = true
   404  	}
   405  	return e
   406  }
   407  
   408  // Bool adds the field key with val as a bool to the *Event context.
   409  func (e *Event) Bool(key string, b bool) *Event {
   410  	if e == nil {
   411  		return e
   412  	}
   413  	e.buf = enc.AppendBool(enc.AppendKey(e.buf, key), b)
   414  	return e
   415  }
   416  
   417  // Bools adds the field key with val as a []bool to the *Event context.
   418  func (e *Event) Bools(key string, b []bool) *Event {
   419  	if e == nil {
   420  		return e
   421  	}
   422  	e.buf = enc.AppendBools(enc.AppendKey(e.buf, key), b)
   423  	return e
   424  }
   425  
   426  // Int adds the field key with i as a int to the *Event context.
   427  func (e *Event) Int(key string, i int) *Event {
   428  	if e == nil {
   429  		return e
   430  	}
   431  	e.buf = enc.AppendInt(enc.AppendKey(e.buf, key), i)
   432  	return e
   433  }
   434  
   435  // Ints adds the field key with i as a []int to the *Event context.
   436  func (e *Event) Ints(key string, i []int) *Event {
   437  	if e == nil {
   438  		return e
   439  	}
   440  	e.buf = enc.AppendInts(enc.AppendKey(e.buf, key), i)
   441  	return e
   442  }
   443  
   444  // Int8 adds the field key with i as a int8 to the *Event context.
   445  func (e *Event) Int8(key string, i int8) *Event {
   446  	if e == nil {
   447  		return e
   448  	}
   449  	e.buf = enc.AppendInt8(enc.AppendKey(e.buf, key), i)
   450  	return e
   451  }
   452  
   453  // Ints8 adds the field key with i as a []int8 to the *Event context.
   454  func (e *Event) Ints8(key string, i []int8) *Event {
   455  	if e == nil {
   456  		return e
   457  	}
   458  	e.buf = enc.AppendInts8(enc.AppendKey(e.buf, key), i)
   459  	return e
   460  }
   461  
   462  // Int16 adds the field key with i as a int16 to the *Event context.
   463  func (e *Event) Int16(key string, i int16) *Event {
   464  	if e == nil {
   465  		return e
   466  	}
   467  	e.buf = enc.AppendInt16(enc.AppendKey(e.buf, key), i)
   468  	return e
   469  }
   470  
   471  // Ints16 adds the field key with i as a []int16 to the *Event context.
   472  func (e *Event) Ints16(key string, i []int16) *Event {
   473  	if e == nil {
   474  		return e
   475  	}
   476  	e.buf = enc.AppendInts16(enc.AppendKey(e.buf, key), i)
   477  	return e
   478  }
   479  
   480  // Int32 adds the field key with i as a int32 to the *Event context.
   481  func (e *Event) Int32(key string, i int32) *Event {
   482  	if e == nil {
   483  		return e
   484  	}
   485  	e.buf = enc.AppendInt32(enc.AppendKey(e.buf, key), i)
   486  	return e
   487  }
   488  
   489  // Ints32 adds the field key with i as a []int32 to the *Event context.
   490  func (e *Event) Ints32(key string, i []int32) *Event {
   491  	if e == nil {
   492  		return e
   493  	}
   494  	e.buf = enc.AppendInts32(enc.AppendKey(e.buf, key), i)
   495  	return e
   496  }
   497  
   498  // Int64 adds the field key with i as a int64 to the *Event context.
   499  func (e *Event) Int64(key string, i int64) *Event {
   500  	if e == nil {
   501  		return e
   502  	}
   503  	e.buf = enc.AppendInt64(enc.AppendKey(e.buf, key), i)
   504  	return e
   505  }
   506  
   507  // Ints64 adds the field key with i as a []int64 to the *Event context.
   508  func (e *Event) Ints64(key string, i []int64) *Event {
   509  	if e == nil {
   510  		return e
   511  	}
   512  	e.buf = enc.AppendInts64(enc.AppendKey(e.buf, key), i)
   513  	return e
   514  }
   515  
   516  // Uint adds the field key with i as a uint to the *Event context.
   517  func (e *Event) Uint(key string, i uint) *Event {
   518  	if e == nil {
   519  		return e
   520  	}
   521  	e.buf = enc.AppendUint(enc.AppendKey(e.buf, key), i)
   522  	return e
   523  }
   524  
   525  // Uints adds the field key with i as a []int to the *Event context.
   526  func (e *Event) Uints(key string, i []uint) *Event {
   527  	if e == nil {
   528  		return e
   529  	}
   530  	e.buf = enc.AppendUints(enc.AppendKey(e.buf, key), i)
   531  	return e
   532  }
   533  
   534  // Uint8 adds the field key with i as a uint8 to the *Event context.
   535  func (e *Event) Uint8(key string, i uint8) *Event {
   536  	if e == nil {
   537  		return e
   538  	}
   539  	e.buf = enc.AppendUint8(enc.AppendKey(e.buf, key), i)
   540  	return e
   541  }
   542  
   543  // Uints8 adds the field key with i as a []int8 to the *Event context.
   544  func (e *Event) Uints8(key string, i []uint8) *Event {
   545  	if e == nil {
   546  		return e
   547  	}
   548  	e.buf = enc.AppendUints8(enc.AppendKey(e.buf, key), i)
   549  	return e
   550  }
   551  
   552  // Uint16 adds the field key with i as a uint16 to the *Event context.
   553  func (e *Event) Uint16(key string, i uint16) *Event {
   554  	if e == nil {
   555  		return e
   556  	}
   557  	e.buf = enc.AppendUint16(enc.AppendKey(e.buf, key), i)
   558  	return e
   559  }
   560  
   561  // Uints16 adds the field key with i as a []int16 to the *Event context.
   562  func (e *Event) Uints16(key string, i []uint16) *Event {
   563  	if e == nil {
   564  		return e
   565  	}
   566  	e.buf = enc.AppendUints16(enc.AppendKey(e.buf, key), i)
   567  	return e
   568  }
   569  
   570  // Uint32 adds the field key with i as a uint32 to the *Event context.
   571  func (e *Event) Uint32(key string, i uint32) *Event {
   572  	if e == nil {
   573  		return e
   574  	}
   575  	e.buf = enc.AppendUint32(enc.AppendKey(e.buf, key), i)
   576  	return e
   577  }
   578  
   579  // Uints32 adds the field key with i as a []int32 to the *Event context.
   580  func (e *Event) Uints32(key string, i []uint32) *Event {
   581  	if e == nil {
   582  		return e
   583  	}
   584  	e.buf = enc.AppendUints32(enc.AppendKey(e.buf, key), i)
   585  	return e
   586  }
   587  
   588  // Uint64 adds the field key with i as a uint64 to the *Event context.
   589  func (e *Event) Uint64(key string, i uint64) *Event {
   590  	if e == nil {
   591  		return e
   592  	}
   593  	e.buf = enc.AppendUint64(enc.AppendKey(e.buf, key), i)
   594  	return e
   595  }
   596  
   597  // Uints64 adds the field key with i as a []int64 to the *Event context.
   598  func (e *Event) Uints64(key string, i []uint64) *Event {
   599  	if e == nil {
   600  		return e
   601  	}
   602  	e.buf = enc.AppendUints64(enc.AppendKey(e.buf, key), i)
   603  	return e
   604  }
   605  
   606  // Float32 adds the field key with f as a float32 to the *Event context.
   607  func (e *Event) Float32(key string, f float32) *Event {
   608  	if e == nil {
   609  		return e
   610  	}
   611  	e.buf = enc.AppendFloat32(enc.AppendKey(e.buf, key), f)
   612  	return e
   613  }
   614  
   615  // Floats32 adds the field key with f as a []float32 to the *Event context.
   616  func (e *Event) Floats32(key string, f []float32) *Event {
   617  	if e == nil {
   618  		return e
   619  	}
   620  	e.buf = enc.AppendFloats32(enc.AppendKey(e.buf, key), f)
   621  	return e
   622  }
   623  
   624  // Float64 adds the field key with f as a float64 to the *Event context.
   625  func (e *Event) Float64(key string, f float64) *Event {
   626  	if e == nil {
   627  		return e
   628  	}
   629  	e.buf = enc.AppendFloat64(enc.AppendKey(e.buf, key), f)
   630  	return e
   631  }
   632  
   633  // Floats64 adds the field key with f as a []float64 to the *Event context.
   634  func (e *Event) Floats64(key string, f []float64) *Event {
   635  	if e == nil {
   636  		return e
   637  	}
   638  	e.buf = enc.AppendFloats64(enc.AppendKey(e.buf, key), f)
   639  	return e
   640  }
   641  
   642  // Timestamp adds the current local time as UNIX timestamp to the *Event context with the "time" key.
   643  // To customize the key name, change zerolog.TimestampFieldName.
   644  //
   645  // NOTE: It won't dedupe the "time" key if the *Event (or *Context) has one
   646  // already.
   647  func (e *Event) Timestamp() *Event {
   648  	if e == nil {
   649  		return e
   650  	}
   651  	e.buf = enc.AppendTime(enc.AppendKey(e.buf, TimestampFieldName), TimestampFunc(), TimeFieldFormat)
   652  	return e
   653  }
   654  
   655  // Time adds the field key with t formatted as string using zerolog.TimeFieldFormat.
   656  func (e *Event) Time(key string, t time.Time) *Event {
   657  	if e == nil {
   658  		return e
   659  	}
   660  	e.buf = enc.AppendTime(enc.AppendKey(e.buf, key), t, TimeFieldFormat)
   661  	return e
   662  }
   663  
   664  // Times adds the field key with t formatted as string using zerolog.TimeFieldFormat.
   665  func (e *Event) Times(key string, t []time.Time) *Event {
   666  	if e == nil {
   667  		return e
   668  	}
   669  	e.buf = enc.AppendTimes(enc.AppendKey(e.buf, key), t, TimeFieldFormat)
   670  	return e
   671  }
   672  
   673  // Dur adds the field key with duration d stored as zerolog.DurationFieldUnit.
   674  // If zerolog.DurationFieldInteger is true, durations are rendered as integer
   675  // instead of float.
   676  func (e *Event) Dur(key string, d time.Duration) *Event {
   677  	if e == nil {
   678  		return e
   679  	}
   680  	e.buf = enc.AppendDuration(enc.AppendKey(e.buf, key), d, DurationFieldUnit, DurationFieldInteger)
   681  	return e
   682  }
   683  
   684  // Durs adds the field key with duration d stored as zerolog.DurationFieldUnit.
   685  // If zerolog.DurationFieldInteger is true, durations are rendered as integer
   686  // instead of float.
   687  func (e *Event) Durs(key string, d []time.Duration) *Event {
   688  	if e == nil {
   689  		return e
   690  	}
   691  	e.buf = enc.AppendDurations(enc.AppendKey(e.buf, key), d, DurationFieldUnit, DurationFieldInteger)
   692  	return e
   693  }
   694  
   695  // TimeDiff adds the field key with positive duration between time t and start.
   696  // If time t is not greater than start, duration will be 0.
   697  // Duration format follows the same principle as Dur().
   698  func (e *Event) TimeDiff(key string, t time.Time, start time.Time) *Event {
   699  	if e == nil {
   700  		return e
   701  	}
   702  	var d time.Duration
   703  	if t.After(start) {
   704  		d = t.Sub(start)
   705  	}
   706  	e.buf = enc.AppendDuration(enc.AppendKey(e.buf, key), d, DurationFieldUnit, DurationFieldInteger)
   707  	return e
   708  }
   709  
   710  // Interface adds the field key with i marshaled using reflection.
   711  func (e *Event) Interface(key string, i interface{}) *Event {
   712  	if e == nil {
   713  		return e
   714  	}
   715  	if obj, ok := i.(LogObjectMarshaler); ok {
   716  		return e.Object(key, obj)
   717  	}
   718  	e.buf = enc.AppendInterface(enc.AppendKey(e.buf, key), i)
   719  	return e
   720  }
   721  
   722  // CallerSkipFrame instructs any future Caller calls to skip the specified number of frames.
   723  // This includes those added via hooks from the context.
   724  func (e *Event) CallerSkipFrame(skip int) *Event {
   725  	if e == nil {
   726  		return e
   727  	}
   728  	e.skipFrame += skip
   729  	return e
   730  }
   731  
   732  // Caller adds the file:line of the caller with the zerolog.CallerFieldName key.
   733  // The argument skip is the number of stack frames to ascend
   734  // Skip If not passed, use the global variable CallerSkipFrameCount
   735  func (e *Event) Caller(skip ...int) *Event {
   736  	sk := CallerSkipFrameCount
   737  	if len(skip) > 0 {
   738  		sk = skip[0] + CallerSkipFrameCount
   739  	}
   740  	return e.caller(sk)
   741  }
   742  
   743  func (e *Event) caller(skip int) *Event {
   744  	if e == nil {
   745  		return e
   746  	}
   747  	pc, file, line, ok := runtime.Caller(skip + e.skipFrame)
   748  	if !ok {
   749  		return e
   750  	}
   751  	e.buf = enc.AppendString(enc.AppendKey(e.buf, CallerFieldName), CallerMarshalFunc(pc, file, line))
   752  	return e
   753  }
   754  
   755  // IPAddr adds IPv4 or IPv6 Address to the event
   756  func (e *Event) IPAddr(key string, ip net.IP) *Event {
   757  	if e == nil {
   758  		return e
   759  	}
   760  	e.buf = enc.AppendIPAddr(enc.AppendKey(e.buf, key), ip)
   761  	return e
   762  }
   763  
   764  // IPPrefix adds IPv4 or IPv6 Prefix (address and mask) to the event
   765  func (e *Event) IPPrefix(key string, pfx net.IPNet) *Event {
   766  	if e == nil {
   767  		return e
   768  	}
   769  	e.buf = enc.AppendIPPrefix(enc.AppendKey(e.buf, key), pfx)
   770  	return e
   771  }
   772  
   773  // MACAddr adds MAC address to the event
   774  func (e *Event) MACAddr(key string, ha net.HardwareAddr) *Event {
   775  	if e == nil {
   776  		return e
   777  	}
   778  	e.buf = enc.AppendMACAddr(enc.AppendKey(e.buf, key), ha)
   779  	return e
   780  }
   781
View as plain text