Documentation ¶
Overview ¶
Package zap provides fast, structured, leveled logging in Go.
Example ¶
package main import ( "time" "github.com/uber-go/zap" ) func main() { // Log in JSON, using zap's reflection-free JSON encoder. // The default options will log any Info or higher logs to standard out. logger := zap.New( zap.NewJSONEncoder(zap.NoTime()), // drop timestamps in tests ) logger.Warn("Log without structured data...") logger.Warn( "Or use strongly-typed wrappers to add structured context.", zap.String("library", "zap"), zap.Duration("latency", time.Nanosecond), ) // Avoid re-serializing the same data repeatedly by creating a child logger // with some attached context. That context is added to all the child's // log output, but doesn't affect the parent. child := logger.With(zap.String("user", "jane@test.com"), zap.Int("visits", 42)) child.Error("Oh no!") }
Output: {"level":"warn","msg":"Log without structured data..."} {"level":"warn","msg":"Or use strongly-typed wrappers to add structured context.","library":"zap","latency":1} {"level":"error","msg":"Oh no!","user":"jane@test.com","visits":42}
Example (FileOutput) ¶
package main import ( "fmt" "io/ioutil" "os" "github.com/uber-go/zap" ) func main() { // Create a temporary file to output logs to. f, err := ioutil.TempFile("", "log") if err != nil { panic("failed to create temporary file") } defer os.Remove(f.Name()) logger := zap.New( zap.NewJSONEncoder(zap.NoTime()), // drop timestamps in tests // Write the logging output to the specified file instead of stdout. // Any type implementing zap.WriteSyncer or zap.WriteFlusher can be used. zap.Output(f), ) logger.Info("This is an info log.", zap.Int("foo", 42)) // Sync the file so logs are written to disk, and print the file contents. // zap will call Sync automatically when logging at FatalLevel or PanicLevel. f.Sync() contents, err := ioutil.ReadFile(f.Name()) if err != nil { panic("failed to read temporary file") } fmt.Println(string(contents)) }
Output: {"level":"info","msg":"This is an info log.","foo":42}
Index ¶
- Variables
- func NewHTTPHandler(logger Logger) http.Handler
- type CheckedMessage
- type Encoder
- type Entry
- type Field
- func Base64(key string, val []byte) Field
- func Bool(key string, val bool) Field
- func Duration(key string, val time.Duration) Field
- func Error(err error) Field
- func Float64(key string, val float64) Field
- func Int(key string, val int) Field
- func Int64(key string, val int64) Field
- func Marshaler(key string, val LogMarshaler) Field
- func Nest(key string, fields ...Field) Field
- func Object(key string, val interface{}) Field
- func Skip() Field
- func Stack() Field
- func String(key string, val string) Field
- func Stringer(key string, val fmt.Stringer) Field
- func Time(key string, val time.Time) Field
- func Uint(key string, val uint) Field
- func Uint64(key string, val uint64) Field
- type Hook
- type JSONOption
- type KeyValue
- type Level
- type LevelFormatter
- type LogMarshaler
- type LogMarshalerFunc
- type Logger
- type MessageFormatter
- type Meta
- type Option
- type TimeFormatter
- type WriteFlusher
- type WriteSyncer
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var Discard = AddSync(ioutil.Discard)
Discard is a convenience wrapper around ioutil.Discard.
Functions ¶
func NewHTTPHandler ¶
NewHTTPHandler returns an HTTP handler that can change the logging level at runtime.
GET requests return a JSON description of the current logging level. PUT requests change the logging level and expect a payload like
{"level":"info"}
Types ¶
type CheckedMessage ¶
type CheckedMessage struct {
// contains filtered or unexported fields
}
A CheckedMessage is the result of a call to Logger.Check, which allows especially performance-sensitive applications to avoid allocations for disabled or heavily sampled log levels.
Example ¶
package main import ( "github.com/uber-go/zap" ) func main() { logger := zap.New( zap.NewJSONEncoder(zap.NoTime()), // drop timestamps in tests ) // By default, the debug logging level is disabled. However, calls to // logger.Debug will still allocate a slice to hold any passed fields. // Particularly performance-sensitive applications can avoid paying this // penalty by using checked messages. if cm := logger.Check(zap.DebugLevel, "This is a debug log."); cm.OK() { // Debug-level logging is disabled, so we won't get here. cm.Write(zap.Int("foo", 42), zap.Stack()) } if cm := logger.Check(zap.InfoLevel, "This is an info log."); cm.OK() { // Since info-level logging is enabled, we expect to write out this message. cm.Write() } }
Output: {"level":"info","msg":"This is an info log."}
func NewCheckedMessage ¶
func NewCheckedMessage(logger Logger, lvl Level, msg string) *CheckedMessage
NewCheckedMessage constructs a CheckedMessage. It's only intended for use by wrapper libraries, and shouldn't be necessary in application code.
func (*CheckedMessage) OK ¶
func (m *CheckedMessage) OK() bool
OK checks whether it's safe to call Write.
func (*CheckedMessage) Write ¶
func (m *CheckedMessage) Write(fields ...Field)
Write logs the pre-checked message with the supplied fields. It should only be used once; if a CheckedMessage is re-used, it also logs an error message with the underlying logger's DFatal method.
type Encoder ¶
type Encoder interface { KeyValue Clone() Encoder Free() WriteEntry(io.Writer, string, Level, time.Time) error }
Encoder is a format-agnostic interface for all log field encoders. It's not safe for concurrent use.
func NewJSONEncoder ¶
func NewJSONEncoder(options ...JSONOption) Encoder
NewJSONEncoder creates a logging-optimized JSON encoder. By default, JSON encoders put the log message under the "msg" key, the timestamp (as floating-point seconds since epoch) under the "ts" key, and the log level under the "level" key.
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 it's the user's responsibility to avoid duplicate keys.
Example ¶
package main import ( "github.com/uber-go/zap" ) func main() { // An encoder with the default settings. zap.NewJSONEncoder() // Dropping timestamps is often useful in tests. zap.NewJSONEncoder(zap.NoTime()) // In production, customize the encoder to work with your log aggregation // system. zap.NewJSONEncoder( zap.RFC3339Formatter("@timestamp"), // human-readable timestamps zap.MessageKey("@message"), // customize the message key zap.LevelString("@level"), // stringify the log level ) }
Output:
type Entry ¶
type Entry struct { Level Level Time time.Time Message string // contains filtered or unexported fields }
An Entry represents a complete log message. The entry's structured context is already serialized, but the log level, time, and message are available for inspection and modification.
Entries are pooled, so any functions that accept them must be careful not to retain references to them.
type Field ¶
type Field struct {
// contains filtered or unexported fields
}
A Field is a deferred marshaling operation used to add a key-value pair to a logger's context. Keys and values are appropriately escaped for the current encoding scheme (e.g., JSON).
func Base64 ¶
Base64 constructs a field that encodes the given value as a padded base64 string. The byte slice is converted to a base64 string immediately.
func Duration ¶
Duration constructs a Field with the given key and value. It represents durations as an integer number of nanoseconds.
func Error ¶
Error constructs a Field that stores err.Error() under the key "error". This is just a convenient shortcut for a common pattern - apart from saving a few keystrokes, it's no different from using zap.String.
func Float64 ¶
Float64 constructs a Field with the given key and value. The way the floating-point value is represented is encoder-dependent.
func Marshaler ¶
func Marshaler(key string, val LogMarshaler) Field
Marshaler constructs a field with the given key and zap.LogMarshaler. It provides a flexible, but still type-safe and efficient, way to add user-defined types to the logging context.
Example ¶
package main import ( "time" "github.com/uber-go/zap" ) type Auth struct { ExpiresAt time.Time `json:"expires_at"` // Since we'll need to send the token to the browser, we include it in the // struct's JSON representation. Token string `json:"token"` } func (a Auth) MarshalLog(kv zap.KeyValue) error { kv.AddInt64("expires_at", a.ExpiresAt.UnixNano()) // We don't want to log sensitive data. kv.AddString("token", "---") return nil } type User struct { Name string `json:"name"` Age int `json:"age"` Auth Auth `auth:"auth"` } func (u User) MarshalLog(kv zap.KeyValue) error { kv.AddString("name", u.Name) kv.AddInt("age", u.Age) return kv.AddMarshaler("auth", u.Auth) } func main() { jane := User{ Name: "Jane Doe", Age: 42, Auth: Auth{ ExpiresAt: time.Unix(0, 100), Token: "super secret", }, } logger := zap.New(zap.NewJSONEncoder(zap.NoTime())) logger.Info("Successful login.", zap.Marshaler("user", jane)) }
Output: {"level":"info","msg":"Successful login.","user":{"name":"Jane Doe","age":42,"auth":{"expires_at":100,"token":"---"}}}
func Nest ¶
Nest takes a key and a variadic number of Fields and creates a nested namespace.
Example ¶
package main import ( "github.com/uber-go/zap" ) func main() { logger := zap.New( zap.NewJSONEncoder(zap.NoTime()), // drop timestamps in tests ) // We'd like the logging context to be {"outer":{"inner":42}} nest := zap.Nest("outer", zap.Int("inner", 42)) logger.Info("Logging a nested field.", nest) }
Output: {"level":"info","msg":"Logging a nested field.","outer":{"inner":42}}
func Object ¶
Object constructs a field with the given key and an arbitrary object. It uses an encoding-appropriate, reflection-based function to serialize nearly any object into the logging context, but it's relatively slow and allocation-heavy.
If encoding fails (e.g., trying to serialize a map[int]string to JSON), Object includes the error message in the final log output.
func Stack ¶
func Stack() Field
Stack constructs a Field that stores a stacktrace of the current goroutine under the key "stacktrace". Keep in mind that taking a stacktrace is extremely expensive (relatively speaking); this function both makes an allocation and takes ~10 microseconds.
func Stringer ¶
Stringer constructs a Field with the given key and value. The value is the result of the String method.
func Time ¶
Time constructs a Field with the given key and value. It represents a time.Time as a floating-point number of seconds since epoch.
type Hook ¶
A Hook is executed each time the logger writes an Entry. It can modify the entry, but must not retain references to the entry or any of its contents. Returned errors are written to the logger's error output.
Hooks implement the Option interface.
type JSONOption ¶
type JSONOption interface {
// contains filtered or unexported methods
}
JSONOption is used to set options for a JSON encoder.
type KeyValue ¶
type KeyValue interface { AddBool(key string, value bool) AddFloat64(key string, value float64) AddInt(key string, value int) AddInt64(key string, value int64) AddUint(key string, value uint) AddUint64(key string, value uint64) AddMarshaler(key string, marshaler LogMarshaler) error // AddObject uses reflection to serialize arbitrary objects, so it's slow and // allocation-heavy. Consider implementing the LogMarshaler interface instead. AddObject(key string, value interface{}) error AddString(key, value string) }
KeyValue is an encoding-agnostic interface to add structured data to the logging context. Like maps, KeyValues aren't safe for concurrent use (though typical use shouldn't require locks).
See Marshaler for an example.
type Level ¶
type Level int32
A Level is a logging priority. Higher levels are more important.
Note that Level satisfies the Option interface, so any Level can be passed to NewJSON to override the default logging priority.
const ( // DebugLevel logs are typically voluminous, and are usually disabled in // production. DebugLevel Level = iota - 1 // InfoLevel is the default logging priority. InfoLevel // WarnLevel logs are more important than Info, but don't need individual // human review. WarnLevel // ErrorLevel logs are high-priority. If an application is running smoothly, // it shouldn't generate any error-level logs. ErrorLevel // PanicLevel logs a message, then panics. PanicLevel // FatalLevel logs a message, then calls os.Exit(1). FatalLevel )
func LevelFlag ¶
LevelFlag defines a Level flag with specified name, default value and usage string. The return value is the address of a Level value that stores the value of the flag.
func (*Level) MarshalText ¶
MarshalText marshals the Level to text. Note that the text representation drops the -Level suffix (see example).
Example ¶
package main import ( "encoding/json" "fmt" "github.com/uber-go/zap" ) func main() { level := zap.ErrorLevel s := struct { Level *zap.Level `json:"level"` }{&level} bytes, _ := json.Marshal(s) fmt.Println(string(bytes)) }
Output: {"level":"error"}
func (*Level) UnmarshalText ¶
UnmarshalText unmarshals text to a level. Like MarshalText, UnmarshalText expects the text representation of a Level to drop the -Level suffix (see example).
In particular, this makes it easy to configure logging levels using YAML, TOML, or JSON files.
Example ¶
package main import ( "encoding/json" "fmt" "github.com/uber-go/zap" ) func main() { var s struct { Level zap.Level `json:"level"` } // The zero value for a zap.Level is zap.InfoLevel. fmt.Println(s.Level) json.Unmarshal([]byte(`{"level":"error"}`), &s) fmt.Println(s.Level) }
Output: info error
type LevelFormatter ¶
A LevelFormatter defines how to convert an entry's logging level into a Field.
func LevelString ¶
func LevelString(key string) LevelFormatter
LevelString encodes the entry's level under the provided key. It uses the level's String method to serialize it.
type LogMarshaler ¶
LogMarshaler 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 LogMarshalerFunc ¶
LogMarshalerFunc is a type adapter that allows using a function as a LogMarshaler.
func (LogMarshalerFunc) MarshalLog ¶
func (f LogMarshalerFunc) MarshalLog(kv KeyValue) error
MarshalLog calls the underlying function.
type Logger ¶
type Logger interface { // Check the minimum enabled log level. Level() Level // Change the level of this logger, as well as all its ancestors and // descendants. This makes it easy to change the log level at runtime // without restarting your application. SetLevel(Level) // Create a child logger, and optionally add some context to that logger. With(...Field) Logger // Check returns a CheckedMessage 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. // // See CheckedMessage for an example. Check(Level, string) *CheckedMessage // Log a message at the given level. Messages include any context that's // accumulated on the logger, as well as any fields added at the log site. Log(Level, string, ...Field) Debug(string, ...Field) Info(string, ...Field) Warn(string, ...Field) Error(string, ...Field) Panic(string, ...Field) Fatal(string, ...Field) // If the logger is in development mode (via the Development option), DFatal // logs at the Fatal level. Otherwise, it logs at the Error level. DFatal(string, ...Field) }
A Logger enables leveled, structured logging. All methods are safe for concurrent use.
func New ¶
New constructs a logger that uses the provided encoder. By default, the logger will write Info logs or higher to standard out. Any errors during logging will be written to standard error.
Options can change the log level, the output location, the initial fields that should be added as context, and many other behaviors.
Example ¶
package main import ( "github.com/uber-go/zap" ) func main() { // The default logger outputs to standard out and only writes logs that are // Info level or higher. logger := zap.New( zap.NewJSONEncoder(zap.NoTime()), // drop timestamps in tests ) // The default logger does not print Debug logs. logger.Debug("This won't be printed.") logger.Info("This is an info log.") }
Output: {"level":"info","msg":"This is an info log."}
Example (Options) ¶
package main import ( "github.com/uber-go/zap" ) func main() { // We can pass multiple options to the NewJSON method to configure // the logging level, output location, or even the initial context. logger := zap.New( zap.NewJSONEncoder(zap.NoTime()), // drop timestamps in tests zap.DebugLevel, zap.Fields(zap.Int("count", 1)), ) logger.Debug("This is a debug log.") logger.Info("This is an info log.") }
Output: {"level":"debug","msg":"This is a debug log.","count":1} {"level":"info","msg":"This is an info log.","count":1}
type MessageFormatter ¶
A MessageFormatter defines how to convert a log message into a Field.
func MessageKey ¶
func MessageKey(key string) MessageFormatter
MessageKey encodes log messages under the provided key.
type Meta ¶
type Meta struct { Development bool Encoder Encoder Hooks []Hook Output WriteSyncer ErrorOutput WriteSyncer // contains filtered or unexported fields }
Meta is implementation-agnostic state management for Loggers. Most Logger implementations can reduce the required boilerplate by embedding a Meta.
Note that while the level-related fields and methods are safe for concurrent use, the remaining fields are not.
func MakeMeta ¶
MakeMeta returns a new meta struct with sensible defaults: logging at InfoLevel, a JSON encoder, development mode off, and writing to standard error and standard out.
func (Meta) Clone ¶
Clone creates a copy of the meta struct. It deep-copies the encoder, but not the hooks (since they rarely change).
type Option ¶
type Option interface {
// contains filtered or unexported methods
}
Option is used to set options for the logger.
func AddCaller ¶
func AddCaller() Option
AddCaller configures the Logger to annotate each message with the filename and line number of zap's caller.
func AddStacks ¶
AddStacks configures the Logger to record a stack trace for all messages at or above a given level. Keep in mind that this is (relatively speaking) quite expensive.
func Development ¶
func Development() Option
Development puts the logger in development mode, which alters the behavior of the DFatal method.
func ErrorOutput ¶
func ErrorOutput(w WriteSyncer) Option
ErrorOutput sets the destination for errors generated by the logger.
func Output ¶
func Output(w WriteSyncer) Option
Output sets the destination for the logger's output.
type TimeFormatter ¶
A TimeFormatter defines how to convert the time of a log entry into a Field.
func EpochFormatter ¶
func EpochFormatter(key string) TimeFormatter
EpochFormatter uses the Time field (floating-point seconds since epoch) to encode the entry time under the provided key.
func NoTime ¶
func NoTime() TimeFormatter
NoTime drops the entry time altogether. It's often useful in testing, since it removes the need to stub time.Now.
func RFC3339Formatter ¶
func RFC3339Formatter(key string) TimeFormatter
RFC3339Formatter encodes the entry time as an RFC3339-formatted string under the provided key.
type WriteFlusher ¶
A WriteFlusher is an io.Writer that can also flush any buffered data.
type WriteSyncer ¶
A WriteSyncer is an io.Writer that can also flush any buffered data. Note that *os.File (and thus, os.Stderr and os.Stdout) implement WriteSyncer.
func AddSync ¶
func AddSync(w io.Writer) WriteSyncer
AddSync converts an io.Writer to a WriteSyncer. It attempts to be intelligent: if the concrete type of the io.Writer implements WriteSyncer or WriteFlusher, we'll use the existing Sync or Flush methods. If it doesn't, we'll add a no-op Sync method.
Source Files ¶
Directories ¶
Path | Synopsis |
---|---|
Package spy provides an implementation of zap.Logger that helps test logging wrappers.
|
Package spy provides an implementation of zap.Logger that helps test logging wrappers. |
Package spywrite provides various I/O implementations with known errors.
|
Package spywrite provides various I/O implementations with known errors. |
Package testutils provides some simple testing helpers (most of which aren't specifically logging-related).
|
Package testutils provides some simple testing helpers (most of which aren't specifically logging-related). |
Package zbark provides a wrapper to make zap.Loggers compatible with the bark.Logger interface.
|
Package zbark provides a wrapper to make zap.Loggers compatible with the bark.Logger interface. |
Package zwrap provides a variety of wrappers for the core zap logger.
|
Package zwrap provides a variety of wrappers for the core zap logger. |