logger

README

go-logger

Logger aims to be a highly performant, levelled logging package with a simplistic API at first glance, but with the tools for much greater customization if necessary.

This was born after my own increasing frustrations with overly complex logging packages when often I just want the simple Print(), Info(), Error(). That's not to say they are bad packages, but the complexity of their APIs increases time required to adjust or later move to another. Not to mention being less enjoyable to use!

If you have highly specific logging needs, e.g. in a production environment with log parsing utilities, then using an existing solution e.g. zerolog is a good idea.

If you're looking for levelled logging that doesn't dump a kitchen sink in your lap, but keeps the parts around should you want it, then give this a try :)

Pass -tags=kvformat to your build to use the custom formatter in go-kv when printing fields (see package for more details).

Import with "codeberg.org/gruf/go-logger/v2". Only v2 is supported going forward.

Documentation

Index

• type Config
• type Flags
  • func (f Flags) Caller() bool
  • func (f Flags) SetCaller() Flags
  • func (f Flags) SetTime() Flags
  • func (f Flags) Time() bool
  • func (f Flags) UnsetCaller() Flags
  • func (f Flags) UnsetTime() Flags
• type Logger
  • func New(out io.Writer) *Logger
  • func NewWith(out io.Writer, cfg Config, lvl level.LEVEL, flags Flags) *Logger
  • func (l *Logger) Debug(a ...interface{})
  • func (l *Logger) DebugKVs(fields ...kv.Field)
  • func (l *Logger) Debugf(s string, a ...interface{})
  • func (l *Logger) Entry(calldepth int) *entry.Entry
  • func (l *Logger) Error(a ...interface{})
  • func (l *Logger) ErrorKVs(fields ...kv.Field)
  • func (l *Logger) Errorf(s string, a ...interface{})
  • func (l *Logger) Fatal(a ...interface{})
  • func (l *Logger) FatalKVs(fields ...kv.Field)
  • func (l *Logger) Fatalf(s string, a ...interface{})
  • func (l *Logger) Flags() Flags
  • func (l *Logger) Info(a ...interface{})
  • func (l *Logger) InfoKVs(fields ...kv.Field)
  • func (l *Logger) Infof(s string, a ...interface{})
  • func (l *Logger) Level() level.LEVEL
  • func (l *Logger) Log(calldepth int, lvl level.LEVEL, a ...interface{})
  • func (l *Logger) LogKVs(calldepth int, lvl level.LEVEL, fields ...kv.Field)
  • func (l *Logger) Logf(calldepth int, lvl level.LEVEL, s string, a ...interface{})
  • func (l *Logger) Panic(a ...interface{})
  • func (l *Logger) PanicKVs(fields ...kv.Field)
  • func (l *Logger) Panicf(s string, a ...interface{})
  • func (l *Logger) Print(a ...interface{})
  • func (l *Logger) PrintKVs(fields ...kv.Field)
  • func (l *Logger) Printf(s string, a ...interface{})
  • func (l *Logger) SetFlags(flags Flags)
  • func (l *Logger) SetLevel(lvl level.LEVEL)
  • func (l *Logger) SetOutput(out io.Writer)
  • func (l *Logger) Trace(a ...interface{})
  • func (l *Logger) TraceKVs(fields ...kv.Field)
  • func (l *Logger) Tracef(s string, a ...interface{})
  • func (l *Logger) Warn(a ...interface{})
  • func (l *Logger) WarnKVs(fields ...kv.Field)
  • func (l *Logger) Warnf(s string, a ...interface{})
  • func (l *Logger) Write(entry *entry.Entry)
  • func (l *Logger) Writer() io.Writer

Types

type Config

type Config struct {
	// FlagHandler handles any necessary tasks to perform on an Entry
	// given the provided flags. Calldepth is provided for logger.FCaller.
	FlagHandler func(entry *entry.Entry, calldepth int, flags Flags)

	// Format provides formatting for Entries produced from Logger.
	Format entry.Formatter

	// Calldepth allows setting a minimum calldepth for log entries when
	// calling functions that internally set a calldepth e.g. .Print(),
	// though will not effect functions that accept a calldepth argument.
	// This is useful when wrapping Logger.
	Calldepth int
}

Config provides entry format configuration for a Logger.

type Flags

type Flags bitutil.Flags16

Flags provides configurable output flags for Logger.

func (Flags) Caller

func (f Flags) Caller() bool

Caller will return if the Caller flag bit is set.

func (Flags) SetCaller

func (f Flags) SetCaller() Flags

SetCaller will set the Caller flag bit.

func (Flags) SetTime

func (f Flags) SetTime() Flags

SetTime will set the Time flag bit.

func (Flags) Time

func (f Flags) Time() bool

Time will return if the Time flag bit is set.

func (Flags) UnsetCaller

func (f Flags) UnsetCaller() Flags

UnsetCaller will unset the Caller flag bit.

func (Flags) UnsetTime

func (f Flags) UnsetTime() Flags

UnsetTime will unset the Time flag bit.

type Logger

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

Logger is an object that provides logging to an io.Writer output with levels and many formatting options. Each log entry is written to the output by a singular .Write() call.

func New

func New(out io.Writer) *Logger

New returns a new Logger instance with defaults.

func NewWith

func NewWith(out io.Writer, cfg Config, lvl level.LEVEL, flags Flags) *Logger

NewWith returns a new Logger instance with given configuration, logging level and log flags.

func (*Logger) Debug

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

Debug: see Logger.Log.

func (*Logger) DebugKVs

func (l *Logger) DebugKVs(fields ...kv.Field)

DebugKVs: see Logger.LogKVs.

func (*Logger) Debugf

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

Debugf: see Logger.Logf.

func (*Logger) Entry

func (l *Logger) Entry(calldepth int) *entry.Entry

Entry will acquire a log entry from memory pool and append any information required by log flags using Config.FlagHandler(). This is valid until passed to Logger.Write().

func (*Logger) Error

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

Error: see Logger.Log.

func (*Logger) ErrorKVs

func (l *Logger) ErrorKVs(fields ...kv.Field)

ErrorKVs: see Logger.LogKVs.

func (*Logger) Errorf

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

Errorf: see Logger.Logf.

func (*Logger) Fatal

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

Fatal: see Logger.Log. Aftward, exits with `defer syscall.Exit(1)`.

func (*Logger) FatalKVs

func (l *Logger) FatalKVs(fields ...kv.Field)

FatalKVs: see Logger.LogKVs. Aftward, exits with `defer syscall.Exit(1)`.

func (*Logger) Fatalf

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

Fatalf: see Logger.Logf. Aftward, exits with `defer syscall.Exit(1)`.

func (*Logger) Flags

func (l *Logger) Flags() Flags

Flags will return the currently set logger flags.

func (*Logger) Info

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

Info: see Logger.Log.

func (*Logger) InfoKVs

func (l *Logger) InfoKVs(fields ...kv.Field)

InfoKVs: see Logger.LogKVs.

func (*Logger) Infof

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

Infof: see Logger.Logf.

func (*Logger) Level

func (l *Logger) Level() level.LEVEL

Level will return the currently set logger value.

func (*Logger) Log

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

Log writes provided args to the log output at provided log level. Calldepth determines number of frames to skip when .FCaller is enabled and calculating stack frames.

func (*Logger) LogKVs

func (l *Logger) LogKVs(calldepth int, lvl level.LEVEL, fields ...kv.Field)

LogKVs writes provided key-value fields to the log output. Calldepth determines number of frames to skip when .FCaller is enabled and calculating stack frames.

func (*Logger) Logf

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

Logf writes provided format string and args to the log output. Calldepth determines number of frames to skip when .FCaller is enabled and calculating stack frames.

func (*Logger) Panic

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

Panic: see Logger.Log. Aftward, exits with `defer panic(fmt.Sprintf(a...))`.

func (*Logger) PanicKVs

func (l *Logger) PanicKVs(fields ...kv.Field)

PanicKVs: see Logger.LogKVs. Aftward, exits with `defer panic(fmt.Sprintf(a...))`.

func (*Logger) Panicf

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

Panicf: see Logger.Logf. Aftward, exits with `defer panic(fmt.Sprintf(a...))`.

func (*Logger) Print

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

Print writes provided args to the log output.

func (*Logger) PrintKVs

func (l *Logger) PrintKVs(fields ...kv.Field)

PrintKVs writes provided key-value fields to the log output.

func (*Logger) Printf

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

Printf writes provided format string and args to the log output.

func (*Logger) SetFlags

func (l *Logger) SetFlags(flags Flags)

SetFlags will set the logger flags to the given value.

func (*Logger) SetLevel

func (l *Logger) SetLevel(lvl level.LEVEL)

SetLevel will set the logger level to the given value.

func (*Logger) SetOutput

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

SetOutput will update the log output to given writer.

func (*Logger) Trace

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

Trace: see Logger.Log.

func (*Logger) TraceKVs

func (l *Logger) TraceKVs(fields ...kv.Field)

TraceKVs: see Logger.LogKVs.

func (*Logger) Tracef

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

Tracef: see Logger.Logf.

func (*Logger) Warn

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

Warn: see Logger.Log.

func (*Logger) WarnKVs

func (l *Logger) WarnKVs(fields ...kv.Field)

WarnKVs: see Logger.LogKVs.

func (*Logger) Warnf

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

Warnf: see Logger.Logf.

func (*Logger) Write

func (l *Logger) Write(entry *entry.Entry)

Write will write the contents of log entry to the output writer, reset it, then release to memory pool. The entry is NOT safe to be used after passing to this function.

func (*Logger) Writer

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

Writer returns the current output writer.