errorlogger

package module
v0.5.0 Latest Latest
Warning

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

 Go to latest Published: Mar 16, 2022 License: MIT Imports: 9 Imported by: 0

README

errorlogger

Tricky and fun utilities for Go programs.

GitHub Workflow Status Codecov

Contributor Covenant

Twitter Follow GitHub followers

Getting Started

Prerequisites

Developed with 1.16.4. Go is extremely backwards compatible and semver stable. Nearly any v1.x should work fine.

Installation

To build and install this package as a utility on your machine.

# add repo to $GOPATH (xxxxxx is your computer login username)
go get github.com/xxxxxx/errorlogger

cd ${GOPATH}/src/github.com/xxxxxx/errorlogger

# test results and coverage info
./go.test.sh

# install as a utility package
go install
Use Template

To use this repo as a template for your own project:

gh repo create -y --public --template "https://github.com/skeptycal/errorlogger"
Contributing

To clone this repo to test and contribute, use git clone or gh clone.

gh repo clone skeptycal/errorlogger

cd errorlogger

git branch -b dev

Use the Issues and PR templates on the GitHub repo page to contribute.

Basic Usage

This is a copy of the example script available in the cmd/example/errorlogger folder:

package main

import "github.com/skeptycal/errorlogger"

func main() {
    errorlogger.Example()
}

To try it out:

# change to the sample folder
cd cmd/example/errorlogger

# run the main.go program
go run ./main.go

# to compile as an executable
go build

Code of Conduct and Contributing

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us. Please read the Code of Conduct for details before submitting anything.

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

Contributors and Inspiration

  • Michael Treanor (GitHub / Twitter) - Initial work, updates, maintainer
  • Francesc Campoy - Inspiration and great YouTube videos!

See also the list of contributors who participated in this project.

License

Licensed under the MIT https://opensource.org/licenses/MIT - see the LICENSE file for details.

Documentation

Overview

Package errorlogger implements error logging to a variety of output formats. The goal of this package is to provide a simple and efficient mechanism for managing, testing, debugging, and changing options for error logging throughout a program.

It is a drop-in replacement for the standard library log package and the popular Logrus package.

Code like this works as expected without any changes: 

log.Errorf("this is an error: %v", err)
log.Fatal("no input file provided.")

Usage

A global logger with a default logging function is supplied: 

var log = errorlogger.Log
log.Error("sample log error message")

using the variable 'log' matches most code using the standard library 'log' package or Logrus package.

Logging

The default global error logging function is supplied. 

var Err = errorlogger.Err

Err wraps errors, adds custom messages, formats errors, and outputs messages to the correct io.Writer as specified in the options.

Calling this function will perform all package-level logging and error wrapping. It will then return the error otherwise unchanged and ready to propagate up.

If you do not intend to use any options or disable the logger, it may be more convenient to use only the function alias to call the most common method, Err(), like this: 

var Err = errorlogger.Err

then, just call the function within error blocks: 

err := someProcess(stuff)
if err != nil {
 return Err(err)
}

or 

return Err(someProcess(stuff))

or even this 

_ = Err(someProcess(stuff)) // log errors only and continue

if the error does not need to be propagated (bubbled) up. (This is not generally recommended.)

Examples

file open 

f, err := os.Open("myfile")
if err != nil {
	return Err(err)
}

get environment variable 

env := os.Getenv("PATH")
if env == "" {
	return "", Err(os.ErrNotExist)
}
return env, nil

check return value while returning an error 

return Err(os.Chmod("myfile", 420))

Defaults

The global defaults may be aliased if there is a concern about name collisions: 

var LogThatWontConflict = errorlogger.Log
var ErrThatWontConflict = errorlogger.Err

By default, logging is enabled and ANSI colorized text is sent to stderr of the TTY. If it is changed and you wish to return to the default text formatter, use 

log.SetText()

Logging can also be redirected to a file or any io.Writer 

log.SetLogOutput(w io.Writer)

To create a new logger with default behaviors, use: 

var log = errorlogger.New()

and start logging!

(The defaults are output to os.Stderr, ANSI color, include timestamps, logging enabled, default log level(INFO), no error wrapping, default log function, and use default Logrus logger as pass-through.)

Customize

If you want to customize the logger, use: 

NewWithOptions(enabled bool, fn LoggerFunc, wrap error, logger interface{}) ErrorLogger

Some additional features of this package include:

  • easy configuration of JSON logging: log.EnableJSON(true) // true for pretty printing
  • return to the default text formatting log.SetText() // change to default text formatter
  • easy configuration of custom output formatting: log.SetFormatter(myJSONformatter) // set a custom formatter

- easy configuration of numerous third party formatters.

- Set log level - the verbosity of the logging may be adjusted. Allowed values are Panic, Fatal, Error, Warn, Info, Debug, Trace. The default is "Info" 

log.SetLogLevel("INFO") // Set log level - uppercase string ...
log.SetLogLevel("error") // ... or lowercase string accepted

Performance

Error logging may be disabled during performance critical operations: 

log.Disable() // temporarily disable logging
defer log.Enable()  // enable logging after critical code

In this case, the error function is replaced with a noop function. This removed any enabled/disabled check and usually results in a performance gain when compared to checking a flag during every possible operation that may request logging.

Logging is deferred or reenabled with 

log.Enable() // after performance sensitive portion, enable logging

This may be done at any time and as often as desired.

- SetLoggerFunc allows setting of a custom logger function. The default is log.Error(), which is compatible with the standard library log package and logrus. 

log.SetLoggerFunc(fn LoggerFunc)

- SetErrorWrap allows ErrorLogger to wrap errors in a specified custom type for use with errors.Is(): 

log.SetErrorWrap(wrap error)

For example, if you want all errors returned to be considered type *os.PathError, use: 

log.SetErrorWrap(&os.PathError{})

To wrap all errors in a custom type, use: 

log.SetErrorWrap(myErrType{}) // wrap all errors in a custom type

Index

Constants

View Source 
const (

	// DefaultTimestampFormat is time.RFC3339FA
	//
	// Note that this is not the most current standard but it is the
	// most stable and recommended with the Go standard library.
	//
	// Additional notes
	//
	// The RFC822, RFC850, and RFC1123 formats should be applied only to
	// local times. Applying them to UTC times will use "UTC" as the time
	// zone abbreviation, while strictly speaking those RFCs require the
	// use of "GMT" in that case.
	//
	// In general RFC1123Z should be used instead of RFC1123 for servers
	// that insist on that format, and RFC3339 should be preferred for
	// new protocols.
	//
	// While RFC3339, RFC822, RFC822Z, RFC1123, and RFC1123Z are useful
	// for formatting, when used with time.Parse they do not accept all
	// the time formats permitted by the RFCs and they do accept time
	// formats not formally defined.
	//
	// The RFC3339Nano format removes trailing zeros from the seconds
	// field and thus may not sort correctly once formatted.
	DefaultTimestampFormat string = time.RFC3339
)

Variables

View Source 
var (
	// Log is the default global ErrorLogger. It implements
	// the ErrorLogger interface as well as the basic
	// logrus.Logger interface, which is compatible with the
	// standard library "log" package.
	//
	// In the case of name collisions with 'Log', use an alias
	// instead of creating a new instance. For example:
	//  var mylogthatwontmessthingsup = errorlogger.Log
	Log = New()

	// Err is the logging function for the global ErrorLogger.
	Err = Log.Err

	// ErrInvalidWriter is returned when an output writer is
	// nil or does not implement io.Writer.
	ErrInvalidWriter = os.ErrInvalid

	// DefaultLogFunc is Log.Error, which will log messages
	// of level ErrorLevel or higher.
	DefaultLogFunc LoggerFunc = defaultlogger.Error

	// DefaultErrWrap is the default error used to wrap
	// errors processed with Err. A <nil> value disables
	// error wrapping.
	DefaultErrWrap error = nil
)
View Source 
var (
	// A constant exposing all logging levels
	AllLevels = logrus.AllLevels
)

Functions

func Example 

func Example()

Types

type Entry added in v0.2.1 

type Entry = logrus.Entry

type ErrorFunc added in v0.4.0 

type ErrorFunc = func(err error) error

ErrorFunc defines the function signature to choose the logging function.

type ErrorLogger added in v0.2.0 

type ErrorLogger interface {

	// Disable disables logging and sets a no-op function for
	// Err() to prevent slowdowns while logging is disabled.
	Disable()

	// Enable enables logging and restores the Err() logging functionality.
	Enable()

	// EnableText enables text formatting of log errors (default)
	SetText()

	// EnableJSON enables JSON formatting of log errors
	SetJSON(pretty bool)

	// LogLevel sets the logging level from a string value.
	// Allowed values: Panic, Fatal, Error, Warn, Info, Debug, Trace
	SetLogLevel(lvl string) error

	// Err logs an error to the provided logger, if it is enabled,
	// and returns the error unchanged.
	Err(err error) error

	// SetLoggerFunc allows setting of the logger function.
	// The default is log.Error(), which is compatible with
	// the standard library log package and logrus.
	SetLoggerFunc(fn LoggerFunc)

	// SetErrorWrap allows ErrorLogger to wrap errors in a
	// specified custom type. For example, if you want all errors
	// returned to be of type *os.PathError
	SetErrorWrap(wrap error)

	// SetCustomMessage allows automated addition of a custom
	// message to all log messages generated by this
	// logger.
	SetCustomMessage(msg string)
	// contains filtered or unexported methods
}

ErrorLogger implements error logging to a logrus log (or a standard library log) by providing convenience methods, advanced formatting options, more automated logging, a more efficient way to log errors within code, and methods to temporarily disable/enable logging, such as in the case of performance optimization or during critical code blocks.

func New added in v0.2.0 

func New() ErrorLogger

New returns a new ErrorLogger with default options and logging enabled. Most users will not need to call this, since the default global ErrorLogger 'Log' is provided.

In the case of name collisions with 'Log', use an alias instead of creating a new instance. For example: 

var mylogthatwontmessthingsup = errorlogger.Log

func NewWithOptions added in v0.2.0 

func NewWithOptions(enabled bool, msg string, fn LoggerFunc, wrap error, logger *logrus.Logger) ErrorLogger

NewWithOptions returns a new ErrorLogger with options determined by parameters. To use defaults, use nil for any option except 'enabled'.

- enabled: defines the initial logging state.

- fn: defines a custom logging function used to log information.

- wrap: defines a custom error type to wrap all errors in.

- logger: defines a custom logger to use.

type Fields added in v0.2.1 

type Fields = logrus.Fields

type Formatter added in v0.2.1 

type Formatter interface{ logrus.Formatter }

The Formatter interface is used to implement a custom Formatter. It takes an `Entry`. It exposes all the fields, including the default ones:

* `entry.Data["msg"]`. The message passed from Info, Warn, Error .. * `entry.Data["time"]`. The timestamp. * `entry.Data["level"]. The level the entry was logged at.

Any additional fields added with `WithField` or `WithFields` are also in `entry.Data`. Format is expected to return an array of bytes which are then logged to `logger.Out`.

Reference: logrus@v1.8.1 formatter.go 

type Formatter interface {
	Format(*Entry) ([]byte, error)
}

type JSONFormatter added in v0.3.1 

type JSONFormatter struct{ logrus.JSONFormatter }

JSONFormatter formats logs into parsable json. It is composed of logrus.JSONFormatter with additional formatting methods.

func NewJSONFormatter added in v0.3.1 

func NewJSONFormatter(pretty bool) *JSONFormatter

NewJSONFormatter returns a new Formatter that is initialized and ready to use.

For pretty printing, set pretty == true.

func (*JSONFormatter) Formatter added in v0.5.0 

func (f *JSONFormatter) Formatter() Formatter

func (*JSONFormatter) SetCallerPrettyfier added in v0.3.1 

func (f *JSONFormatter) SetCallerPrettyfier(fn func(*runtime.Frame) (function string, file string))

SetCallerPrettyfier sets the user option to modify the content of the function and file keys in the json data when ReportCaller is activated. If any of the returned values is the empty string the corresponding key will be removed from json fields.

func (*JSONFormatter) SetDataKey added in v0.3.1 

func (f *JSONFormatter) SetDataKey(key string)

SetDataKey allows users to put all the log entry parameters into a nested dictionary at a given key.

func (*JSONFormatter) SetDisableHTMLEscape added in v0.3.1 

func (f *JSONFormatter) SetDisableHTMLEscape(yesno bool)

SetDisableHTMLEscape allows disabling html escaping in output

func (*JSONFormatter) SetDisableTimeStamp added in v0.3.1 

func (f *JSONFormatter) SetDisableTimeStamp(yesno bool)

SetDisableTimeStamp allows disabling automatic timestamps in output

func (*JSONFormatter) SetFieldMap added in v0.3.1 

func (f *JSONFormatter) SetFieldMap(m logrus.FieldMap)

SetFieldMap allows users to customize the names of keys for default fields. For example: 

 formatter := &JSONFormatter{
  	FieldMap: FieldMap{
		 FieldKeyTime:  "@timestamp",
		 FieldKeyLevel: "@level",
		 FieldKeyMsg:   "@message",
		 FieldKeyFunc:  "@caller",
   },
 }

func (*JSONFormatter) SetPrettyPrint added in v0.3.1 

func (f *JSONFormatter) SetPrettyPrint(pretty bool)

SetPrettyPrint set to true will indent all json logs

func (*JSONFormatter) SetTimestampFormat added in v0.3.1 

func (f *JSONFormatter) SetTimestampFormat(fmt string)

SetTimestampFormat sets the format used for marshaling timestamps. The format to use is the same as for time.Format or time.Parse from the standard library. The standard Library already provides a set of predefined formats. The recommended and default format is RFC3339.

type LenWriter added in v0.5.0 

type LenWriter struct{}

func (LenWriter) Write added in v0.5.0 

func (LenWriter) Write(b []byte) (n int, err error)

nopWriter_Write returns 0, nil no matter what the input is.

type Level added in v0.2.0 

type Level = logrus.Level

Level type 

const (
	// PanicLevel level, highest level of severity. Logs and then calls panic with the
	// message passed to Debug, Info, ...
	PanicLevel Level = iota
	// FatalLevel level. Logs and then calls `logger.Exit(1)`. It will exit even if the
	// logging level is set to Panic.
	FatalLevel
	// ErrorLevel level. Logs. Used for errors that should definitely be noted.
	// Commonly used for hooks to send errors to an error tracking service.
	ErrorLevel
	// WarnLevel level. Non-critical entries that deserve eyes.
	WarnLevel
	// InfoLevel level. General operational entries about what's going on inside the
	// application.
	InfoLevel
	// DebugLevel level. Usually only enabled when debugging. Very verbose logging.
	DebugLevel
	// TraceLevel level. Designates finer-grained informational events than the Debug.
	TraceLevel
)

These are the different logging levels. You can set the logging level to log on your instance of logger, obtained with `logrus.New()`.

type LoggerFunc added in v0.2.0 

type LoggerFunc = func(args ...interface{})

LoggerFunc defines the function signature for logging functions.

type MutexEnable added in v0.5.0 

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

func (*MutexEnable) Disable added in v0.5.0 

func (mw *MutexEnable) Disable()

func (*MutexEnable) Enable added in v0.5.0 

func (mw *MutexEnable) Enable()

func (*MutexEnable) Lock added in v0.5.0 

func (mw *MutexEnable) Lock()

func (*MutexEnable) Unlock added in v0.5.0 

func (mw *MutexEnable) Unlock()

type MutexWrap added in v0.5.0 

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

func (*MutexWrap) Disable added in v0.5.0 

func (mw *MutexWrap) Disable()

func (*MutexWrap) Lock added in v0.5.0 

func (mw *MutexWrap) Lock()

func (*MutexWrap) Unlock added in v0.5.0 

func (mw *MutexWrap) Unlock()

type NopWriter added in v0.5.0 

type NopWriter struct{}

func (NopWriter) Write added in v0.5.0 

func (NopWriter) Write(b []byte) (n int, err error)

nopWriter_Write returns 0, nil no matter what the input is.

type TextFormatter added in v0.3.1 

type TextFormatter struct {
	logrus.TextFormatter
}

TextFormatter formats logs into text. Note: this is a logrus type with marginally useful utilities and may become a type alias in the future. 

type TextFormatter struct {
	// Set to true to bypass checking for a TTY before outputting colors.
	ForceColors bool

	// Force disabling colors.
	DisableColors bool

	// Force quoting of all values
	ForceQuote bool

	// DisableQuote disables quoting for all values.
	// DisableQuote will have a lower priority than ForceQuote.
	// If both of them are set to true, quote will be forced on all values.
	DisableQuote bool

	// Override coloring based on CLICOLOR and CLICOLOR_FORCE.
	// Reference: https://bixense.com/clicolors/
	EnvironmentOverrideColors bool

	// Disable timestamp logging. useful when output is redirected to logging
	// system that already adds timestamps.
	DisableTimestamp bool

	// Enable logging the full timestamp when a TTY is attached instead of just
	// the time passed since beginning of execution.
	FullTimestamp bool

	// TimestampFormat to use for display when a full timestamp is printed.
	// The format to use is the same than for time.Format or time.Parse from the standard
	// library.
	// The standard Library already provides a set of predefined format.
	TimestampFormat string

	// The fields are sorted by default for a consistent output. For applications
	// that log extremely frequently and don't use the JSON formatter this may not
	// be desired.
	DisableSorting bool

	// The keys sorting function, when uninitialized it uses sort.Strings.
	SortingFunc func([]string)

	// Disables the truncation of the level text to 4 characters.
	DisableLevelTruncation bool

	// PadLevelText Adds padding the level text so that all the levels output at the same length
	// PadLevelText is a superset of the DisableLevelTruncation option
	PadLevelText bool

	// QuoteEmptyFields will wrap empty fields in quotes if true
	QuoteEmptyFields bool

	// Whether the logger's out is to a terminal
	isTerminal bool

	// FieldMap allows users to customize the names of keys for default fields.
	// As an example:
	// formatter := &TextFormatter{
	//     FieldMap: FieldMap{
	//         FieldKeyTime:  "@timestamp",
	//         FieldKeyLevel: "@level",
	//         FieldKeyMsg:   "@message"}}
	FieldMap FieldMap

	// CallerPrettyfier can be set by the user to modify the content
	// of the function and file keys in the data when ReportCaller is
	// activated. If any of the returned value is the empty string the
	// corresponding key will be removed from fields.
	CallerPrettyfier func(*runtime.Frame) (function string, file string)

	terminalInitOnce sync.Once

	// The max length of the level text, generated dynamically on init
	levelTextMaxLength int
}

func NewTextFormatter added in v0.3.1 

func NewTextFormatter() *TextFormatter

NewTextFormatter returns a new TextFormatter that is initialized and ready to use.

func (*TextFormatter) SetCallerPrettyfier added in v0.3.1 

func (f *TextFormatter) SetCallerPrettyfier(fn func(*runtime.Frame) (function string, file string))

SetCallerPrettyfier sets the user option to modify the content of the function and file keys in the data when ReportCaller is activated. If any of the returned values is the empty string the corresponding key will be removed from fields.

func (*TextFormatter) SetDisableColors added in v0.3.1 

func (f *TextFormatter) SetDisableColors(yesno bool)

SetDisableColors allows users to disable colors.

func (*TextFormatter) SetDisableLevelTruncation added in v0.3.1 

func (f *TextFormatter) SetDisableLevelTruncation(yesno bool)

SetDisableLevelTruncation allows users to disable the truncation of the level text to 4 characters.

func (*TextFormatter) SetDisableQuote added in v0.3.1 

func (f *TextFormatter) SetDisableQuote(yesno bool)

SetDisableQuote allows users to disable quoting for all values. It has a lower priority than SetForceQuote, i.e. if both of them are set to true, quotes will be forced on for all values.

func (*TextFormatter) SetDisableSorting added in v0.3.1 

func (f *TextFormatter) SetDisableSorting(yesno bool)

SetDisableSorting allows users to disable the default behavior of sorting of fields by default for a consistent output. For applications that log extremely frequently and don't use the JSON formatter this may not be desired.

func (*TextFormatter) SetDisableTimeStamp added in v0.3.1 

func (f *TextFormatter) SetDisableTimeStamp(yesno bool)

SetDisableTimeStamp allows users to disable automatic timestamp logging. Useful when output is redirected to logging systems that already add timestamps.

func (*TextFormatter) SetEnvironmentOverrideColors added in v0.3.1 

func (f *TextFormatter) SetEnvironmentOverrideColors(yesno bool)

SetEnvironmentOverrideColors allows users to override coloring based on CLICOLOR and CLICOLOR_FORCE. - https://bixense.com/clicolors/

func (*TextFormatter) SetFieldMap added in v0.3.1 

func (f *TextFormatter) SetFieldMap(m logrus.FieldMap)

SetFieldMap allows users to customize the names of keys for default fields. For example: 

 formatter := &TextFormatter{
  	FieldMap: FieldMap{
		 FieldKeyTime:  "@timestamp",
		 FieldKeyLevel: "@level",
		 FieldKeyMsg:   "@message",
		 FieldKeyFunc:  "@caller",
   },
 }

func (*TextFormatter) SetForceColors added in v0.3.1 

func (f *TextFormatter) SetForceColors(yesno bool)

SetForceColors allows users to bypass checking for a TTY before outputting colors and forces color output.

func (*TextFormatter) SetForceQuote added in v0.3.1 

func (f *TextFormatter) SetForceQuote(yesno bool)

SetForceQuote allows users to force quoting of all values.

func (*TextFormatter) SetFullTimeStamp added in v0.3.1 

func (f *TextFormatter) SetFullTimeStamp(yesno bool)

SetFullTimeStamp allows users to enable logging the full timestamp when a TTY is attached instead of just the time passed since beginning of execution.

func (*TextFormatter) SetPadLevelText added in v0.3.1 

func (f *TextFormatter) SetPadLevelText(yesno bool)

SetPadLevelText allows users to enable the addition of padding to the level text so that all the levels output at the same length PadLevelText is a superset of the DisableLevelTruncation option

func (*TextFormatter) SetQuoteEmptyFields added in v0.3.1 

func (f *TextFormatter) SetQuoteEmptyFields(yesno bool)

SetQuoteEmptyFields allows users to enable the wrapping of empty fields in quotes.

func (*TextFormatter) SetSortingFunc added in v0.3.1 

func (f *TextFormatter) SetSortingFunc(fn func([]string))

SetSortingFunc allows users to set the keys sorting function. The default is sort.Strings.

func (*TextFormatter) SetTimestampFormat added in v0.3.1 

func (f *TextFormatter) SetTimestampFormat(fmt string)

SetTimestampFormat sets the format for display when a full timestamp is printed. The format to use is the same than for time.Format or time.Parse from the standard library. The standard Library already provides a set of predefined formats. The recommended and default format is time.RFC3339.

Source Files

View all Source files

Directories

Path Synopsis
cmd
example/errorlogger command
Example for package errorlogger.
 Example for package errorlogger.
example/executable command
example/executable/osargsutils

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.