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're looking for levelled logging that doesn't dump a kitchen sink in your lap, but keeps the parts around should you want it, 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/v3". Only v3 is supported going forward.

Documentation

Index

• Variables
• func Argsn(n int) string
• type CtxProvider
  • func (p CtxProvider) New(calldepth int) LogCtx
  • func (p *CtxProvider) SetIncludeCaller(enabled bool)
  • func (p *CtxProvider) SetIncludeTimestamp(enabled bool)
• type FieldFormatter
  • func (f *FieldFormatter) Format(buf *byteutil.Buffer, ctx LogCtx, msg string, args ...interface{})
• type LEVEL
  • func (loglvl LEVEL) CanLog(lvl LEVEL) bool
• type Levels
  • func (l Levels) Get(lvl LEVEL) string
  • func (l Levels) Parse(s string) (LEVEL, error)
• type LogCtx
• type Logger
  • func New(out io.Writer) *Logger
  • func NewWith(out io.Writer, lvl LEVEL, caller, timestamp bool) *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) 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) Info(a ...interface{})
  • func (l *Logger) InfoKVs(fields ...kv.Field)
  • func (l *Logger) Infof(s string, a ...interface{})
  • func (l *Logger) Log(calldepth int, lvl LEVEL, a ...interface{})
  • func (l *Logger) LogKVs(calldepth int, lvl LEVEL, fields ...kv.Field)
  • func (l *Logger) Logf(calldepth int, lvl LEVEL, s string, a ...interface{})
  • func (l *Logger) Output(ctx LogCtx, msg string, args ...interface{}) error
  • 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) 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) Writer() io.Writer
• type TextFormatter
  • func (f *TextFormatter) Format(buf *byteutil.Buffer, ctx LogCtx, msg string, args ...interface{})

Variables

var DefaultLevels = Levels{
	TRACE: "TRACE",
	DEBUG: "DEBUG",
	INFO:  "INFO",
	WARN:  "WARN",
	ERROR: "ERROR",
	FATAL: "FATAL",
	PANIC: "PANIC",
}

Default is the default set of log levels.

Functions

func Argsn

func Argsn(n int) string

Argsn returns a "%v " arg format string with 'n' args.

Types

type CtxProvider

type CtxProvider uint8

CtxProvider serves as an implementer of Logger.New, configurable via bit flags.

func (CtxProvider) New

func (p CtxProvider) New(calldepth int) LogCtx

New will allocate a new LogCtx with current

func (*CtxProvider) SetIncludeCaller

func (p *CtxProvider) SetIncludeCaller(enabled bool)

SetIncludeCaller will set whether to include caller information on LogCtx allocation.

func (*CtxProvider) SetIncludeTimestamp

func (p *CtxProvider) SetIncludeTimestamp(enabled bool)

SetIncludeTimestamp will set whether to include current time on LogCtx allocation.

type FieldFormatter

type FieldFormatter struct {
	Levels
}

FieldFormatter is a Levels wrapper to implement the logger.Format function, in a manner that provides logging with timestamp, caller info and level prefixing log entries in key-value formatting.

func (*FieldFormatter) Format

func (f *FieldFormatter) Format(buf *byteutil.Buffer, ctx LogCtx, msg string, args ...interface{})

type LEVEL

type LEVEL uint8

LEVEL defines a level of logging.

const (
	UNSET LEVEL = 0
	PANIC LEVEL = 1
	FATAL LEVEL = 50
	ERROR LEVEL = 100
	WARN  LEVEL = 150
	INFO  LEVEL = 200
	DEBUG LEVEL = 250
	TRACE LEVEL = 254
	ALL   LEVEL = ^LEVEL(0)
)

Default levels of logging.

func (LEVEL) CanLog

func (loglvl LEVEL) CanLog(lvl LEVEL) bool

CanLog returns whether an incoming log of 'lvl' can be logged against receiving level.

type Levels

type Levels [int(ALL) + 1]string

Levels defines a mapping of log LEVELs to formatted level strings.

func (Levels) Get

func (l Levels) Get(lvl LEVEL) string

Get fetches the level string for the provided value.

func (Levels) Parse

func (l Levels) Parse(s string) (LEVEL, error)

Parse will attempt to decode a LEVEL from given string, checking (case insensitive) against strings in Levels.

type LogCtx

type LogCtx struct {
	Context context.Context
	Caller  *runtime.Func
	Fields  []kv.Field
	Level   LEVEL
	Time    time.Time
}

LogCtx provides extra contextual information with each log message. For e.g. extra log fields, log time to include formatted timestamp, calling function information, logging level, and a context.Context which can be used to pass extra information to log hooks.

type Logger

type Logger struct {
	// Level specifies the maximum level of log entries to output. i.e. if
	// it is set to INFO, then ERROR,WARN,INFO would be outputted, but DEBUG
	// would not.
	Level LEVEL

	// New is the function used by Logger to allocate a new LogCtx for a log entry. The calldepth is passed
	// for determing caller information at the point of LogCtx creation, as used by the Logger output functions.
	New func(calldepth int) LogCtx

	// Format is the function used by Logger to format each log entry. The format string and arguments
	// containing the main log message, and LogCtx containing any extra contextual fieilds or caller information.
	Format func(buf *byteutil.Buffer, ctx LogCtx, msg string, args ...interface{})

	// Hooks allow modifying a log entry's LogCtx during Logger.Output().
	Hooks []func(LogCtx) LogCtx
	// contains filtered or unexported fields
}

Logger wraps an io.Writer to provide format-customizable levelled logging. All writes are mutex protected.

func New

func New(out io.Writer) *Logger

New returns a new Logger instance with defaults.

func NewWith

func NewWith(out io.Writer, lvl LEVEL, caller, timestamp bool) *Logger

NewWith returns a new Logger instance with given max log level, caller and timestamping configuration.

The default Logger function implementations are provided by: - Logger.New --> CtxProvider{}.New() - Logger.Format --> TextFormatter{}.Format()

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

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

Log writes provided args to the log output at provided log Calldepth is passed through to Logger.New, and determines how many frames to skip when calculating the caller.

func (*Logger) LogKVs

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

LogKVs writes provided key-value fields to the log output. Calldepth is passed through to Logger.New, and determines how many frames to skip when calculating the caller.

func (*Logger) Logf

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

Logf writes provided format string and args to the log output. Calldepth is passed through to Logger.New, and determines how many frames to skip when calculating the caller.

func (*Logger) Output

func (l *Logger) Output(ctx LogCtx, msg string, args ...interface{}) error

Output will take a log entry format string with contextual information (LogCtx), and handle passing through log hooks, formatting and sending to the output io.Writer. The LogCtx level is checked directly after passing through hooks, returning early if required.

func (*Logger) Panic

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

Panic: see Logger.Log. Aftward, exits with `defer panic(fmt.Sprintf(logger.Argsn(len(a)), 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) 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) Writer

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

Writer returns the current output writer.

type TextFormatter

type TextFormatter struct {
	Levels
}

TextFormatter is a Levels wrapper to implement the logger.Format function, in a manner that provides logging with timestamp, caller info and level prefixing in plain printed text.

func (*TextFormatter) Format

func (f *TextFormatter) Format(buf *byteutil.Buffer, ctx LogCtx, msg string, args ...interface{})