Documentation

Overview

    Package core houses zap's shared internal buffer pool. Third-party packages can recreate the same functionality with buffers.NewPool.

    Index

    Constants

    View Source
    const DefaultLineEnding = "\n"

      DefaultLineEnding defines the default line ending when writing logs. Alternate line endings specified in EncoderConfig can override this behavior.

      Variables

      View Source
      var (
      
      	// GetPool retrieves a buffer from the pool, creating one if necessary.
      	GetPool = _pool.Get
      )

      Functions

      func EpochTimeEncoder

      func EpochTimeEncoder(t time.Time, enc PrimitiveArrayEncoder)

        EpochTimeEncoder serializes a time.Time to a floating-point number of seconds since the Unix epoch.

        func SecondsDurationEncoder

        func SecondsDurationEncoder(d time.Duration, enc PrimitiveArrayEncoder)

          SecondsDurationEncoder serializes a time.Duration to a floating-point number of seconds elapsed.

          Types

          type ArrayEncoder

          type ArrayEncoder interface {
          	// Built-in types.
          	PrimitiveArrayEncoder
          
          	// Time-related types.
          	AppendDuration(time.Duration)
          	AppendTime(time.Time)
          
          	// Logging-specific marshalers.
          	AppendArray(ArrayMarshaler) error
          	AppendObject(ObjectMarshaler) error
          
          	// AppendReflected uses reflection to serialize arbitrary objects, so it's
          	// slow and allocation-heavy.
          	AppendReflected(value interface{}) error
          }

            ArrayEncoder is a strongly-typed, encoding-agnostic interface for adding array-like objects to the logging context. Of note, it supports mixed-type arrays even though they aren't typical in Go. Like slices, ArrayEncoders aren't safe for concurrent use (though typical use shouldn't require locks).

            type ArrayMarshaler

            type ArrayMarshaler interface {
            	MarshalLogArray(ArrayEncoder) error
            }

              ArrayMarshaler allows user-defined types to efficiently add themselves to the logging context, and to selectively omit information which shouldn't be included in logs (e.g., passwords).

              type ArrayMarshalerFunc

              type ArrayMarshalerFunc func(ArrayEncoder) error

                ArrayMarshalerFunc is a type adapter that turns a function into an ArrayMarshaler.

                func (ArrayMarshalerFunc) MarshalLogArray

                func (f ArrayMarshalerFunc) MarshalLogArray(enc ArrayEncoder) error

                  MarshalLogArray calls the underlying function.

                  type Buffer

                  type Buffer struct {
                  	// contains filtered or unexported fields
                  }

                    Buffer is a thin wrapper around a byte slice. It's intended to be pooled, so the only way to construct one is via a Pool.

                    func NewBuffer

                    func NewBuffer(_size int) *Buffer

                      NewBuffer is new buffer

                      func (*Buffer) AppendBool

                      func (b *Buffer) AppendBool(v bool)

                        AppendBool appends a bool to the underlying buffer.

                        func (*Buffer) AppendByte

                        func (b *Buffer) AppendByte(v byte)

                          AppendByte writes a single byte to the Buffer.

                          func (*Buffer) AppendFloat

                          func (b *Buffer) AppendFloat(f float64, bitSize int)

                            AppendFloat appends a float to the underlying buffer. It doesn't quote NaN or +/- Inf.

                            func (*Buffer) AppendInt

                            func (b *Buffer) AppendInt(i int64)

                              AppendInt appends an integer to the underlying buffer (assuming base 10).

                              func (*Buffer) AppendString

                              func (b *Buffer) AppendString(s string)

                                AppendString writes a string to the Buffer.

                                func (*Buffer) AppendUint

                                func (b *Buffer) AppendUint(i uint64)

                                  AppendUint appends an unsigned integer to the underlying buffer (assuming base 10).

                                  func (*Buffer) Bytes

                                  func (b *Buffer) Bytes() []byte

                                    Bytes returns a mutable reference to the underlying byte slice.

                                    func (*Buffer) Cap

                                    func (b *Buffer) Cap() int

                                      Cap returns the capacity of the underlying byte slice.

                                      func (*Buffer) Free

                                      func (b *Buffer) Free()

                                        Free returns the Buffer to its Pool.

                                        Callers must not retain references to the Buffer after calling Free.

                                        func (*Buffer) Len

                                        func (b *Buffer) Len() int

                                          Len returns the length of the underlying byte slice.

                                          func (*Buffer) Reset

                                          func (b *Buffer) Reset()

                                            Reset resets the underlying byte slice. Subsequent writes re-use the slice's backing array.

                                            func (*Buffer) String

                                            func (b *Buffer) String() string

                                              String returns a string copy of the underlying byte slice.

                                              func (*Buffer) TrimNewline

                                              func (b *Buffer) TrimNewline()

                                                TrimNewline trims any final "\n" byte from the end of the buffer.

                                                func (*Buffer) Write

                                                func (b *Buffer) Write(bs []byte) (int, error)

                                                  Write implements io.Writer.

                                                  type DurationEncoder

                                                  type DurationEncoder func(time.Duration, PrimitiveArrayEncoder)

                                                    A DurationEncoder serializes a time.Duration to a primitive type.

                                                    type Encoder

                                                    type Encoder interface {
                                                    	ObjectEncoder
                                                    
                                                    	// Clone copies the encoder, ensuring that adding fields to the copy doesn't
                                                    	// affect the original.
                                                    	Clone() Encoder
                                                    
                                                    	// EncodeEntry encodes an entry and fields, along with any accumulated
                                                    	// context, into a byte buffer and returns it.
                                                    	Encode(*Buffer, ...Field) error
                                                    }

                                                      Encoder is a format-agnostic interface for all log entry marshalers. Since log encoders don't need to support the same wide range of use cases as general-purpose marshalers, it's possible to make them faster and lower-allocation.

                                                      Implementations of the ObjectEncoder interface's methods can, of course, freely modify the receiver. However, the Clone and EncodeEntry methods will be called concurrently and shouldn't modify the receiver.

                                                      func NewJSONEncoder

                                                      func NewJSONEncoder(cfg EncoderConfig, buf *Buffer) Encoder

                                                        NewJSONEncoder creates a fast, low-allocation JSON encoder. The encoder appropriately escapes all field keys and values.

                                                        Note that the encoder doesn't deduplicate keys, so it's possible to produce a message like

                                                        {"foo":"bar","foo":"baz"}
                                                        

                                                        This is permitted by the JSON specification, but not encouraged. Many libraries will ignore duplicate key-value pairs (typically keeping the last pair) when unmarshaling, but users should attempt to avoid adding duplicate keys.

                                                        type EncoderConfig

                                                        type EncoderConfig struct {
                                                        	EncodeTime     TimeEncoder     `json:"timeEncoder" yaml:"timeEncoder"`
                                                        	EncodeDuration DurationEncoder `json:"durationEncoder" yaml:"durationEncoder"`
                                                        }

                                                          An EncoderConfig allows users to configure the concrete encoders supplied by zapcore.

                                                          type Field

                                                          type Field struct {
                                                          	Key       string
                                                          	Value     interface{}
                                                          	Type      FieldType
                                                          	StringVal string
                                                          	Int64Val  int64
                                                          }

                                                            Field is for encoder

                                                            func (Field) AddTo

                                                            func (f Field) AddTo(enc ObjectEncoder)

                                                              AddTo exports a field through the ObjectEncoder interface. It's primarily useful to library authors, and shouldn't be necessary in most applications.

                                                              type FieldType

                                                              type FieldType int32

                                                                FieldType represent D value type

                                                                const (
                                                                	UnknownType FieldType = iota
                                                                	StringType
                                                                	IntTpye
                                                                	Int64Type
                                                                	UintType
                                                                	Uint64Type
                                                                	Float32Type
                                                                	Float64Type
                                                                	DurationType
                                                                )

                                                                  DType enum

                                                                  type ObjectEncoder

                                                                  type ObjectEncoder interface {
                                                                  	// Logging-specific marshalers.
                                                                  	AddArray(key string, marshaler ArrayMarshaler) error
                                                                  	AddObject(key string, marshaler ObjectMarshaler) error
                                                                  
                                                                  	// Built-in types.
                                                                  	AddBinary(key string, value []byte)     // for arbitrary bytes
                                                                  	AddByteString(key string, value []byte) // for UTF-8 encoded bytes
                                                                  	AddBool(key string, value bool)
                                                                  	AddComplex128(key string, value complex128)
                                                                  	AddComplex64(key string, value complex64)
                                                                  	AddDuration(key string, value time.Duration)
                                                                  	AddFloat64(key string, value float64)
                                                                  	AddFloat32(key string, value float32)
                                                                  	AddInt(key string, value int)
                                                                  	AddInt64(key string, value int64)
                                                                  	AddInt32(key string, value int32)
                                                                  	AddInt16(key string, value int16)
                                                                  	AddInt8(key string, value int8)
                                                                  	AddString(key, value string)
                                                                  	AddTime(key string, value time.Time)
                                                                  	AddUint(key string, value uint)
                                                                  	AddUint64(key string, value uint64)
                                                                  	AddUint32(key string, value uint32)
                                                                  	AddUint16(key string, value uint16)
                                                                  	AddUint8(key string, value uint8)
                                                                  	AddUintptr(key string, value uintptr)
                                                                  
                                                                  	// AddReflected uses reflection to serialize arbitrary objects, so it's slow
                                                                  	// and allocation-heavy.
                                                                  	AddReflected(key string, value interface{}) error
                                                                  	// OpenNamespace opens an isolated namespace where all subsequent fields will
                                                                  	// be added. Applications can use namespaces to prevent key collisions when
                                                                  	// injecting loggers into sub-components or third-party libraries.
                                                                  	OpenNamespace(key string)
                                                                  }

                                                                    ObjectEncoder is a strongly-typed, encoding-agnostic interface for adding a map- or struct-like object to the logging context. Like maps, ObjectEncoders aren't safe for concurrent use (though typical use shouldn't require locks).

                                                                    type ObjectMarshaler

                                                                    type ObjectMarshaler interface {
                                                                    	MarshalLogObject(ObjectEncoder) error
                                                                    }

                                                                      ObjectMarshaler allows user-defined types to efficiently add themselves to the logging context, and to selectively omit information which shouldn't be included in logs (e.g., passwords).

                                                                      type ObjectMarshalerFunc

                                                                      type ObjectMarshalerFunc func(ObjectEncoder) error

                                                                        ObjectMarshalerFunc is a type adapter that turns a function into an ObjectMarshaler.

                                                                        func (ObjectMarshalerFunc) MarshalLogObject

                                                                        func (f ObjectMarshalerFunc) MarshalLogObject(enc ObjectEncoder) error

                                                                          MarshalLogObject calls the underlying function.

                                                                          type Pool

                                                                          type Pool struct {
                                                                          	// contains filtered or unexported fields
                                                                          }

                                                                            A Pool is a type-safe wrapper around a sync.Pool.

                                                                            func NewPool

                                                                            func NewPool(size int) Pool

                                                                              NewPool constructs a new Pool.

                                                                              func (Pool) Get

                                                                              func (p Pool) Get() *Buffer

                                                                                Get retrieves a Buffer from the pool, creating one if necessary.

                                                                                type PrimitiveArrayEncoder

                                                                                type PrimitiveArrayEncoder interface {
                                                                                	// Built-in types.
                                                                                	AppendBool(bool)
                                                                                	AppendByteString([]byte) // for UTF-8 encoded bytes
                                                                                	AppendComplex128(complex128)
                                                                                	AppendComplex64(complex64)
                                                                                	AppendFloat64(float64)
                                                                                	AppendFloat32(float32)
                                                                                	AppendInt(int)
                                                                                	AppendInt64(int64)
                                                                                	AppendInt32(int32)
                                                                                	AppendInt16(int16)
                                                                                	AppendInt8(int8)
                                                                                	AppendString(string)
                                                                                	AppendUint(uint)
                                                                                	AppendUint64(uint64)
                                                                                	AppendUint32(uint32)
                                                                                	AppendUint16(uint16)
                                                                                	AppendUint8(uint8)
                                                                                	AppendUintptr(uintptr)
                                                                                }

                                                                                  PrimitiveArrayEncoder is the subset of the ArrayEncoder interface that deals only in Go's built-in types. It's included only so that Duration- and TimeEncoders cannot trigger infinite recursion.

                                                                                  type TimeEncoder

                                                                                  type TimeEncoder func(time.Time, PrimitiveArrayEncoder)

                                                                                    A TimeEncoder serializes a time.Time to a primitive type.