logger

package module
v1.3.2 Latest Latest
Warning

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

 Go to latest Published: Dec 14, 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.

Note there are 2 uses of the unsafe package:

  • safer interface nil value checks, uses similar logic to reflect package to check if the value in the internal fat pointer is nil
  • casting a byte slice to string to allow sharing of similar byte and string methods, performs same logic as strings.Builder{}.String()

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var DefaultTextFormat = TextFormat{
	Strict:   false,
	Verbose:  false,
	MaxDepth: 10,
	Levels:   DefaultLevels(),
}

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

func LogFields(lvl LEVEL, fields map[string]interface{})

LogFields prints the provided fields formatted as key-value pairs at the supplied log level to the global Logger instance.

func LogValues added in v1.3.1 

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

LogValues prints the provided values formatted as-so at 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 PrintFields added in v1.3.1 

func PrintFields(fields map[string]interface{})

PrintFields prints the provided fields formatted as key-value pairs to the global Logger instance.

func PrintValues added in v1.3.1 

func PrintValues(a ...interface{})

PrintValues prints the provided values formatted as-so 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) Append added in v1.2.5 

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

Append will append the given args formatted using fmt.Sprint(a...) to the Entry.

func (*Entry) Appendf added in v1.2.5 

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

Appendf will append the given format string and args using fmt.Sprintf(s, a...) to the Entry.

func (*Entry) Bool 

func (e *Entry) Bool(value bool) *Entry

Bool appends a bool value to the log entry

func (*Entry) BoolField added in v1.3.0 

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

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

func (*Entry) Bools 

func (e *Entry) Bools(value []bool) *Entry

Bools appends a bool slice value to the log entry

func (*Entry) BoolsField added in v1.3.0 

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

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

func (*Entry) Byte 

func (e *Entry) Byte(value byte) *Entry

Byte appends a byte value to the log entry

func (*Entry) ByteField added in v1.3.0 

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

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

func (*Entry) Bytes 

func (e *Entry) Bytes(value []byte) *Entry

Bytes appends a byte slice value as to the log entry

func (*Entry) BytesField added in v1.3.0 

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

BytesField 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(value time.Duration) *Entry

DurationField appends a time.Duration value to the log entry

func (*Entry) DurationField added in v1.3.0 

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

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

func (*Entry) Durations 

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

Durations appends a time.Duration slice value to the log entry

func (*Entry) DurationsField added in v1.3.0 

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

DurationsField 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(value float64) *Entry

Float appends a float value to the log entry

func (*Entry) FloatField added in v1.3.0 

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

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

func (*Entry) Floats 

func (e *Entry) Floats(value []float64) *Entry

Floats appends a float slice value to the log entry

func (*Entry) FloatsField added in v1.3.0 

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

FloatsField 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(value int) *Entry

Int appends an int value to the log entry

func (*Entry) IntField added in v1.3.0 

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

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

func (*Entry) Ints 

func (e *Entry) Ints(value []int) *Entry

Ints appends an int slice value to the log entry

func (*Entry) IntsField added in v1.3.0 

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

IntsField 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(value string) *Entry

Str appends a string value to the log entry

func (*Entry) StrField added in v1.3.0 

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

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

func (*Entry) Strs 

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

Strs appends a string slice value to the log entry

func (*Entry) StrsField added in v1.3.0 

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

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

func (*Entry) Time 

func (e *Entry) Time(value time.Time) *Entry

Time appends a time.Time value to the log entry

func (*Entry) TimeField added in v1.3.0 

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

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

func (*Entry) Times 

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

Times appends a time.Time slice value to the log entry

func (*Entry) TimesField added in v1.3.0 

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

TimesField 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(value uint) *Entry

Uint appends a uint value to the log entry

func (*Entry) UintField added in v1.3.0 

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

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

func (*Entry) Uints 

func (e *Entry) Uints(value []uint) *Entry

Uints appends a uint slice value to the log entry

func (*Entry) UintsField added in v1.3.0 

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

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

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

type Formattable interface {
	AppendFormat([]byte) []byte
}

Formattable defines a type capable of writing a string formatted form of itself to a supplied byte buffer, and returning the resulting byte buffer. Implementing this will greatly speed up formatting of custom types passed to LogFormat (assuming they implement checking for this).

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 [^LEVEL(0)]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) Get added in v1.3.1 

func (l Levels) Get(lvl LEVEL) string

Get fetches the level string for the provided value, or "unknown"

type LogFormat 

type LogFormat interface {
	// AppendKey appends given key to the log buffer
	AppendKey(buf *bytes.Buffer, key string)

	// AppendLevel appends given log level as key-value pair to the log buffer
	AppendLevel(buf *bytes.Buffer, lvl LEVEL)

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

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

	// AppendByte appends given byte value to the log buffer
	AppendByte(buf *bytes.Buffer, value byte)

	// AppendBytes appends given byte slice value to the log buffer
	AppendBytes(buf *bytes.Buffer, value []byte)

	// AppendString appends given string value to the log buffer
	AppendString(buf *bytes.Buffer, value string)

	// AppendStrings appends given string slice value to the log buffer
	AppendStrings(buf *bytes.Buffer, value []string)

	// AppendBool appends given bool value to the log buffer
	AppendBool(buf *bytes.Buffer, value bool)

	// AppendBools appends given bool slice value to the log buffer
	AppendBools(buf *bytes.Buffer, value []bool)

	// AppendInt appends given int value to the log buffer
	AppendInt(buf *bytes.Buffer, value int)

	// AppendInts appends given int slice value to the log buffer
	AppendInts(buf *bytes.Buffer, value []int)

	// AppendUint appends given uint value to the log buffer
	AppendUint(buf *bytes.Buffer, value uint)

	// AppendUints appends given uint slice value to the log buffer
	AppendUints(buf *bytes.Buffer, value []uint)

	// AppendFloat appends given float value to the log buffer
	AppendFloat(buf *bytes.Buffer, value float64)

	// AppendFloats appends given float slice value to the log buffer
	AppendFloats(buf *bytes.Buffer, value []float64)

	// AppendTime appends given time value to the log buffer
	AppendTime(buf *bytes.Buffer, value time.Time)

	// AppendTimes appends given time slice value to the log buffer
	AppendTimes(buf *bytes.Buffer, value []time.Time)

	// AppendDuration appends given duration value to the log buffer
	AppendDuration(buf *bytes.Buffer, value time.Duration)

	// AppendDurations appends given duration slice value to the log buffer
	AppendDurations(buf *bytes.Buffer, 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 at the supplied log level

func (*Logger) LogFields added in v1.3.1 

func (l *Logger) LogFields(lvl LEVEL, fields map[string]interface{})

LogFields prints the provided fields formatted as key-value pairs at the supplied log level

func (*Logger) LogValues added in v1.3.1 

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

LogValues prints the provided values formatted as-so at 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 at the supplied log level

func (*Logger) Print 

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

Print simply prints provided arguments

func (*Logger) PrintFields added in v1.3.1 

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

PrintFields prints the provided fields formatted as key-value pairs

func (*Logger) PrintValues added in v1.3.1 

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

PrintValues prints the provided values formatted as-so

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

	// Verbose defines whether to increase output verbosity, i.e. include types with nil values
	// and force values implementing .String() / .AppendFormat() to be printed as a struct etc.
	Verbose 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
}

TextFormat is the default LogFormat implementation, with very similar formatting to the standard "fmt" package's '%#v' operator. The main difference being that pointers are dereferenced as far as possible in order to reach a printable value. It is also *mildly* faster.

func (TextFormat) AppendBool added in v1.3.0 

func (f TextFormat) AppendBool(buf *bytes.Buffer, value bool)

func (TextFormat) AppendBools added in v1.3.0 

func (f TextFormat) AppendBools(buf *bytes.Buffer, value []bool)

func (TextFormat) AppendByte added in v1.3.0 

func (f TextFormat) AppendByte(buf *bytes.Buffer, value byte)

func (TextFormat) AppendBytes added in v1.3.0 

func (f TextFormat) AppendBytes(buf *bytes.Buffer, value []byte)

func (TextFormat) AppendDuration added in v1.3.0 

func (f TextFormat) AppendDuration(buf *bytes.Buffer, value time.Duration)

func (TextFormat) AppendDurations added in v1.3.0 

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

func (TextFormat) AppendFloat added in v1.3.0 

func (f TextFormat) AppendFloat(buf *bytes.Buffer, value float64)

func (TextFormat) AppendFloats added in v1.3.0 

func (f TextFormat) AppendFloats(buf *bytes.Buffer, value []float64)

func (TextFormat) AppendInt added in v1.3.0 

func (f TextFormat) AppendInt(buf *bytes.Buffer, value int)

func (TextFormat) AppendInts added in v1.3.0 

func (f TextFormat) AppendInts(buf *bytes.Buffer, value []int)

func (TextFormat) AppendKey added in v1.3.0 

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

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) AppendString added in v1.3.0 

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

func (TextFormat) AppendStrings added in v1.3.0 

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

func (TextFormat) AppendTime added in v1.3.0 

func (f TextFormat) AppendTime(buf *bytes.Buffer, value time.Time)

func (TextFormat) AppendTimes added in v1.3.0 

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

func (TextFormat) AppendTimestamp 

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

func (TextFormat) AppendUint added in v1.3.0 

func (f TextFormat) AppendUint(buf *bytes.Buffer, value uint)

func (TextFormat) AppendUints added in v1.3.0 

func (f TextFormat) AppendUints(buf *bytes.Buffer, value []uint)

func (TextFormat) AppendValue added in v1.2.0 

func (f TextFormat) AppendValue(buf *bytes.Buffer, value 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 🇻🇳