log

package module
v1.7.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 1, 2023 License: MIT Imports: 23 Imported by: 168

README

GitHub release CI PkgGoDev Go Report Card

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

View Source 
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.

View Source 
const (
	LvCritical = 2
	LvError    = 3
	LvWarn     = 4
	LvInfo     = 6
	LvDebug    = 7
)

Severities a.k.a log levels.

View Source 
const (
	// EnvLogLevel ks the environment variable name to configure
	// the default logger's log level at program startup.
	EnvLogLevel = "CYBOZU_LOG_LEVEL"
)
View Source 
const (
	// RFC3339Micro is for time.Time.Format().
	RFC3339Micro = "2006-01-02T15:04:05.000000Z07:00"
)

Variables

View Source 
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 Critical 

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

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

func Debug 

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

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

func Enabled 

func Enabled(level int) bool

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

func Error 

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

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

func ErrorExit 

func ErrorExit(err error)

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

func Info 

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

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

func IsValidKey 

func IsValidKey(key string) bool

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

func LevelName 

func LevelName(level int) string

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

func NewFileReopener 

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 

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 

func ReservedKey(k string) bool

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

func Warn 

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

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

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.

https://jsonlines.org/

func (JSONFormat) Format 

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 

func (f JSONFormat) String() string

String returns "json".

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

func (Logfmt) Format 

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 

func (f Logfmt) String() string

String returns "logfmt".

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

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

Critical outputs a critical log. fields can be nil.

func (*Logger) Debug 

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

Debug outputs a debug log. fields can be nil.

func (*Logger) Defaults 

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

Defaults returns default field values.

func (*Logger) Enabled 

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 

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

Error outputs an error log. fields can be nil.

func (*Logger) Formatter 

func (l *Logger) Formatter() Formatter

Formatter returns the current log formatter.

func (*Logger) Info 

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

Info outputs an informational log. fields can be nil.

func (*Logger) Log 

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 

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 added in v1.4.0 

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 

func (l *Logger) SetFormatter(f Formatter)

SetFormatter sets log formatter.

func (*Logger) SetOutput 

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

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

func (*Logger) SetThreshold 

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 

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

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

func (*Logger) SetTopic 

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 

func (l *Logger) Threshold() int

Threshold returns the current threshold of the logger.

func (*Logger) Topic 

func (l *Logger) Topic() string

Topic returns the topic for the logger.

func (*Logger) Warn 

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

Warn outputs a warning log. fields can be nil.

func (*Logger) WriteThrough added in v1.2.0 

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

WriteThrough writes data through to the underlying writer.

func (*Logger) Writer 

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 

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 

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 

func (m MsgPack) String() string

String returns "msgpack".

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

func (PlainFormat) Format 

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 

func (f PlainFormat) String() string

String returns "plain".

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.