core

Documentation

Overview

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

Index

• Constants
• Variables
• func EpochTimeEncoder(t time.Time, enc PrimitiveArrayEncoder)
• func SecondsDurationEncoder(d time.Duration, enc PrimitiveArrayEncoder)
• type ArrayEncoder
• type ArrayMarshaler
• type ArrayMarshalerFunc
  • func (f ArrayMarshalerFunc) MarshalLogArray(enc ArrayEncoder) error
• type Buffer
  • func NewBuffer(_size int) *Buffer
  • func (b *Buffer) AppendBool(v bool)
  • func (b *Buffer) AppendByte(v byte)
  • func (b *Buffer) AppendFloat(f float64, bitSize int)
  • func (b *Buffer) AppendInt(i int64)
  • func (b *Buffer) AppendString(s string)
  • func (b *Buffer) AppendUint(i uint64)
  • func (b *Buffer) Bytes() []byte
  • func (b *Buffer) Cap() int
  • func (b *Buffer) Free()
  • func (b *Buffer) Len() int
  • func (b *Buffer) Reset()
  • func (b *Buffer) String() string
  • func (b *Buffer) TrimNewline()
  • func (b *Buffer) Write(bs []byte) (int, error)
• type DurationEncoder
• type Encoder
  • func NewJSONEncoder(cfg EncoderConfig, buf *Buffer) Encoder
• type EncoderConfig
• type Field
  • func (f Field) AddTo(enc ObjectEncoder)
• type FieldType
• type ObjectEncoder
• type ObjectMarshaler
• type ObjectMarshalerFunc
  • func (f ObjectMarshalerFunc) MarshalLogObject(enc ObjectEncoder) error
• type Pool
  • func NewPool(size int) Pool
  • func (p Pool) Get() *Buffer
• type PrimitiveArrayEncoder
• type TimeEncoder

Constants

const DefaultLineEnding = "\n"

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

Variables

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.