glog

README

gLog

Your silver bullet logging solution. Because that is definitely what the world needed: another logging library.

Features

gLog supports the following features:

• log-levels
• smart-colors
• customization
• caller-insertion
• mutiple outputs
• log rotation (coming soon™)
• panic-handling
• conditionals:
  • output per logging level
  • caller from a certain level
• sane defaults

Output

The output follows this structure:

%level:\t%time – %caller – …

%level is colored by default when logging to stdout or stderr. It can be enabled and disabled at will.

%time is in the ISO-8601 format working with nanosecond precision (if supported)

%caller is the name (format: package.function) of the function that is logging the message. By default this does not happen for INFO and WARNING.

Why – and not -

I decided to use U+2013 (EN DASH) because a normal U+002D (HYPHEN-MINUS) due to multiple reasons; some of which are:

• 2D is not at all unlikely to appear in a log-message
  • using 2013 allows for an easy way of splitting log lines without using RegEx
• they look very similar while they can still be distinguished
• it is also in most fonts used in a terminal
  • if it is not in your's think about changing fonts
• it allows for easy splitting and processing of logs with tools like cut or awk
• you don't have to type it by hand anyway

Levels

Level	Description
TRACE	Print everything. This is usually not wanted unless debugging.
DEBUG	Print every function call.
INFO	Print general statusmessages like HTTP-Requests (a good default)
WARNING	Handled errors. (the better default¹)
ERROR	Non-Critical Errors like access denied
FATAL	Errors that do not allow the Program to continue

¹) "no news is good news" or so they say

Environment Variables

All environment-variable values (not the variables themselves) are case insensitive.

GLOG_COLOR

• ALWAYS, ON, 1

  • automatically sets OverwriteColor to 1, thereby enabling color even on file outputs

• NEVER, OFF, -1

  • automatically sets OverwriteColor to -1, thereby disabling color even on terminals

GLOG_LEVEL

Sets the level to the specified value. Special cases:

• VERBOSE

  • an alias for TRACE

• MUTE, SILENT

  • disable every and all log-output

GLOG_METALOGGER

• 1
  • enable the built in meta-logger (the logger, logging activities of the logging library). DO NOT USE THIS UNLESS YOU HAVE GOOD REASON! It look horrible.

License

© Moritz Poldrack

gLog is a gun unter the MPL-2.0

To learn more you may:

• read the license-text here
• take a look at the official FAQs
• take a look at a summary at TLDRLegal

Documentation

Overview

glog aims to be the "one for all" logging package. It has a wide variety of features. To "handle errors gracefully" most times when a Setting-Function is called, no error is returned. If the specified level does not exist, execution is just silently aborted.

An important note is that *all* log-level ranges are inclusive. This means that "below …" actually means "below or equal to …".

Index

• Variables
• func AddLogFile(filepath string, lvls ...Level) (*os.File, error)
• func AddOutput(lvl Level, output io.Writer)
• func AddOutputAbove(lvl Level, output io.Writer)
• func AddOutputBelow(lvl Level, output io.Writer)
• func AddOutputBetween(lowerLevel, upperLevel Level, output io.Writer)
• func Debug(message ...interface{})
• func Debugf(format string, values ...interface{})
• func Error(message ...interface{})
• func Errorf(format string, values ...interface{})
• func Fatal(message ...interface{})
• func FatalStyle(content ...interface{}) string
• func Fatalf(format string, values ...interface{})
• func GetCaller(skipFrames int) string
• func Info(message ...interface{})
• func Infof(format string, values ...interface{})
• func PanicHandler()
• func PlainStyle(content ...interface{}) string
• func SetLevel(lvl Level) bool
• func SetOutput(lvl Level, output io.Writer)
• func SetOutputAbove(lvl Level, output io.Writer)
• func SetOutputBelow(lvl Level, output io.Writer)
• func SetOutputBetween(lowerLevel, upperLevel Level, output io.Writer)
• func SetShowCaller(lvl Level, show bool)
• func SetStyle(lvl Level, styler StyleFunction)
• func Trace(message ...interface{})
• func Tracef(format string, values ...interface{})
• func Warn(message ...interface{})
• func Warnf(format string, values ...interface{})
• type FormatFunction
• type Level
  • func (lvl Level) Short() string
  • func (lvl Level) String() string
• type StyleFunction

Variables

var (

	// OverwriteColor allows overwriting the coloring mode. 0 = auto;
	// 1 = always; -1 = never
	//
	// This can also be set using the Environment-variable `GLOG_COLOR`
	OverwriteColor int8
	// LogLevel indicates the level of verbosity to use when logging.
	// Messages below the specified level are discarded. Usually you want to
	// use SetLevel() to ensure that overrides are correctly applied.
	//
	// This can also be set using the Environment-variable `GLOG_LEVEL`
	LogLevel = WARNING
)

var (
	// TimeFormat specifies the formatting of the timestamp to use. The
	// default is ISO-8601 which corresponds to:
	TimeFormat = "2006-01-02T15:04:05.000000-0700"
	// NoPanic indicates that after a call to Fatal(f) no panic-stop shall
	// be executed.
	NoPanic bool
	// LogFormatter contains the function used to actually format logged
	// statements. Changing this allows complete control over the format of
	// log messages.
	LogFormatter FormatFunction = defaultLogFormat

	// EnableMetaLogging starts logging the inner workings of this library
	// and is usually only used when developing but can be helpful if there
	// are issues with your logging. If you happen to find a bug, please
	// don't hesitate it at: https://todo.sr.ht/~poldi1405/issues
	// (no account needed)
	EnableMetaLogging bool
)

Functions

func AddLogFile

func AddLogFile(filepath string, lvls ...Level) (*os.File, error)

AddLogFile opens the specified files and adds it to the specified levels

func AddOutput

func AddOutput(lvl Level, output io.Writer)

AddOutput adds the specified output to the list of outputs for the level

func AddOutputAbove

func AddOutputAbove(lvl Level, output io.Writer)

AddOutput adds the specified output to the list of outputs for the specified levels.

func AddOutputBelow

func AddOutputBelow(lvl Level, output io.Writer)

AddOutput adds the specified output to the list of outputs for the specified levels.

func AddOutputBetween

func AddOutputBetween(lowerLevel, upperLevel Level, output io.Writer)

AddOutputBetween adds the specified output to the list of outputs for all specified levels.

func Debug

func Debug(message ...interface{})

Debug logs a message at the DEBUG level

func Debugf

func Debugf(format string, values ...interface{})

Debugf formats the input values as specified and writes them to the according channels

func Error

func Error(message ...interface{})

Error logs a message at the ERROR level

func Errorf

func Errorf(format string, values ...interface{})

Errorf formats the input values as specified and writes them to the according channels

func Fatal

func Fatal(message ...interface{})

Fatal logs a message at the FATAL level and Panics afterwards

func FatalStyle

func FatalStyle(content ...interface{}) string

FatalStyle is the default style for fatal logmessages. Just in case you want to restore it after changing it.

func Fatalf

func Fatalf(format string, values ...interface{})

Fatalf formats the input values as specified and writes them to the according channels

func GetCaller

func GetCaller(skipFrames int) string

GetCaller returns the calling function. skipFrames indicates how far up the ladder we go when looking for the caller (2 = direct caller, 3 = caller of the caller, …). You can use this for more information in your log messages when creating custom formatters. Note that this is *relatively* expensive.

func Info

func Info(message ...interface{})

Info logs a message at the INFO level

func Infof

func Infof(format string, values ...interface{})

Infof formats the input values as specified and writes them to the according channels

func PanicHandler

func PanicHandler()

PanicHandler logs a panic if it occurs. A panic is always written to panic.log and then passed on. Under *no* circumstances should this be used as a way to ensure a programs stability. Make your own function for that.

func PlainStyle

func PlainStyle(content ...interface{}) string

PlainStyle is an implementation of StyleFunction that does not format output.

func SetLevel

func SetLevel(lvl Level) bool

SetLevel allows setting the loglevel while

func SetOutput

func SetOutput(lvl Level, output io.Writer)

SetOutput removes all outputs and replaces them with the specified output. To discard log messages to this level set the loglevel accordingly or use `io.Discard`

func SetOutputAbove

func SetOutputAbove(lvl Level, output io.Writer)

SetOutputAbove removes all outputs and replaces them with the specified output. This is repeated for every specified level.

func SetOutputBelow

func SetOutputBelow(lvl Level, output io.Writer)

SetOutput removes all outputs and replaces them with the specified output. This is repeated for every specified level.

func SetOutputBetween

func SetOutputBetween(lowerLevel, upperLevel Level, output io.Writer)

SetOutputBetween removes all outputs and replaces them with the specified output. This is executed for all specified levels.

func SetShowCaller

func SetShowCaller(lvl Level, show bool)

SetShowCaller allows defining for what levels the caller is displayed in the Log. By default the caller is shown for TRACE, DEBUG, ERROR, and FATAL.

func SetStyle

func SetStyle(lvl Level, styler StyleFunction)

SetStyle allows customizing the look of the *error-level*. This can also be used for changing the names of the loglevels.

func Trace

func Trace(message ...interface{})

Trace logs a message at the TRACE level

func Tracef

func Tracef(format string, values ...interface{})

Tracef formats the input values as specified and writes them to the according channels

func Warn

func Warn(message ...interface{})

Warn logs a message at the WARNING level

func Warnf

func Warnf(format string, values ...interface{})

Warnf formats the input values as specified and writes them to the according channels

Types

type FormatFunction

type FormatFunction func(Level, time.Time, string, string) string

FormatFunction allow defining custom logging formats and changing around the order. If Caller is not set all I can do at the moment is passing an empty string.

The string arguments correspond to caller and message.

type Level

type Level uint8

const (
	TRACE Level = iota
	DEBUG
	INFO
	WARNING
	ERROR
	FATAL
)

func (Level) Short

func (lvl Level) Short() string

Short returns a levels representation in log

func (Level) String

func (lvl Level) String() string

String implements the fmt.Stringer interface to allow use of levels in fmt calls.

type StyleFunction

type StyleFunction func(...interface{}) string

StyleFunction is a kind of function that is used for styling. I know, who would have thought.