errorlogger

README

errorlogger

Tricky and fun utilities for Go programs.

---

---

Getting Started

Prerequisites

• Go
• Git
• GitHub CLI

Developed with $( go version; ). Go is extremely backwards compatible and semver stable. Nearly any v1.x should work fine.

---

Installation

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

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

Clone this repo to test and contribute:

# 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 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 logrus log (or a standard library log) by providing a convenient way to log errors and to temporarily disable/enable logging.

A global Log and Err with default behaviors are supplied that may be aliased if you wish:

Log = errorlogger.Log
Err = errorlogger.Err

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

var Err = errorlogger.New().Err

then, just call the function:

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

Either way, the default ErrorLogger is enabled and ready to go:

EL := errorlogger.New() // enabled by default
Err := EL.Err

If a private ErrorLogger is desired, or if name collisions with Err cause conflicts, you may implement your own.

myErr := errorlogger.New()
err := myErr.Err

Example:

 f, err := os.Open("somefile.txt")
 if err != nil {
	 return nil, e.Err(err) // avoids additional logging steps
 }
 e.Disable() // can be disabled and enabled as desired

Index

• Variables
• func Example()
• type ErrorLogger
  • func New() ErrorLogger
  • func NewWithOptions(enabled bool, fn LoggerFunc, wrap error) ErrorLogger
• type Level
• type LoggerFunc
• type LogrusCommonOptions
• type LogrusLogFunctions
• type LogrusLogger
• type LogrusLoggerComplete
• type LogrusOptions
• type Options

Variables

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
)

Functions

func Example

func Example()

Types

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

	// SetOptions accepts an Options set and adjust the
	// ErrorLogger options accordingly. Any options that are not included are ignored. The Options struct has methods for managing, saving and loading Options sets.
	SetOptions(o Options) error

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

	LogrusLogger
}

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, fn LoggerFunc, wrap error) ErrorLogger

NewWithOptions returns a new ErrorLogger with options determined by parameters.

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

type Level

type Level = logrus.Level

Level type values: Panic, Fatal, Error, Warn, Info, Debug, Trace

type LoggerFunc

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

LoggerFunc defines the function signature used when logging errors.

type LogrusCommonOptions

type LogrusCommonOptions interface {
	SetLevel(level Level)
	GetLevel() Level
	SetFormatter(formatter logrus.Formatter)
	SetOutput(output io.Writer)
}

LogrusCommonOptions implements several common options that should be in the basic LogrusLogger interface.

type LogrusLogFunctions

type LogrusLogFunctions interface {
	DebugFn(fn logrus.LogFunction)
	InfoFn(fn logrus.LogFunction)
	PrintFn(fn logrus.LogFunction)
	WarnFn(fn logrus.LogFunction)
	WarningFn(fn logrus.LogFunction)
	ErrorFn(fn logrus.LogFunction)
	FatalFn(fn logrus.LogFunction)
	PanicFn(fn logrus.LogFunction)
}

LogrusLogFunctions implements logrus Logrus LogFunctions. Instead of using this directly, create your own custom interface that uses the options required.

type LogrusLogger

type LogrusLogger interface {
	logrus.FieldLogger
	LogrusCommonOptions
}

LogrusLogger implements the most common functionality of the logging interface of the Logrus package.

It is a compatible superset of the standard library log package and a compatible subset of the ErrorLogger package.

type LogrusLoggerComplete

type LogrusLoggerComplete interface {
	LogrusLogger
	LogrusOptions
	LogrusLogFunctions
}

LogrusLoggerComplete implements the complete exported interface implemented by the logrus.Logger struct.

Most users will not need to use this. ErrorLogger contains the most common functionality, including the basic LogrusLogger interface.

type LogrusOptions

type LogrusOptions interface {
	WithContext(ctx context.Context) *logrus.Entry
	WithTime(t time.Time) *logrus.Entry
	Exit(code int)
	SetNoLock()
	AddHook(hook logrus.Hook)
	IsLevelEnabled(level Level) bool
	SetReportCaller(reportCaller bool)
	ReplaceHooks(hooks logrus.LevelHooks) logrus.LevelHooks
}

LogrusOptions implements rarely used logging options. Instead of using this directly, create your own custom interface that uses the options required.

type Options

type Options struct {
	// Width is an max column width for single line arrays
	// Default is 80
	Width int
	// Prefix is a prefix for all lines
	// Default is an empty string
	Prefix string
	// Indent is the nested indentation
	// Default is two spaces
	Indent string
	// SortKeys will sort the keys alphabetically
	// Default is false
	SortKeys bool
}

Options is Pretty options