README
Documentation
¶
Index ¶
- Constants
- func RegisterEncoder(name string, constructor func(zapcore.EncoderConfig) (zapcore.Encoder, error)) error
- type AtomicLevel
- func (lvl AtomicLevel) Enabled(l zapcore.Level) bool
- func (lvl AtomicLevel) Level() zapcore.Level
- func (lvl AtomicLevel) MarshalText() (text []byte, err error)
- func (lvl AtomicLevel) SetLevel(l zapcore.Level)
- func (lvl AtomicLevel) String() string
- func (lvl *AtomicLevel) UnmarshalText(text []byte) error
- type Config
- type Field
- func Any(key string, value interface{}) Field
- func Array(key string, val zapcore.ArrayMarshaler) Field
- func Binary(key string, val []byte) Field
- func Bool(key string, val bool) Field
- func Bools(key string, bs []bool) Field
- func ByteString(key string, val []byte) Field
- func ByteStrings(key string, bss [][]byte) Field
- func Complex128(key string, val complex128) Field
- func Complex128s(key string, nums []complex128) Field
- func Complex64(key string, val complex64) Field
- func Complex64s(key string, nums []complex64) Field
- func Duration(key string, val time.Duration) Field
- func Durations(key string, ds []time.Duration) Field
- func Error(err error) Field
- func Errors(key string, errs []error) Field
- func Float32(key string, val float32) Field
- func Float32s(key string, nums []float32) Field
- func Float64(key string, val float64) Field
- func Float64s(key string, nums []float64) Field
- func Int(key string, val int) Field
- func Int16(key string, val int16) Field
- func Int16s(key string, nums []int16) Field
- func Int32(key string, val int32) Field
- func Int32s(key string, nums []int32) Field
- func Int64(key string, val int64) Field
- func Int64s(key string, nums []int64) Field
- func Int8(key string, val int8) Field
- func Int8s(key string, nums []int8) Field
- func Ints(key string, nums []int) Field
- func NamedError(key string, err error) Field
- func Namespace(key string) Field
- func Object(key string, val zapcore.ObjectMarshaler) Field
- func Reflect(key string, val interface{}) Field
- func Skip() Field
- func String(key string, val string) Field
- func Stringer(key string, val fmt.Stringer) Field
- func Strings(key string, ss []string) Field
- func Time(key string, val time.Time) Field
- func Times(key string, ts []time.Time) Field
- func Uint(key string, val uint) Field
- func Uint16(key string, val uint16) Field
- func Uint16s(key string, nums []uint16) Field
- func Uint32(key string, val uint32) Field
- func Uint32s(key string, nums []uint32) Field
- func Uint64(key string, val uint64) Field
- func Uint64s(key string, nums []uint64) Field
- func Uint8(key string, val uint8) Field
- func Uint8s(key string, nums []uint8) Field
- func Uintptr(key string, val uintptr) Field
- func Uintptrs(key string, us []uintptr) Field
- func Uints(key string, nums []uint) Field
- type LevelEnablerFunc
- type Logger
- func (log *Logger) Check(lvl zapcore.Level, msg string) *zapcore.CheckedEntry
- func (log *Logger) Core() zapcore.Core
- func (log *Logger) Debug(msg string, fields ...Field)
- func (log *Logger) Error(msg string, fields ...Field)
- func (log *Logger) Fatal(msg string, fields ...Field)
- func (log *Logger) Info(msg string, fields ...Field)
- func (log *Logger) Panic(msg string, fields ...Field)
- func (l *Logger) ReOpen() error
- func (log *Logger) Sync() error
- func (log *Logger) Warn(msg string, fields ...Field)
- func (log *Logger) With(fields ...Field) *Logger
- func (log *Logger) WithOptions(opts ...Option) *Logger
- type Option
Constants ¶
const ( // DebugLevel logs are typically voluminous, and are usually disabled in // production. DebugLevel = zapcore.DebugLevel // InfoLevel is the default logging priority. InfoLevel = zapcore.InfoLevel // WarnLevel logs are more important than Info, but don't need individual // human review. WarnLevel = zapcore.WarnLevel // ErrorLevel logs are high-priority. If an application is running smoothly, // it shouldn't generate any error-level logs. ErrorLevel = zapcore.ErrorLevel // PanicLevel logs a message, then panics. PanicLevel = zapcore.PanicLevel // FatalLevel logs a message, then calls os.Exit(1). FatalLevel = zapcore.FatalLevel )
Variables ¶
This section is empty.
Functions ¶
func RegisterEncoder ¶
func RegisterEncoder(name string, constructor func(zapcore.EncoderConfig) (zapcore.Encoder, error)) error
RegisterEncoder registers an encoder constructor, which the Config struct can then reference. By default, the "json" and "console" encoders are registered.
Attempting to register an encoder whose name is already taken returns an error.
Types ¶
type AtomicLevel ¶
type AtomicLevel struct {
// contains filtered or unexported fields
}
An AtomicLevel is an atomically changeable, dynamic logging level. It lets you safely change the log level of a tree of loggers (the root logger and any children created by adding context) at runtime.
The AtomicLevel itself is an http.Handler that serves a JSON endpoint to alter its level.
AtomicLevels must be created with the NewAtomicLevel constructor to allocate their internal atomic pointer.
func NewAtomicLevel ¶
func NewAtomicLevel() AtomicLevel
NewAtomicLevel creates an AtomicLevel with InfoLevel and above logging enabled.
func NewAtomicLevelAt ¶
func NewAtomicLevelAt(l zapcore.Level) AtomicLevel
NewAtomicLevelAt is a convenience function that creates an AtomicLevel and then calls SetLevel with the given level.
func (AtomicLevel) Enabled ¶
func (lvl AtomicLevel) Enabled(l zapcore.Level) bool
Enabled implements the zapcore.LevelEnabler interface, which allows the AtomicLevel to be used in place of traditional static levels.
func (AtomicLevel) Level ¶
func (lvl AtomicLevel) Level() zapcore.Level
Level returns the minimum enabled log level.
func (AtomicLevel) MarshalText ¶
func (lvl AtomicLevel) MarshalText() (text []byte, err error)
MarshalText marshals the AtomicLevel to a byte slice. It uses the same text representation as the static zapcore.Levels ("debug", "info", "warn", "error", "dpanic", "panic", and "fatal").
func (AtomicLevel) SetLevel ¶
func (lvl AtomicLevel) SetLevel(l zapcore.Level)
SetLevel alters the logging level.
func (AtomicLevel) String ¶
func (lvl AtomicLevel) String() string
String returns the string representation of the underlying Level.
func (*AtomicLevel) UnmarshalText ¶
func (lvl *AtomicLevel) UnmarshalText(text []byte) error
UnmarshalText unmarshals the text to an AtomicLevel. It uses the same text representations as the static zapcore.Levels ("debug", "info", "warn", "error", "dpanic", "panic", and "fatal").
type Config ¶
type Config struct {
// Level is the minimum enabled logging level. Note that this is a dynamic
// level, so calling Config.Level.SetLevel will atomically change the log
// level of all loggers descended from this config.
Level AtomicLevel `json:"level" yaml:"level"`
// Encoding sets the logger's encoding. Valid values are "json" and
// "console", as well as any third-party encodings registered via
// RegisterEncoder.
Encoding string `json:"encoding" yaml:"encoding"`
// EncoderConfig sets options for the chosen encoder. See
// zapcore.EncoderConfig for details.
EncoderConfig zapcore.EncoderConfig `json:"encoderConfig" yaml:"encoderConfig"`
// OutputPath is a URL or file path to write logging output to.
// See Open for details.
OutputPath string `json:"outputPath" yaml:"outputPath"`
// BufSize log write buf,
// See zapcore/writebuf.go for details.
BufSize int `json:"bufSize" yaml:"bufSize"`
// Flush will flush log buf every Flush seconds.
Flush int `json:"flush" yaml:"flush"`
}
Config offers a declarative way to construct a logger. It doesn't do anything that can't be done with New, Options, and the various zapcore.WriteSyncer and zapcore.Core wrappers, but it's a simpler way to toggle common options.
Note that Config intentionally supports only the most common options. More unusual logging setups (logging to network connections or message queues, splitting output between multiple files, etc.) are possible, but require direct use of the zapcore package. For sample code, see the package-level BasicConfiguration and AdvancedConfiguration examples.
For an example showing runtime log level changes, see the documentation for AtomicLevel.
type Field ¶
Field is an alias for Field. Aliasing this type dramatically improves the navigability of this package's API documentation.
func Any ¶
Any takes a key and an arbitrary value and chooses the best way to represent them as a field, falling back to a reflection-based approach only if necessary.
Since byte/uint8 and rune/int32 are aliases, Any can't differentiate between them. To minimize surprises, []byte values are treated as binary blobs, byte values are treated as uint8, and runes are always treated as integers.
func Array ¶
func Array(key string, val zapcore.ArrayMarshaler) Field
Array constructs a field with the given key and ArrayMarshaler. It provides a flexible, but still type-safe and efficient, way to add array-like types to the logging context. The struct's MarshalLogArray method is called lazily.
func Binary ¶
Binary constructs a field that carries an opaque binary blob.
Binary data is serialized in an encoding-appropriate format. For example, zap's JSON encoder base64-encodes binary blobs. To log UTF-8 encoded text, use ByteString.
func ByteString ¶
ByteString constructs a field that carries UTF-8 encoded text as a []byte. To log opaque binary blobs (which aren't necessarily valid UTF-8), use Binary.
func ByteStrings ¶
ByteStrings constructs a field that carries a slice of []byte, each of which must be UTF-8 encoded text.
func Complex128 ¶
func Complex128(key string, val complex128) Field
Complex128 constructs a field that carries a complex number. Unlike most numeric fields, this costs an allocation (to convert the complex128 to interface{}).
func Complex128s ¶
func Complex128s(key string, nums []complex128) Field
Complex128s constructs a field that carries a slice of complex numbers.
func Complex64 ¶
Complex64 constructs a field that carries a complex number. Unlike most numeric fields, this costs an allocation (to convert the complex64 to interface{}).
func Complex64s ¶
Complex64s constructs a field that carries a slice of complex numbers.
func Duration ¶
Duration constructs a field with the given key and value. The encoder controls how the duration is serialized.
func Float32 ¶
Float32 constructs a field that carries a float32. The way the floating-point value is represented is encoder-dependent, so marshaling is necessarily lazy.
func Float64 ¶
Float64 constructs a field that carries a float64. The way the floating-point value is represented is encoder-dependent, so marshaling is necessarily lazy.
func NamedError ¶
NamedError constructs a field that lazily stores err.Error() under the provided key. Errors which also implement fmt.Formatter (like those produced by github.com/pkg/errors) will also have their verbose representation stored under key+"Verbose". If passed a nil error, the field is a no-op.
For the common case in which the key is simply "error", the Error function is shorter and less repetitive.
func Namespace ¶
Namespace creates a named, isolated scope within the logger's context. All subsequent fields will be added to the new namespace.
This helps prevent key collisions when injecting loggers into sub-components or third-party libraries.
func Object ¶
func Object(key string, val zapcore.ObjectMarshaler) Field
Object constructs a field with the given key and ObjectMarshaler. It provides a flexible, but still type-safe and efficient, way to add map- or struct-like user-defined types to the logging context. The struct's MarshalLogObject method is called lazily.
func Reflect ¶
Reflect constructs a field with the given key and an arbitrary object. It uses an encoding-appropriate, reflection-based function to lazily serialize nearly any object into the logging context, but it's relatively slow and allocation-heavy. Outside tests, Any is always a better choice.
If encoding fails (e.g., trying to serialize a map[int]string to JSON), Reflect includes the error message in the final log output.
func Skip ¶
func Skip() Field
Skip constructs a no-op field, which is often useful when handling invalid inputs in other Field constructors.
func Stringer ¶
Stringer constructs a field with the given key and the output of the value's String method. The Stringer's String method is called lazily.
func Time ¶
Time constructs a Field with the given key and value. The encoder controls how the time is serialized.
type LevelEnablerFunc ¶
LevelEnablerFunc is a convenient way to implement zapcore.LevelEnabler with an anonymous function.
It's particularly useful when splitting log output between different outputs (e.g., standard error and standard out). For sample code, see the package-level AdvancedConfiguration example.
type Logger ¶
type Logger struct {
// contains filtered or unexported fields
}
A Logger provides fast, leveled, structured logging. All methods are safe for concurrent use.
The Logger is designed for contexts in which every microsecond and every allocation matters, so its API intentionally favors performance and type safety over brevity. For most applications, the SugaredLogger strikes a better balance between performance and ergonomics.
func New ¶
New constructs a new Logger from the provided zapcore.Core and Options. If the passed zapcore.Core is nil, it falls back to using a no-op implementation.
This is the most flexible way to construct a Logger, but also the most verbose. For typical use cases, the highly-opinionated presets (NewProduction, NewDevelopment, and NewExample) or the Config struct are more convenient.
For sample code, see the package-level AdvancedConfiguration example.
func (*Logger) Check ¶
Check returns a CheckedEntry if logging a message at the specified level is enabled. It's a completely optional optimization; in high-performance applications, Check can help avoid allocating a slice to hold fields.
func (*Logger) Debug ¶
Debug logs a message at DebugLevel. The message includes any fields passed at the log site, as well as any fields accumulated on the logger.
func (*Logger) Error ¶
Error logs a message at ErrorLevel. The message includes any fields passed at the log site, as well as any fields accumulated on the logger.
func (*Logger) Fatal ¶
Fatal logs a message at FatalLevel. The message includes any fields passed at the log site, as well as any fields accumulated on the logger.
The logger then calls os.Exit(1), even if logging at FatalLevel is disabled.
func (*Logger) Info ¶
Info logs a message at InfoLevel. The message includes any fields passed at the log site, as well as any fields accumulated on the logger.
func (*Logger) Panic ¶
Panic logs a message at PanicLevel. The message includes any fields passed at the log site, as well as any fields accumulated on the logger.
The logger then panics, even if logging at PanicLevel is disabled.
func (*Logger) Sync ¶
Sync calls the underlying Core's Sync method, flushing any buffered log entries. Applications should take care to call Sync before exiting.
func (*Logger) Warn ¶
Warn logs a message at WarnLevel. The message includes any fields passed at the log site, as well as any fields accumulated on the logger.
func (*Logger) With ¶
With creates a child logger and adds structured context to it. Fields added to the child don't affect the parent, and vice versa.
func (*Logger) WithOptions ¶
WithOptions clones the current Logger, applies the supplied Options, and returns the resulting Logger. It's safe to use concurrently.
type Option ¶
type Option interface {
// contains filtered or unexported methods
}
An Option configures a Logger.
func Hooks ¶
Hooks registers functions which will be called each time the Logger writes out an Entry. Repeated use of Hooks is additive.
Hooks are useful for simple side effects, like capturing metrics for the number of emitted logs. More complex side effects, including anything that requires access to the Entry's structured fields, should be implemented as a zapcore.Core instead. See zapcore.RegisterHooks for details.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package buffer provides a thin wrapper around a byte slice.
|
Package buffer provides a thin wrapper around a byte slice. |
|
internal
|
|
|
bufferpool
Package bufferpool houses zap's shared internal buffer pool.
|
Package bufferpool houses zap's shared internal buffer pool. |
|
color
Package color adds coloring functionality for TTY output.
|
Package color adds coloring functionality for TTY output. |
|
exit
Package exit provides stubs so that unit tests can exercise code that calls os.Exit(1).
|
Package exit provides stubs so that unit tests can exercise code that calls os.Exit(1). |
|
Package zaptest provides a variety of helpers for testing log output.
|
Package zaptest provides a variety of helpers for testing log output. |
|
observer
Package observer provides a zapcore.Core that keeps an in-memory, encoding-agnostic repesentation of log entries.
|
Package observer provides a zapcore.Core that keeps an in-memory, encoding-agnostic repesentation of log entries. |