log

README

log package

Currently, this documentation is unfinished, so you may need to read the source code before use.

Flags

The log package comes with following flags auto registered by default.

• log.level
• log.format

HINT You can disable the auto-register feature by passing commonlog_noautoinit to your build tags.

log.level

Only log messages with the given severity or above. Valid levels:

• debug
• info
• warn
• error
• fatal

log.format

The log.format have a common format (optional parts marked by squared brackets):

logger:<encoder>[?param=value[&param2=value2]]

A full example:

logger:json?outputPaths=/var/log/test.log&disableCaller=false&disableStacktrace=false

Encoders

Currently, only two encoders are supported:

1. JSON (Default)
2. Console

Parameters

• development
• disableCaller
• disableStacktrace
• outputPaths
• lumberjack

Documentation

Overview

Package log provides logging wrapper around zap (https://github.com/uber-go/zap), the amazing logging library for Go.

Index

• Constants
• func AddFlags(fs *flag.FlagSet) error
• func AddKingpinFlags(a *kingpin.Application)
• func DPanic(msg string, fields ...zapcore.Field)
• func Debug(msg string, fields ...zapcore.Field)
• func Error(msg string, fields ...zapcore.Field)
• func Fatal(msg string, fields ...zapcore.Field)
• func Info(msg string, fields ...zapcore.Field)
• func L() *zap.Logger
• func Panic(msg string, fields ...zapcore.Field)
• func ReplaceGlobals(logger *zap.Logger) func()
• func S() *zap.SugaredLogger
• func Warn(msg string, fields ...zapcore.Field)
• type Config
  • func ParseConfigFromURI(u *url.URL) (*Config, error)
  • func ParseConfigFromURIString(uri string) (*Config, error)
  • func (cfg Config) Build(opts ...zap.Option) (*zap.Logger, error)
• type EncoderType
• type LumberjackConfig
  • func ParseLumberjacks(vs ...string) ([]LumberjackConfig, error)

Constants

const (
	// DefaultLumberjackMaxSize is the default maximum size in megabytes of the
	// log file before it gets rotated.
	DefaultLumberjackMaxSize = 100
	// DefaultLumberjackMaxBackups is the maximum number of old log files to retain.  The default
	// is to retain all old log files (though MaxAge may still cause them to get
	// deleted.)
	DefaultLumberjackMaxBackups = 50
)

Functions

func AddFlags

func AddFlags(fs *flag.FlagSet) error

AddFlags adds the flags used by this package to the given FlagSet. That's useful if working with a custom FlagSet. The init function of this package adds the flags to flag.CommandLine anyway. Thus, it's usually enough to call flag.Parse() to make the logging flags take effect.

func AddKingpinFlags

func AddKingpinFlags(a *kingpin.Application)

AddKingpinFlags adds the flags used by this package to the Kingpin application. To use the default Kingpin application, call AddFlags(kingpin.CommandLine)

func DPanic

func DPanic(msg string, fields ...zapcore.Field)

DPanic logs a message at DPanicLevel. The message includes any fields passed at the log site, as well as any fields accumulated on the logger.

If the logger is in development mode, it then panics (DPanic means "development panic"). This is useful for catching errors that are recoverable, but shouldn't ever happen.

func Debug

func Debug(msg string, fields ...zapcore.Field)

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 Error

func Error(msg string, fields ...zapcore.Field)

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 Fatal

func Fatal(msg string, fields ...zapcore.Field)

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 Info

func Info(msg string, fields ...zapcore.Field)

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 L

func L() *zap.Logger

L returns the global zap.Logger.

It's safe for concurrent use.

func Panic

func Panic(msg string, fields ...zapcore.Field)

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 ReplaceGlobals

func ReplaceGlobals(logger *zap.Logger) func()

ReplaceGlobals replaces the global zap.Logger and the zap.SugaredLogger, and returns a function to restore the original values.

It's safe for concurrent use.

func S

func S() *zap.SugaredLogger

S returns the global zap.SugaredLogger. ReplaceGlobals.

It's safe for concurrent use.

func Warn

func Warn(msg string, fields ...zapcore.Field)

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.

Types

type Config

type Config struct {
	EncoderType EncoderType `json:"encoderType" yaml:"encoderType"`
	// 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 zap.AtomicLevel `json:"level" yaml:"level"`
	// Development puts the logger in development mode, which changes the
	// behavior of DPanicLevel and takes stacktraces more liberally.
	Development bool `json:"development" yaml:"development"`
	// DisableCaller stops annotating logs with the calling function's file
	// name and line number. By default, all logs are annotated.
	DisableCaller bool `json:"disableCaller" yaml:"disableCaller"`
	// DisableStacktrace completely disables automatic stacktrace capturing. By
	// default, stacktraces are captured for WarnLevel and above logs in
	// development and ErrorLevel and above in production.
	DisableStacktrace bool     `json:"disableStacktrace" yaml:"disableStacktrace"`
	OutputPaths       []string `json:"outputPaths" yaml:"outputPaths"`
	// ErrorOutputPaths is a list of paths to write internal logger errors to.
	// The default is standard error.
	//
	// Note that this setting only affects internal errors; for sample code that
	// sends error-level logs to a different location from info- and debug-level
	// logs, see the package-level AdvancedConfiguration example.
	ErrorOutputPaths []string           `json:"errorOutputPaths" yaml:"errorOutputPaths"`
	Lumberjacks      []LumberjackConfig `json:"lumberjacks" json:"lumberjacks"`
	ErrorLumberjacks []LumberjackConfig `json:"errorLumberjacks" json:"errorLumberjacks"`

	OutputAddresses []string `json:"outputAddresses" yaml:"outputAddresses"`
	// Syslog related config
	Framing  zapsyslog.Framing `json:"framing" yaml:"framing"`
	Facility syslog.Priority   `json:"facility" yaml:"facility"`
	Hostname string            `json:"hostname" yaml:"hostname"`
	PID      int               `json:"pid" yaml:"pid"`
	App      string            `json:"app" yaml:"app"`
	// contains filtered or unexported fields
}

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.

func ParseConfigFromURI

func ParseConfigFromURI(u *url.URL) (*Config, error)

ParseConfigFromURI parses config from a config uri.

func ParseConfigFromURIString

func ParseConfigFromURIString(uri string) (*Config, error)

ParseConfigFromURIString parses config from a config uri string.

func (Config) Build

func (cfg Config) Build(opts ...zap.Option) (*zap.Logger, error)

Build builds options into zap.Logger.

type EncoderType

type EncoderType int

EncoderType represents encoder type.

const (
	// JSONEncoder represents a json encoder type.
	JSONEncoder EncoderType = iota
	// ConsoleEncoder represents a console encoder type, which is mainly for human friendly output.
	ConsoleEncoder
	// SyslogEncoder represents a Syslog (RFC5425) encoder type.
	SyslogEncoder
)

type LumberjackConfig

type LumberjackConfig struct {
	// Filename is the file to write logs to.  Backup log files will be retained
	// in the same directory.  It uses <processname>-lumberjack.log in
	// os.TempDir() if empty.
	Filename string `json:"filename" yaml:"filename"`
	// MaxSize is the maximum size in megabytes of the log file before it gets
	// rotated. It defaults to 100 megabytes.
	MaxSize int `json:"maxsize" yaml:"maxsize"`
	// MaxAge is the maximum number of days to retain old log files based on the
	// timestamp encoded in their filename.  Note that a day is defined as 24
	// hours and may not exactly correspond to calendar days due to daylight
	// savings, leap seconds, etc. The default is not to remove old log files
	// based on age.
	MaxAge int `json:"maxage" yaml:"maxage"`
	// MaxBackups is the maximum number of old log files to retain.  The default
	// is to retain all old log files (though MaxAge may still cause them to get
	// deleted.)
	MaxBackups int `json:"maxbackups" yaml:"maxbackups"`
	// LocalTime determines if the time used for formatting the timestamps in
	// backup files is the computer's local time.  The default is to use UTC
	// time.
	LocalTime bool `json:"localtime" yaml:"localtime"`
	// Compress determines if the rotated log files should be compressed
	// using gzip.
	Compress bool `json:"compress" yaml:"compress"`
}

LumberjackConfig offers a declarative way to construct a lumberjack Logger with rolling.

func ParseLumberjacks

func ParseLumberjacks(vs ...string) ([]LumberjackConfig, error)

ParseLumberjacks parses lumberjack config values into LumberjackConfig slice.