README
¶
Logging framework for Go
This is a logging framework mainly for our Go products.
Be warned that this is a framework rather than a library. Most features cannot be configured.
Features
-
Light-weight.
Hard-coded maximum log buffer size and 1-pass formatters help cybozu-go/log be memory- and CPU- efficient.
Benchmark results show that it can format about 340K logs per second in JSON.
-
Built-in logfmt and JSON Lines formatters.
By default, logs are formatted in syslog-like plain text. logfmt and JSON Lines formatters can be used alternatively.
-
Automatic redirect for Go standard logs.
The framework automatically redirects Go standard logs to itself.
-
Reopen handler.
The framework comes with a handy writer that reopens the log file upon signal reception. Useful for work with log rotating programs.
Only for non-Windows systems.
Usage
Read the documentation.
Log structure
Read SPEC.md.
Documentation
¶
Overview ¶
Package log provides the standard logging framework for cybozu products.
As this is a framework rather than a library, most features are hard-coded and non-customizable.
cybozu/log is a structured logger, that is, every log entry consists of mandatory and optional fields. Mandatory fields are:
"topic" is by default the executables file name w/o directory path. "logged_at" is generated automatically by the framework. "severity" corresponds to each logging method such as "log.Error". "utsname" is generated automatically by the framework. "message" is provided by the argument for logging methods.
To help development, logs go to standard error by default. This can be changed to any io.Writer. Logs are formatted by a Formatter. Following built-in formatters are available.
Plain (default): syslog like text formatter. logfmt: https://gist.github.com/kr/0e8d5ee4b954ce604bb2 JSON Lines: https://jsonlines.org/
The standard field names are defined as constants in this package. For example, "secret" is defined as FnSecret.
Field data can be any type though following types are recommended:
nil,
bool,
time.Time (formatted in RFC3339),
string and slice of strings,
int, int8, int16, int32, int64, and slice of them,
uint, uint8, uint16, uint32, uint64, and slice of them,
float32, float64, and slice of them,
map[string]interface{} where values are one of the above types.
The framework automatically redirects Go's standard log output to the default logger provided by this framework.
Index ¶
- Constants
- Variables
- func Critical(msg string, fields map[string]interface{}) error
- func Debug(msg string, fields map[string]interface{}) error
- func Enabled(level int) bool
- func Error(msg string, fields map[string]interface{}) error
- func ErrorExit(err error)
- func Info(msg string, fields map[string]interface{}) error
- func IsValidKey(key string) bool
- func LevelName(level int) string
- func NewFileReopener(filename string, sig ...os.Signal) (io.Writer, error)
- func NewReopenWriter(opener Opener, sig ...os.Signal) (io.Writer, error)
- func ReservedKey(k string) bool
- func Warn(msg string, fields map[string]interface{}) error
- type Formatter
- type JSONFormat
- type Logfmt
- type Logger
- func (l *Logger) Critical(msg string, fields map[string]interface{}) error
- func (l *Logger) Debug(msg string, fields map[string]interface{}) error
- func (l *Logger) Defaults() map[string]interface{}
- func (l *Logger) Enabled(level int) bool
- func (l *Logger) Error(msg string, fields map[string]interface{}) error
- func (l *Logger) Formatter() Formatter
- func (l *Logger) Info(msg string, fields map[string]interface{}) error
- func (l *Logger) Log(severity int, msg string, fields map[string]interface{}) error
- func (l *Logger) SetDefaults(d map[string]interface{}) error
- func (l *Logger) SetErrorHandler(h func(error) error)
- func (l *Logger) SetFormatter(f Formatter)
- func (l *Logger) SetOutput(w io.Writer)
- func (l *Logger) SetThreshold(level int)
- func (l *Logger) SetThresholdByName(n string) error
- func (l *Logger) SetTopic(topic string)
- func (l *Logger) Threshold() int
- func (l *Logger) Topic() string
- func (l *Logger) Warn(msg string, fields map[string]interface{}) error
- func (l *Logger) WriteThrough(data []byte) error
- func (l *Logger) Writer(severity int) io.Writer
- type MsgPack
- type Opener
- type PlainFormat
Constants ¶
const ( FnTopic = "topic" FnLoggedAt = "logged_at" FnSeverity = "severity" FnUtsname = "utsname" FnMessage = "message" FnSecret = "secret" FnType = "type" FnRequestID = "request_id" FnResponseTime = "response_time" FnRemoteAddress = "remote_ipaddr" FnURL = "url" FnProtocol = "protocol" FnHTTPMethod = "http_method" FnHTTPVersion = "http_version" FnHTTPHost = "http_host" FnHTTPStatusCode = "http_status_code" FnHTTPReferer = "http_referer" FnHTTPUserAgent = "http_user_agent" FnRequestSize = "request_size" FnResponseSize = "response_size" FnDomain = "domain" FnService = "service" FnTrackingCookie = "tracking_cookie" FnBrowser = "browser" FnServiceSet = "serviceset" FnStartAt = "start_at" FnError = "error" )
Standard log field names.
const ( LvCritical = 2 LvError = 3 LvWarn = 4 LvInfo = 6 LvDebug = 7 )
Severities a.k.a log levels.
const ( // EnvLogLevel ks the environment variable name to configure // the default logger's log level at program startup. EnvLogLevel = "CYBOZU_LOG_LEVEL" )
const (
// RFC3339Micro is for time.Time.Format().
RFC3339Micro = "2006-01-02T15:04:05.000000Z07:00"
)
Variables ¶
var ( // ErrTooLarge is returned for too large log. ErrTooLarge = errors.New("too large log") // ErrInvalidKey is returned when fields contain invalid key. ErrInvalidKey = errors.New("invalid key") // ErrInvalidData is returned when fields contain invalid data. ErrInvalidData = errors.New("invalid data type") )
Functions ¶
func ErrorExit ¶
func ErrorExit(err error)
ErrorExit outputs an error log using the default logger, then exit.
func IsValidKey ¶
IsValidKey returns true if given key is valid for extra fields.
func LevelName ¶
LevelName returns the name for the defined threshold. An empty string is returned for undefined thresholds.
func NewFileReopener ¶
NewFileReopener returns io.Writer that will reopen the named file when signals are received.
func NewReopenWriter ¶
NewReopenWriter constructs a io.Writer that reopens inner io.WriteCloser when signals are received.
func ReservedKey ¶
ReservedKey returns true if k is a field name reserved for log formatters.
Types ¶
type Formatter ¶
type Formatter interface {
// Format appends formatted log data into buf.
//
// buf will be a zero-length byte slice with a certain capacity to
// store formatted log data. If the capacity of buf is not sufficient,
// Format should return (nil, ErrTooLarge).
//
// Format should return (nil, ErrInvalidKey) if a key in fields is
// not valid in the sense of IsValidKey().
//
// Implementations can assume enough capacity in buf to store
// mandatory fields except for msg (and optional fields).
Format(buf []byte, l *Logger, t time.Time, severity int,
msg string, fields map[string]interface{}) ([]byte, error)
// String returns the formatter name.
String() string
}
Formatter is the interface for log formatters.
type JSONFormat ¶
type JSONFormat struct {
// Utsname can normally be left blank.
// If not empty, the string is used instead of the hostname.
// Utsname must match this regexp: ^[a-z][a-z0-9-]*$
Utsname string
}
JSONFormat implements Formatter for JSON Lines.
type Logfmt ¶
type Logfmt struct {
// Utsname can normally be left blank.
// If not empty, the string is used instead of the hostname.
// Utsname must match this regexp: ^[a-z][a-z0-9-]*$
Utsname string
}
Logfmt implements Formatter for logfmt format.
https://brandur.org/logfmt https://gist.github.com/kr/0e8d5ee4b954ce604bb2
type Logger ¶
type Logger struct {
// contains filtered or unexported fields
}
Logger is a collection of properties how to output logs. Properties are initially set by NewLogger. They can be customized later by Logger methods.
func DefaultLogger ¶
func DefaultLogger() *Logger
DefaultLogger returns the pointer to the default logger.
func NewLogger ¶
func NewLogger() *Logger
NewLogger constructs a new Logger struct.
Attributes are initialized as follows:
Topic: path.Base(os.Args[0]) Threshold: LvInfo Formatter: PlainFormat Output: os.Stderr Defaults: nil ErrorHandler: os.Exit(5) on EPIPE.
func (*Logger) Enabled ¶
Enabled returns true if the log for the given level will be logged. This can be used to avoid futile computation for logs being ignored.
if log.Enabled(log.LvDebug) {
log.Debug("message", map[string]interface{}{
"debug info": "...",
})
}
func (*Logger) SetDefaults ¶
SetDefaults sets default field values for the logger. Setting nil effectively clear the defaults.
func (*Logger) SetErrorHandler ¶ added in v1.4.0
SetErrorHandler sets error handler.
The handler will be called if the underlying Writer's Write returns non-nil error. If h is nil, no handler will be called.
func (*Logger) SetFormatter ¶
SetFormatter sets log formatter.
func (*Logger) SetOutput ¶
SetOutput sets io.Writer for log output. Setting nil disables log output.
func (*Logger) SetThreshold ¶
SetThreshold sets the threshold for the logger. level must be a pre-defined constant such as LvInfo.
func (*Logger) SetThresholdByName ¶
SetThresholdByName sets the threshold for the logger by the level name.
func (*Logger) SetTopic ¶
SetTopic sets a new topic for the logger. topic must not be empty. Too long topic may be shortened automatically.
func (*Logger) WriteThrough ¶ added in v1.2.0
WriteThrough writes data through to the underlying writer.
type MsgPack ¶
type MsgPack struct {
// Utsname can normally be left blank.
// If not empty, the string is used instead of the hostname.
// Utsname must match this regexp: ^[a-z][a-z0-9-]*$
Utsname string
}
MsgPack implements Formatter for msgpack format.
type Opener ¶
type Opener interface {
Open() (io.WriteCloser, error)
}
Opener returns a new io.WriteCloser.
type PlainFormat ¶
type PlainFormat struct {
// Utsname can normally be left blank.
// If not empty, the string is used instead of the hostname.
// Utsname must match this regexp: ^[a-z][a-z0-9-]*$
Utsname string
}
PlainFormat implements Formatter to generate plain log messages.
A plain log message looks like: DATETIME SEVERITY UTSNAME TOPIC MESSAGE [OPTIONAL FIELDS...]
Source Files
Directories