log: github.com/cybozu-go/log Index | Files | Directories

package log

import "github.com/cybozu-go/log"

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:      http://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

Package Files

constants.go default.go doc.go err.go error_handler.go fluentd.go formatter.go json.go level.go logfmt.go logger.go msgpack.go plain.go reopen.go

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")
)

func Critical Uses

func Critical(msg string, fields map[string]interface{}) error

Critical outputs a critical log using the default logger. fields can be nil.

func Debug Uses

func Debug(msg string, fields map[string]interface{}) error

Debug outputs a debug log using the default logger. fields can be nil.

func Enabled Uses

func Enabled(level int) bool

Enabled does the same for Logger.Enabled() for the default logger.

func Error Uses

func Error(msg string, fields map[string]interface{}) error

Error outputs an error log using the default logger. fields can be nil.

func ErrorExit Uses

func ErrorExit(err error)

ErrorExit outputs an error log using the default logger, then exit.

func Info Uses

func Info(msg string, fields map[string]interface{}) error

Info outputs an informational log using the default logger. fields can be nil.

func IsValidKey Uses

func IsValidKey(key string) bool

IsValidKey returns true if given key is valid for extra fields.

func LevelName Uses

func LevelName(level int) string

LevelName returns the name for the defined threshold. An empty string is returned for undefined thresholds.

func NewFileReopener Uses

func NewFileReopener(filename string, sig ...os.Signal) (io.Writer, error)

NewFileReopener returns io.Writer that will reopen the named file when signals are received.

func NewReopenWriter Uses

func NewReopenWriter(opener Opener, sig ...os.Signal) (io.Writer, error)

NewReopenWriter constructs a io.Writer that reopens inner io.WriteCloser when signals are received.

func ReservedKey Uses

func ReservedKey(k string) bool

ReservedKey returns true if k is a field name reserved for log formatters.

func Warn Uses

func Warn(msg string, fields map[string]interface{}) error

Warn outputs a warning log using the default logger. fields can be nil.

type Formatter Uses

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 Uses

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.

http://jsonlines.org/

func (JSONFormat) Format Uses

func (f JSONFormat) Format(buf []byte, l *Logger, t time.Time, severity int,
    msg string, fields map[string]interface{}) ([]byte, error)

Format implements Formatter.Format.

func (JSONFormat) String Uses

func (f JSONFormat) String() string

String returns "json".

type Logfmt Uses

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

func (Logfmt) Format Uses

func (f Logfmt) Format(buf []byte, l *Logger, t time.Time, severity int,
    msg string, fields map[string]interface{}) ([]byte, error)

Format implements Formatter.Format.

func (Logfmt) String Uses

func (f Logfmt) String() string

String returns "logfmt".

type Logger Uses

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 Uses

func DefaultLogger() *Logger

DefaultLogger returns the pointer to the default logger.

func NewLogger Uses

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) Critical Uses

func (l *Logger) Critical(msg string, fields map[string]interface{}) error

Critical outputs a critical log. fields can be nil.

func (*Logger) Debug Uses

func (l *Logger) Debug(msg string, fields map[string]interface{}) error

Debug outputs a debug log. fields can be nil.

func (*Logger) Defaults Uses

func (l *Logger) Defaults() map[string]interface{}

Defaults returns default field values.

func (*Logger) Enabled Uses

func (l *Logger) Enabled(level int) bool

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) Error Uses

func (l *Logger) Error(msg string, fields map[string]interface{}) error

Error outputs an error log. fields can be nil.

func (*Logger) Formatter Uses

func (l *Logger) Formatter() Formatter

Formatter returns the current log formatter.

func (*Logger) Info Uses

func (l *Logger) Info(msg string, fields map[string]interface{}) error

Info outputs an informational log. fields can be nil.

func (*Logger) Log Uses

func (l *Logger) Log(severity int, msg string, fields map[string]interface{}) error

Log outputs a log message with additional fields. fields can be nil.

func (*Logger) SetDefaults Uses

func (l *Logger) SetDefaults(d map[string]interface{}) error

SetDefaults sets default field values for the logger. Setting nil effectively clear the defaults.

func (*Logger) SetErrorHandler Uses

func (l *Logger) SetErrorHandler(h func(error) error)

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 Uses

func (l *Logger) SetFormatter(f Formatter)

SetFormatter sets log formatter.

func (*Logger) SetOutput Uses

func (l *Logger) SetOutput(w io.Writer)

SetOutput sets io.Writer for log output. Setting nil disables log output.

func (*Logger) SetThreshold Uses

func (l *Logger) SetThreshold(level int)

SetThreshold sets the threshold for the logger. level must be a pre-defined constant such as LvInfo.

func (*Logger) SetThresholdByName Uses

func (l *Logger) SetThresholdByName(n string) error

SetThresholdByName sets the threshold for the logger by the level name.

func (*Logger) SetTopic Uses

func (l *Logger) SetTopic(topic string)

SetTopic sets a new topic for the logger. topic must not be empty. Too long topic may be shortened automatically.

func (*Logger) Threshold Uses

func (l *Logger) Threshold() int

Threshold returns the current threshold of the logger.

func (*Logger) Topic Uses

func (l *Logger) Topic() string

Topic returns the topic for the logger.

func (*Logger) Warn Uses

func (l *Logger) Warn(msg string, fields map[string]interface{}) error

Warn outputs a warning log. fields can be nil.

func (*Logger) WriteThrough Uses

func (l *Logger) WriteThrough(data []byte) error

WriteThrough writes data through to the underlying writer.

func (*Logger) Writer Uses

func (l *Logger) Writer(severity int) io.Writer

Writer returns an io.Writer. Each line written in the writer will be logged to the logger with the given severity.

type MsgPack Uses

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.

https://github.com/msgpack/msgpack/blob/master/spec.md

func (MsgPack) Format Uses

func (m MsgPack) Format(b []byte, l *Logger, t time.Time, severity int, msg string,
    fields map[string]interface{}) ([]byte, error)

Format implements Formatter.Format.

func (MsgPack) String Uses

func (m MsgPack) String() string

String returns "msgpack".

type Opener Uses

type Opener interface {
    Open() (io.WriteCloser, error)
}

Opener returns a new io.WriteCloser.

type PlainFormat Uses

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...]

func (PlainFormat) Format Uses

func (f PlainFormat) Format(buf []byte, l *Logger, t time.Time, severity int,
    msg string, fields map[string]interface{}) ([]byte, error)

Format implements Formatter.Format.

func (PlainFormat) String Uses

func (f PlainFormat) String() string

String returns "plain".

Directories

PathSynopsis
testcmd

Package log imports 25 packages (graph) and is imported by 70 packages. Updated 2019-08-21. Refresh now. Tools for package owners.