logger

package module
v1.2.4 Latest Latest
Warning

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

 Go to latest Published: Nov 27, 2021 License: MIT Imports: 13 Imported by: 1

README

Fast levelled logging package with customizable formatting.

Supports logging in 2 modes:

  • no locks, fastest possible logging, no guarantees for io.Writer thread safety
  • mutex locks during writes, still far faster than standard library logger

Running without locks isn't likely to cause you any issues*, but if it does, you can wrap your io.Writer using AddSafety() when instantiating your new Logger. Even when running the benchmarks, this library has no printing issues without locks, so in most cases you'll be fine, but the safety is there if you need it.

*most logging libraries advertising high speeds are likely not performing mutex locks, which is why with this library you have the option to opt-in/out of them.

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var DefaultTextFormat = TextFormat{
	Strict:     false,
	MaxDepth:   5,
	Levels:     DefaultLevels(),
	TimeFormat: time.RFC1123,
}

DefaultTextFormat is the default TextFormat instance

Functions

func AddSafety added in v1.1.3 

func AddSafety(w io.Writer) io.Writer

AddSafety wraps an io.Writer to provide mutex locking protection

func Debug 

func Debug(a ...interface{})

Debug prints the provided arguments with the debug prefix to the global Logger instance.

func Debugf 

func Debugf(s string, a ...interface{})

Debugf prints the provided format string and arguments with the debug prefix to the global Logger instance.

func Error 

func Error(a ...interface{})

Error prints the provided arguments with the error prefix to the global Logger instance.

func Errorf 

func Errorf(s string, a ...interface{})

Errorf prints the provided format string and arguments with the error prefix to the global Logger instance.

func Fatal 

func Fatal(a ...interface{})

Fatal prints the provided arguments with the fatal prefix to the global Logger instance before exiting the program with os.Exit(1).

func Fatalf 

func Fatalf(s string, a ...interface{})

Fatalf prints the provided format string and arguments with the fatal prefix to the global Logger instance before exiting the program with os.Exit(1).

func Info 

func Info(a ...interface{})

Info prints the provided arguments with the info prefix to the global Logger instance.

func Infof 

func Infof(s string, a ...interface{})

Infof prints the provided format string and arguments with the info prefix to the global Logger instance.

func Log 

func Log(lvl LEVEL, a ...interface{})

Log prints the provided arguments with the supplied log level to the global Logger instance.

func Logf 

func Logf(lvl LEVEL, s string, a ...interface{})

Logf prints the provided format string and arguments with the supplied log level to the global Logger instance.

func Print 

func Print(a ...interface{})

Print simply prints provided arguments to the global Logger instance.

func Printf 

func Printf(s string, a ...interface{})

Printf simply prints provided the provided format string and arguments to the global Logger instance.

func Warn 

func Warn(a ...interface{})

Warn prints the provided arguments with the warn prefix to the global Logger instance.

func Warnf 

func Warnf(s string, a ...interface{})

Warnf prints the provided format string and arguments with the warn prefix to the global Logger instance.

Types

type Entry 

type Entry struct {
	// contains filtered or unexported fields
}

Entry defines an entry in the log, it is NOT safe for concurrent use

func (*Entry) Args added in v1.2.3 

func (e *Entry) Args(a ...interface{}) *Entry

Args appends the given args formatted using the log formatter (usually faster than printf) without any key-value / value formatting.

func (*Entry) Bool 

func (e *Entry) Bool(key string, value bool) *Entry

Bool appends a bool value as key-value pair to the log entry

func (*Entry) Bools 

func (e *Entry) Bools(key string, value []bool) *Entry

Bools appends a bool slice value as key-value pair to the log entry

func (*Entry) Byte 

func (e *Entry) Byte(key string, value byte) *Entry

Byte appends a byte value as key-value pair to the log entry

func (*Entry) Bytes 

func (e *Entry) Bytes(key string, value []byte) *Entry

Bytes appends a byte slice value as key-value pair to the log entry

func (*Entry) Context 

func (e *Entry) Context() context.Context

Context returns the current set Entry context.Context

func (*Entry) Duration 

func (e *Entry) Duration(key string, value time.Duration) *Entry

Duration appends a time.Duration value as key-value pair to the log entry

func (*Entry) Durations 

func (e *Entry) Durations(key string, value []time.Duration) *Entry

Durations appends a time.Duration slice value as key-value pair to the log entry

func (*Entry) Field 

func (e *Entry) Field(key string, value interface{}) *Entry

Field appends an interface value as key-value pair to the log entry

func (*Entry) Fields 

func (e *Entry) Fields(fields map[string]interface{}) *Entry

Fields appends a map of key-value pairs to the log entry

func (*Entry) Float 

func (e *Entry) Float(key string, value float64) *Entry

Float appends a float value as key-value pair to the log entry

func (*Entry) Floats 

func (e *Entry) Floats(key string, value []float64) *Entry

Floats appends a float slice value as key-value pair to the log entry

func (*Entry) Hooks 

func (e *Entry) Hooks() *Entry

Hooks applies currently set Hooks to the Entry. Please note this CAN be called and perform the Hooks multiple times

func (*Entry) Int 

func (e *Entry) Int(key string, value int) *Entry

Int appends an int value as key-value pair to the log entry

func (*Entry) Ints 

func (e *Entry) Ints(key string, value []int) *Entry

Ints appends an int slice value as key-value pair to the log entry

func (*Entry) Level 

func (e *Entry) Level(lvl LEVEL) *Entry

Level appends the supplied level to the log entry, and sets the entry level. Please note this CAN be called and append log levels multiple times

func (*Entry) Msg 

func (e *Entry) Msg(a ...interface{})

Msg appends the fmt.Sprint() formatted final message to the log and calls .Send()

func (*Entry) Msgf 

func (e *Entry) Msgf(s string, a ...interface{})

Msgf appends the fmt.Sprintf() formatted final message to the log and calls .Send()

func (*Entry) Send 

func (e *Entry) Send()

Send triggers write of the log entry, skipping if the entry's log LEVEL is below the currently set Logger level, and releases the Entry back to the Logger's Entry pool. So it is NOT safe to continue using this Entry object after calling .Send(), .Msg() or .Msgf()

func (*Entry) Str 

func (e *Entry) Str(key string, value string) *Entry

Str appends a string value as key-value pair to the log entry

func (*Entry) Strs 

func (e *Entry) Strs(key string, value []string) *Entry

Strs appends a string slice value as key-value pair to the log entry

func (*Entry) Time 

func (e *Entry) Time(key string, value time.Time) *Entry

Time appends a time.Time value as key-value pair to the log entry

func (*Entry) Times 

func (e *Entry) Times(key string, value []time.Time) *Entry

Times appends a time.Time slice value as key-value pair to the log entry

func (*Entry) Timestamp 

func (e *Entry) Timestamp() *Entry

Timestamp appends the current timestamp to the log entry. Please note this CAN be called and append the timestamp multiple times

func (*Entry) TimestampIf 

func (e *Entry) TimestampIf() *Entry

TimestampIf performs Entry.Timestamp() only IF timestamping is enabled for the Logger. Please note this CAN be called multiple times

func (*Entry) Uint 

func (e *Entry) Uint(key string, value uint) *Entry

Uint appends a uint value as key-value pair to the log entry

func (*Entry) Uints 

func (e *Entry) Uints(key string, value []uint) *Entry

Uints appends a uint slice value as key-value pair to the log entry

func (*Entry) Value added in v1.2.0 

func (e *Entry) Value(value interface{}) *Entry

Value appends the given value to the log entry formatted as a value, without a key.

func (*Entry) Values added in v1.2.0 

func (e *Entry) Values(values ...interface{}) *Entry

Values appends the given values to the log entry formatted as values, without a key.

func (*Entry) WithContext 

func (e *Entry) WithContext(ctx context.Context) *Entry

WithContext updates Entry context value to the supplied

type Hook 

type Hook interface {
	Do(*Entry)
}

Hook defines a log Entry modifier

type HookFunc 

type HookFunc func(*Entry)

HookFunc is a simple adapter to allow functions to satisfy the Hook interface

func (HookFunc) Do 

func (hook HookFunc) Do(entry *Entry)

type LEVEL 

type LEVEL uint8

LEVEL defines a level of logging 

const (
	DEBUG LEVEL = 5
	INFO  LEVEL = 10
	WARN  LEVEL = 15
	ERROR LEVEL = 20
	FATAL LEVEL = 25
)

Available levels of logging.

type Levels 

type Levels map[LEVEL]string

Levels defines a mapping of log LEVELs to formatted level strings

func DefaultLevels 

func DefaultLevels() Levels

DefaultLevels returns the default set of log levels

func (Levels) LevelString 

func (l Levels) LevelString(lvl LEVEL) string

LevelString fetches the appropriate level string for the provided level, or "unknown"

type LogFormat 

type LogFormat interface {
	// AppendLevel appends given log level to the log buffer
	AppendLevel(buf *bytes.Buffer, lvl LEVEL)

	// AppendTimestamp appends given time format string to the log buffer
	AppendTimestamp(buf *bytes.Buffer, fmtNow string)

	// AppendField appends given key-value pair to the log buffer
	AppendField(buf *bytes.Buffer, key string, value interface{})

	// AppendFields appends given key-values pairs to the log buffer
	AppendFields(buf *bytes.Buffer, fields map[string]interface{})

	// AppendValue appends given interface formatted as value to the log buffer
	AppendValue(buf *bytes.Buffer, value interface{})

	// AppendValues appends given interfaces formatted as values to the log buffer
	AppendValues(buf *bytes.Buffer, slice []interface{})

	// AppendArgs appends given interfaces raw to the log buffer
	AppendArgs(buf *bytes.Buffer, args []interface{})

	// AppendByteField appends given byte value as key-value pair to the log buffer
	AppendByteField(buf *bytes.Buffer, key string, value byte)

	// AppendBytesField appends given byte slice value as key-value pair to the log buffer
	AppendBytesField(buf *bytes.Buffer, key string, value []byte)

	// AppendStringField appends given string value as key-value pair to the log buffer
	AppendStringField(buf *bytes.Buffer, key string, value string)

	// AppendStringsField appends given string slice value as key-value pair to the log buffer
	AppendStringsField(buf *bytes.Buffer, key string, value []string)

	// AppendBoolField appends given bool value as key-value pair to the log buffer
	AppendBoolField(buf *bytes.Buffer, key string, value bool)

	// AppendBoolsField appends given bool slice value as key-value pair to the log buffer
	AppendBoolsField(buf *bytes.Buffer, key string, value []bool)

	// AppendIntField appends given int value as key-value pair to the log buffer
	AppendIntField(buf *bytes.Buffer, key string, value int)

	// AppendIntsField appends given int slice value as key-value pair to the log buffer
	AppendIntsField(buf *bytes.Buffer, key string, value []int)

	// AppendUintField appends given uint value as key-value pair to the log buffer
	AppendUintField(buf *bytes.Buffer, key string, value uint)

	// AppendUintsField appends given uint slice value as key-value pair to the log buffer
	AppendUintsField(buf *bytes.Buffer, key string, value []uint)

	// AppendFloatField appends given float value as key-value pair to the log buffer
	AppendFloatField(buf *bytes.Buffer, key string, value float64)

	// AppendFloatsField appends given float slice value as key-value pair to the log buffer
	AppendFloatsField(buf *bytes.Buffer, key string, value []float64)

	// AppendTimeField appends given time value as key-value pair to the log buffer
	AppendTimeField(buf *bytes.Buffer, key string, value time.Time)

	// AppendTimesField appends given time slice value as key-value pair to the log buffer
	AppendTimesField(buf *bytes.Buffer, key string, value []time.Time)

	// AppendDurationField appends given duration value as key-value pair to the log buffer
	AppendDurationField(buf *bytes.Buffer, key string, value time.Duration)

	// AppendDurationsField appends given duration slice value as key-value pair to the log buffer
	AppendDurationsField(buf *bytes.Buffer, key string, value []time.Duration)

	// AppendMsg appends given msg as key-value pair to the log buffer using fmt.Sprint(...) formatting
	AppendMsg(buf *bytes.Buffer, a ...interface{})

	// AppendMsgf appends given msg format string as key-value pair to the log buffer using fmt.Sprintf(...) formatting
	AppendMsgf(buf *bytes.Buffer, s string, a ...interface{})
}

LogFormat defines a method of formatting log entries

type Logger 

type Logger struct {
	// Hooks defines a list of hooks which are called before an entry
	// is written. This should NOT be modified while the Logger is in use
	Hooks []Hook

	// Level is the current log LEVEL, entries at level below the
	// currently set level will not be output. This should NOT
	// be modified while the Logger is in use
	Level LEVEL

	// Timestamp defines whether to automatically append timestamps
	// to entries written via Logger convience methods and specifically
	// Entry.TimestampIf(). This should NOT be modified while Logger in use
	Timestamp bool

	// Format is the log entry LogFormat to use. This should NOT
	// be modified while the Logger is in use
	Format LogFormat

	// BufferSize is the Entry buffer size to use when allocating
	// new Entry objects. This should be modified atomically
	BufSize int64

	// Output is the log's output writer. This should NOT be
	// modified while the Logger is in use
	Output io.Writer
	// contains filtered or unexported fields
}

func Default 

func Default() *Logger

Default returns the default Logger instance.

func New 

func New(out io.Writer) *Logger

New returns a new Logger instance with defaults

func NewWith 

func NewWith(lvl LEVEL, timestamp bool, fmt LogFormat, bufsize int64, out io.Writer) *Logger

NewWith returns a new Logger instance with supplied configuration

func (*Logger) Debug 

func (l *Logger) Debug(a ...interface{})

Debug prints the provided arguments with the debug prefix

func (*Logger) Debugf 

func (l *Logger) Debugf(s string, a ...interface{})

Debugf prints the provided format string and arguments with the debug prefix

func (*Logger) Entry 

func (l *Logger) Entry() *Entry

Entry returns a new Entry from the Logger's pool with background context

func (*Logger) Error 

func (l *Logger) Error(a ...interface{})

Error prints the provided arguments with the error prefix

func (*Logger) Errorf 

func (l *Logger) Errorf(s string, a ...interface{})

Errorf prints the provided format string and arguments with the error prefix

func (*Logger) Fatal 

func (l *Logger) Fatal(a ...interface{})

Fatal prints provided arguments with the fatal prefix before exiting the program with os.Exit(1)

func (*Logger) Fatalf 

func (l *Logger) Fatalf(s string, a ...interface{})

Fatalf prints provided the provided format string and arguments with the fatal prefix before exiting the program with os.Exit(1)

func (*Logger) Info 

func (l *Logger) Info(a ...interface{})

Info prints the provided arguments with the info prefix

func (*Logger) Infof 

func (l *Logger) Infof(s string, a ...interface{})

Infof prints the provided format string and arguments with the info prefix

func (*Logger) Log 

func (l *Logger) Log(lvl LEVEL, a ...interface{})

Log prints the provided arguments with the supplied log level

func (*Logger) Logf 

func (l *Logger) Logf(lvl LEVEL, s string, a ...interface{})

Logf prints the provided format string and arguments with the supplied log level

func (*Logger) Print 

func (l *Logger) Print(a ...interface{})

Print simply prints provided arguments

func (*Logger) Printf 

func (l *Logger) Printf(s string, a ...interface{})

Printf simply prints provided the provided format string and arguments

func (*Logger) Warn 

func (l *Logger) Warn(a ...interface{})

Warn prints the provided arguments with the warn prefix

func (*Logger) Warnf 

func (l *Logger) Warnf(s string, a ...interface{})

Warnf prints the provided format string and arguments with the warn prefix

type TextFormat 

type TextFormat struct {
	// Strict defines whether to use strict key-value pair formatting, i.e. should the level
	// timestamp and msg be formatted as key-value pairs (with forced quoting for msg)
	Strict bool

	// MaxDepth specifies the max depth of fields the formatter will iterate
	MaxDepth uint8

	// Levels defines the map of log LEVELs to level strings
	Levels Levels

	// TimeFormat specifies the time formatting to use
	TimeFormat string
}

TextFormat is the default LogFormat implementation, with very similar formatting to logfmt

func (TextFormat) AppendArgs added in v1.2.3 

func (f TextFormat) AppendArgs(buf *bytes.Buffer, args []interface{})

func (TextFormat) AppendBoolField 

func (f TextFormat) AppendBoolField(buf *bytes.Buffer, key string, value bool)

func (TextFormat) AppendBoolsField 

func (f TextFormat) AppendBoolsField(buf *bytes.Buffer, key string, value []bool)

func (TextFormat) AppendByteField 

func (f TextFormat) AppendByteField(buf *bytes.Buffer, key string, value byte)

func (TextFormat) AppendBytesField 

func (f TextFormat) AppendBytesField(buf *bytes.Buffer, key string, value []byte)

func (TextFormat) AppendDurationField 

func (f TextFormat) AppendDurationField(buf *bytes.Buffer, key string, value time.Duration)

func (TextFormat) AppendDurationsField 

func (f TextFormat) AppendDurationsField(buf *bytes.Buffer, key string, value []time.Duration)

func (TextFormat) AppendField 

func (f TextFormat) AppendField(buf *bytes.Buffer, key string, value interface{})

func (TextFormat) AppendFields 

func (f TextFormat) AppendFields(buf *bytes.Buffer, fields map[string]interface{})

func (TextFormat) AppendFloatField 

func (f TextFormat) AppendFloatField(buf *bytes.Buffer, key string, value float64)

func (TextFormat) AppendFloatsField 

func (f TextFormat) AppendFloatsField(buf *bytes.Buffer, key string, value []float64)

func (TextFormat) AppendIntField 

func (f TextFormat) AppendIntField(buf *bytes.Buffer, key string, value int)

func (TextFormat) AppendIntsField 

func (f TextFormat) AppendIntsField(buf *bytes.Buffer, key string, value []int)

func (TextFormat) AppendLevel 

func (f TextFormat) AppendLevel(buf *bytes.Buffer, lvl LEVEL)

func (TextFormat) AppendMsg 

func (f TextFormat) AppendMsg(buf *bytes.Buffer, a ...interface{})

func (TextFormat) AppendMsgf 

func (f TextFormat) AppendMsgf(buf *bytes.Buffer, s string, a ...interface{})

func (TextFormat) AppendStringField 

func (f TextFormat) AppendStringField(buf *bytes.Buffer, key string, value string)

func (TextFormat) AppendStringsField 

func (f TextFormat) AppendStringsField(buf *bytes.Buffer, key string, value []string)

func (TextFormat) AppendTimeField 

func (f TextFormat) AppendTimeField(buf *bytes.Buffer, key string, value time.Time)

func (TextFormat) AppendTimesField 

func (f TextFormat) AppendTimesField(buf *bytes.Buffer, key string, value []time.Time)

func (TextFormat) AppendTimestamp 

func (f TextFormat) AppendTimestamp(buf *bytes.Buffer, now string)

func (TextFormat) AppendUintField 

func (f TextFormat) AppendUintField(buf *bytes.Buffer, key string, value uint)

func (TextFormat) AppendUintsField 

func (f TextFormat) AppendUintsField(buf *bytes.Buffer, key string, value []uint)

func (TextFormat) AppendValue added in v1.2.0 

func (f TextFormat) AppendValue(buf *bytes.Buffer, value interface{})

func (TextFormat) AppendValues added in v1.2.0 

func (f TextFormat) AppendValues(buf *bytes.Buffer, values []interface{})

Source Files

View all Source files

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.
JackTT - Gopher 🇻🇳