glog

package module
v1.0.1 Latest Latest
Warning

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

 Go to latest Published: Dec 6, 2021 License: MPL-2.0 Imports: 10 Imported by: 5

README

gLog

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

Coverage License godocs.io no non-stdlib deps that must be credited*

Features

gLog supports the following features:

  • log-levels
  • smart-colors
  • customization
  • caller-insertion
  • multiple outputs
  • log rotation
  • panic-handling
  • conditionals:
    • output per logging level
    • caller from a certain level
  • sane defaults
coming soon™:
  • "plug-n-play" log formats

Output

The output follows this structure:

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

%level is coloured 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) over 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
  • 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 status messages 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

Notes

  • Obviously, setting a low loglevel will slow down your program, as the writing is not buffered and getting the caller is relatively expensive
    • using StdOut/StdErr for logging decreases this time because it does not need to write to disk

Learn more

You can find more information in this project's wiki

NO_COLOR

glog respects NO_COLOR

Contribute

Contributions are welcome from anyone. Just send a patchset to ~poldi1405/patches@lists.sr.ht and wait for feedback. For general questions or other communications feel free to drop a message to ~poldi1405/discussion@lists.sr.ht

Updates will be announced here

The changelog can be found here

License

* the claim 0 external dependencies refers to 0 dependencies that have to be credited. By crediting this package, the crediting for the only external dependency is also fulfilled

© Moritz Poldrack and contributors

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

Package 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

Examples

Constants

This section is empty.

Variables

View Source 
var (

	// OverrideColor allows overwriting the coloring mode. 0 = auto;
	// 1 = always; -1 = never
	//
	// This can also be set using the Environment-variable `GLOG_COLOR`
	OverrideColor 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
)
View Source 
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"
	// 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
	// ShortCaller indicates whether the printed caller should be shortened
	// to only include the package and it's function instead of the entire
	// import-path.
	ShortCaller = true
	// ShowCallerLine displays file and line as the caller instead of the
	// function that called.
	ShowCallerLine bool
	// PanicLogFile is the file panics are logged to.
	PanicLogFile = "panic.log"
)

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)

AddOutputAbove adds the specified output to the list of outputs for the levels including and above the specified levels.

Example 
AddOutputAbove(WARNING, os.Stderr)
// is equal to
AddOutput(WARNING, os.Stderr)
AddOutput(ERROR, os.Stderr)
AddOutput(FATAL, os.Stderr)

Output:

func AddOutputBelow 

func AddOutputBelow(lvl Level, output io.Writer)

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

Example 
AddOutputBelow(WARNING, os.Stderr)
// is equal to
AddOutput(WARNING, os.Stderr)
AddOutput(INFO, os.Stderr)
AddOutput(DEBUG, os.Stderr)
AddOutput(TRACE, os.Stderr)

Output:

func AddOutputBetween 

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

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

Example 
AddOutputBetween(DEBUG, ERROR, os.Stderr)
// is equal to
AddOutput(DEBUG, os.Stderr)
AddOutput(INFO, os.Stderr)
AddOutput(WARNING, os.Stderr)
AddOutput(ERROR, os.Stderr)

Output:

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 it is recommended to exit the program afterwards.

func FatalStyle added in v0.1.2 

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 channel. It is recommended to exit the program afterwards.

func GetCaller added in v0.1.2 

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 Log added in v0.3.1 

func Log(lvl Level, message ...interface{})

Log logs a message at the specified level

func Logf added in v0.3.1 

func Logf(lvl Level, format string, values ...interface{})

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

func PanicHandler added in v0.1.2 

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 added in v0.1.1 

func SetLevel(lvl Level) bool

SetLevel allows setting the loglevel while preserving the level set using the environment

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 a 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 all specified levels. For more information on the inner workings of SetOutput* see the SetOutput() function.

Example 
SetOutputAbove(WARNING, os.Stderr)
// is equal to
SetOutput(WARNING, os.Stderr)
SetOutput(ERROR, os.Stderr)
SetOutput(FATAL, os.Stderr)

Output:

func SetOutputBelow 

func SetOutputBelow(lvl Level, output io.Writer)

SetOutputBelow removes all outputs and replaces them with the specified output. This is repeated for all specified levels. For more information on the inner workings of SetOutput* see the SetOutput() function.

Example 
SetOutputBelow(WARNING, os.Stderr)
// is equal to
SetOutput(WARNING, os.Stderr)
SetOutput(INFO, os.Stderr)
SetOutput(DEBUG, os.Stderr)
SetOutput(TRACE, os.Stderr)

Output:

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. For more information on the inner workings of SetOutput* see the SetOutput() function.

Example 
SetOutputBetween(DEBUG, ERROR, os.Stderr)
// is equal to
SetOutput(DEBUG, os.Stderr)
SetOutput(INFO, os.Stderr)
SetOutput(WARNING, os.Stderr)
SetOutput(ERROR, os.Stderr)

Output:

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 added in v0.1.2 

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

Level is an alias to allow attaching functions to Loglevels. 

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

func ParseLevel added in v0.3.1 

func ParseLevel(level string, fallback Level) Level

ParseLevel takes in a string and returns the corresponding loglevel. If it does not exist, default is returned instead.

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.

Source Files

View all Source files

Directories

Path Synopsis
Package logrotation provides a writer that automatically rotates logfiles if the set maximum size is reached or exceeded.
 Package logrotation provides a writer that automatically rotates logfiles if the set maximum size is reached or exceeded.

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.