log

README

⚡ zap

Blazing fast, structured, leveled logging in Go.

Installation

go get -u go.uber.org/zap

Note that zap only supports the two most recent minor versions of Go.

Quick Start

In contexts where performance is nice, but not critical, use the SugaredLogger. It's 4-10x faster than other structured logging packages and includes both structured and printf-style APIs.

logger, _ := zap.NewProduction()
defer logger.Sync() // flushes buffer, if any
sugar := logger.Sugar()
sugar.Infow("failed to fetch URL",
  // Structured context as loosely typed key-value pairs.
  "url", url,
  "attempt", 3,
  "backoff", time.Second,
)
sugar.Infof("Failed to fetch URL: %s", url)

When performance and type safety are critical, use the Logger. It's even faster than the SugaredLogger and allocates far less, but it only supports structured logging.

logger, _ := zap.NewProduction()
defer logger.Sync()
logger.Info("failed to fetch URL",
  // Structured context as strongly typed Field values.
  zap.String("url", url),
  zap.Int("attempt", 3),
  zap.Duration("backoff", time.Second),
)

See the documentation and FAQ for more details.

Performance

For applications that log in the hot path, reflection-based serialization and string formatting are prohibitively expensive — they're CPU-intensive and make many small allocations. Put differently, using encoding/json and fmt.Fprintf to log tons of interface{}s makes your application slow.

Zap takes a different approach. It includes a reflection-free, zero-allocation JSON encoder, and the base Logger strives to avoid serialization overhead and allocations wherever possible. By building the high-level SugaredLogger on that foundation, zap lets users choose when they need to count every allocation and when they'd prefer a more familiar, loosely typed API.

As measured by its own benchmarking suite, not only is zap more performant than comparable structured logging packages — it's also faster than the standard library. Like all benchmarks, take these with a grain of salt.¹

Log a message and 10 fields:

Package	Time	Objects Allocated
⚡ zap	3131 ns/op	5 allocs/op
⚡ zap (sugared)	4173 ns/op	21 allocs/op
zerolog	16154 ns/op	90 allocs/op
lion	16341 ns/op	111 allocs/op
go-kit	17049 ns/op	126 allocs/op
logrus	23662 ns/op	142 allocs/op
log15	36351 ns/op	149 allocs/op
apex/log	42530 ns/op	126 allocs/op

Log a message with a logger that already has 10 fields of context:

Package	Time	Objects Allocated
⚡ zap	380 ns/op	0 allocs/op
⚡ zap (sugared)	564 ns/op	2 allocs/op
zerolog	321 ns/op	0 allocs/op
lion	7092 ns/op	39 allocs/op
go-kit	20226 ns/op	115 allocs/op
logrus	22312 ns/op	130 allocs/op
log15	28788 ns/op	79 allocs/op
apex/log	42063 ns/op	115 allocs/op

Log a static string, without any context or printf-style templating:

Package	Time	Objects Allocated
⚡ zap	361 ns/op	0 allocs/op
⚡ zap (sugared)	534 ns/op	2 allocs/op
zerolog	323 ns/op	0 allocs/op
standard library	575 ns/op	2 allocs/op
go-kit	922 ns/op	13 allocs/op
lion	1413 ns/op	10 allocs/op
logrus	2291 ns/op	27 allocs/op
apex/log	3690 ns/op	11 allocs/op
log15	5954 ns/op	26 allocs/op

Development Status: Stable

All APIs are finalized, and no breaking changes will be made in the 1.x series of releases. Users of semver-aware dependency management systems should pin zap to ^1.

Contributing

We encourage and support an active, healthy community of contributors — including you! Details are in the contribution guide and the code of conduct. The zap maintainers keep an eye on issues and pull requests, but you can also report any negative conduct to oss-conduct@uber.com. That email list is a private, safe space; even the zap maintainers don't have access, so don't hesitate to hold us to a high standard.

---

Released under the MIT License.

¹ In particular, keep in mind that we may be benchmarking against slightly older versions of other packages. Versions are pinned in zap's glide.lock file. ↩

Documentation

Index

• Constants
• Variables
• func ConsoleInitLogger()
• func Crit(msg string, ctx ...interface{})
• func Debug(msg string, ctx ...interface{})
• func DebugDynamic(getStr GetString)
• func Debugf(format string, ctx ...interface{})
• func Error(msg string, ctx ...interface{})
• func Errorf(format string, ctx ...interface{})
• func Info(msg string, ctx ...interface{})
• func InfoDynamic(getStr GetString)
• func Infof(msg string, ctx ...interface{})
• func InitLogger()
• func Trace(msg string, ctx ...interface{})
• func Warn(msg string, ctx ...interface{})
• func Warnf(msg string, ctx ...interface{})
• type Config
• type Ctx
• type GetString
• type NothingLogger
  • func (n *NothingLogger) Crit(msg string, ctx ...interface{})
  • func (n *NothingLogger) Debug(msg string, ctx ...interface{})
  • func (n *NothingLogger) Debugf(msg string, ctx ...interface{})
  • func (n *NothingLogger) Error(msg string, ctx ...interface{})
  • func (n *NothingLogger) Errorf(msg string, ctx ...interface{})
  • func (n *NothingLogger) Info(msg string, ctx ...interface{})
  • func (n *NothingLogger) Infof(msg string, ctx ...interface{})
  • func (n *NothingLogger) Trace(msg string, ctx ...interface{})
  • func (n *NothingLogger) Warn(msg string, ctx ...interface{})
  • func (n *NothingLogger) Warnf(msg string, ctx ...interface{})
• type RotationLogger
  • func (l *RotationLogger) Write(p []byte) (n int, err error)

Constants

const (
	RootBuild      = "build"
	RootCmd        = "cmd"
	RootCommon     = "common"
	RootConfigure  = "configure"
	RootCore       = "core"
	RootInternal   = "internal"
	RootPtnclient  = "ptnclient"
	RootPtnjson    = "ptnjson"
	RootStatistics = "statistics"
	RootVendor     = "vendor"
	RootWallet     = "wallet"

	LogStdout = "stdout"
	LogStderr = "stderr"
)

Variables

var DefaultConfig = Config{
	OutputPaths:      []string{LogStdout, "./log/all.log"},
	ErrorOutputPaths: []string{LogStderr, "./log/error.log"},

	LoggerLvl:           "DEBUG",
	Encoding:            "console",
	Development:         true,
	RotationMaxSize:     200,
	RotationMaxAge:      5,
	MaxLogMessageLength: 1024 * 1024,
}

var LogConfig = DefaultConfig

var Logger *zap.Logger

Functions

func ConsoleInitLogger

func ConsoleInitLogger()

func Crit

func Crit(msg string, ctx ...interface{})

Crit

func Debug

func Debug(msg string, ctx ...interface{})

Debug

func DebugDynamic

func DebugDynamic(getStr GetString)

func Debugf

func Debugf(format string, ctx ...interface{})

func Error

func Error(msg string, ctx ...interface{})

Error

func Errorf

func Errorf(format string, ctx ...interface{})

func Info

func Info(msg string, ctx ...interface{})

Info

func InfoDynamic

func InfoDynamic(getStr GetString)

func Infof

func Infof(msg string, ctx ...interface{})

func InitLogger

func InitLogger()

init zap.logger

func Trace

func Trace(msg string, ctx ...interface{})

Trace

func Warn

func Warn(msg string, ctx ...interface{})

Warn

func Warnf

func Warnf(msg string, ctx ...interface{})

Types

type Config

type Config struct {
	OutputPaths      []string `json:"outputPaths" yaml:"outputPaths"`           // output file path
	ErrorOutputPaths []string `json:"errorOutputPaths" yaml:"errorOutputPaths"` // error file path
	//OpenModule       []string // open module
	LoggerLvl           string `json:"level" yaml:"level"`       // log level
	Encoding            string `json:"encoding" yaml:"encoding"` // encoding
	Development         bool   `json:"development" yaml:"development"`
	RotationMaxSize     int    `json:"rotation_max_size" yaml:"rotation_max_size"`
	RotationMaxAge      int    `json:"rotation_max_age" yaml:"rotation_max_age"`
	MaxLogMessageLength int    `json:"max_log_message_length" yaml:"max_log_message_length"`
}

type Ctx

type Ctx map[string]interface{}

Ctx is a map of key/value pairs to pass as context to a log function Use this only if you really need greater safety around the arguments you pass to the logging functions.

type GetString

type GetString func() string

type NothingLogger

type NothingLogger struct{}

对于有些情况，我们只希望在开发环境的时候记录Log，而在生产环境不做任何记录

func (*NothingLogger) Crit

func (n *NothingLogger) Crit(msg string, ctx ...interface{})

func (*NothingLogger) Debug

func (n *NothingLogger) Debug(msg string, ctx ...interface{})

func (*NothingLogger) Debugf

func (n *NothingLogger) Debugf(msg string, ctx ...interface{})

func (*NothingLogger) Error

func (n *NothingLogger) Error(msg string, ctx ...interface{})

func (*NothingLogger) Errorf

func (n *NothingLogger) Errorf(msg string, ctx ...interface{})

func (*NothingLogger) Info

func (n *NothingLogger) Info(msg string, ctx ...interface{})

func (*NothingLogger) Infof

func (n *NothingLogger) Infof(msg string, ctx ...interface{})

func (*NothingLogger) Trace

func (n *NothingLogger) Trace(msg string, ctx ...interface{})

func (*NothingLogger) Warn

func (n *NothingLogger) Warn(msg string, ctx ...interface{})

func (*NothingLogger) Warnf

func (n *NothingLogger) Warnf(msg string, ctx ...interface{})

type RotationLogger

type RotationLogger struct {
	Max1LogLength int64
	Logger        *lumberjack.Logger
}

用于限制一条Log的大小

func (*RotationLogger) Write

func (l *RotationLogger) Write(p []byte) (n int, err error)