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()
• func SetLogOutput(w io.Writer) error
• func SetTextFormatter()
• type ErrorLogger
  • func New() ErrorLogger
  • func NewWithOptions(enabled bool, fn LoggerFunc, wrap error) ErrorLogger
• type Level
• type LoggerFunc
• type Options

Variables

var (
	// Log is the default global ErrorLogger. It implements the
	// ErrorLogger interface as well as the logrus.Logger interface,
	// which is compatible with the standard library "log" package.
	Log = New()

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

var ErrInvalidWriter = os.ErrInvalid

ErrInvalidWriter is returned when a log output writer is passed that does not implement io.Writer.

Functions

func Example

func Example()

func SetLogOutput

func SetLogOutput(w io.Writer) error

SetLogOutput sets the output writer for logging. The default is os.Stderr. Any io.Writer can be setup to receive messages.

func SetTextFormatter

func SetTextFormatter()

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)

	logrus.Ext1FieldLogger
}

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 EL is provided.

func NewWithOptions

func NewWithOptions(enabled bool, fn LoggerFunc, wrap error) ErrorLogger

NewWithOptions returns a new ErrorLogger with options determined by parameters.

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