errorlogger

package module
v0.0.0-...-6f2a7b9 Latest Latest
Warning

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

 Go to latest Published: Apr 15, 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 Go 1.16.4. Updated to Go 1.18. 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 (

	// InfoLevel level. General operational entries about what's going on inside the
	// application.
	DefaultLogLevel Level = InfoLevel

	// 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

	// Discard is a Writer on which all Write calls succeed without doing anything.
	DiscardWriter io.Writer = io.Discard
)
View Source 
var AllLevels []Level = logrus.AllLevels

A constant exposing all logging levels

Reference: https://github.com/sirupsen/logrus

Functions

func Example 

func Example()

Types

type Entry 

type Entry = logrus.Entry

An entry is the final or intermediate Logrus logging entry. It contains all the fields passed with WithField{,s}. It's finally logged when Trace, Debug, Info, Warn, Error, Fatal or Panic is called on it. These objects can be reused and passed around as much as you wish to avoid field duplication.

type ErrorFunc 

type ErrorFunc = func(err error) error

ErrorFunc defines the function signature to choose the logging function.

type ErrorLogger 

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 

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 

func NewWithOptions(enabled bool, msg string, fn LoggerFunc, wrap error, logger *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 

type Fields = logrus.Fields

Fields type, used to pass to `WithFields`.

type Formatter 

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

var DefaultTextFormatter Formatter = NewTextFormatter()

DefaultTextFormatter is the default log formatter. Use 

Log.SetText()

or 

Log.SetFormatter(DefaultTextFormatter)

to return to default text formatting of logs.

To change to another logrus formatter, use 

Log.SetFormatter(myFormatter)

Reference: https://pkg.go.dev/github.com/sirupsen/logrus#TextFormatter

type JSONFormatter 

type JSONFormatter struct{ logrus.JSONFormatter }

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

func NewJSONFormatter 

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 

func (f *JSONFormatter) Formatter() Formatter

func (*JSONFormatter) SetCallerPrettyfier 

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 

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 

func (f *JSONFormatter) SetDisableHTMLEscape(yesno bool)

SetDisableHTMLEscape allows disabling html escaping in output

func (*JSONFormatter) SetDisableTimeStamp 

func (f *JSONFormatter) SetDisableTimeStamp(yesno bool)

SetDisableTimeStamp allows disabling automatic timestamps in output

func (*JSONFormatter) SetFieldMap 

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 

func (f *JSONFormatter) SetPrettyPrint(pretty bool)

SetPrettyPrint set to true will indent all json logs

func (*JSONFormatter) SetTimestampFormat 

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 Level 

type Level = logrus.Level

Level type

Reference: https://github.com/sirupsen/logrus 

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()`.

Reference: github.com/sirupsen/logrus

type Logger 

type Logger = logrus.Logger

Logger is the main structure used by errorlogger. It is a thinly veiled wrapper around logrus.Logger with some additional functionality. 

	type Logger struct {
    // The logs are `io.Copy`'d to this in a mutex. It's common to set this to a
    // file, or leave it default which is `os.Stderr`. You can also set this to
    // something more adventurous, such as logging to Kafka.
    Out io.Writer
    // Hooks for the logger instance. These allow firing events based on logging
    // levels and log entries. For example, to send errors to an error tracking
    // service, log to StatsD or dump the core on fatal errors.
    Hooks LevelHooks
    // All log entries pass through the formatter before logged to Out. The
    // included formatters are `TextFormatter` and `JSONFormatter` for which
    // TextFormatter is the default. In development (when a TTY is attached) it
    // logs with colors, but to a file it wouldn't. You can easily implement your
    // own that implements the `Formatter` interface, see the `README` or included
    // formatters for examples.
    Formatter Formatter

    // Flag for whether to log caller info (off by default)
    ReportCaller bool

    // The logging level the logger should log at. This is typically (and defaults
    // to) `logrus.Info`, which allows Info(), Warn(), Error() and Fatal() to be
    // logged.
    Level Level
    // Used to sync writing to the log. Locking is enabled by Default
    mu MutexWrap
    // Reusable empty entry
    entryPool sync.Pool
    // Function to exit the application, defaults to `os.Exit()`
    ExitFunc exitFunc
	}

type LoggerFunc 

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

LoggerFunc defines the function signature for logging functions.

type TextFormatter 

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 

func NewTextFormatter() *TextFormatter

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

func (*TextFormatter) SetCallerPrettyfier 

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 

func (f *TextFormatter) SetDisableColors(yesno bool)

SetDisableColors allows users to disable colors.

func (*TextFormatter) SetDisableLevelTruncation 

func (f *TextFormatter) SetDisableLevelTruncation(yesno bool)

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

func (*TextFormatter) SetDisableQuote 

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 

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 

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 

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 

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 

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 

func (f *TextFormatter) SetForceQuote(yesno bool)

SetForceQuote allows users to force quoting of all values.

func (*TextFormatter) SetFullTimeStamp 

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 

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 

func (f *TextFormatter) SetQuoteEmptyFields(yesno bool)

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

func (*TextFormatter) SetSortingFunc 

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

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

func (*TextFormatter) SetTimestampFormat 

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

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.