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

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 SetJSONFormatter

func SetJSONFormatter()

SetJSONFormatter sets the log formatter to a logrus JSON formatter with default characteristics. Use

Log.SetJSONFormatter(defaultTextFormatter)

to return to default text formatting of logs.

Many third party logging formatters are available.

- FluentdFormatter. Formats entries that can be parsed by Kubernetes and Google Container Engine.

- GELF. Formats entries so they comply to Graylog's GELF 1.1 specification.

- logstash. Logs fields as Logstash Events.

- prefixed. Displays log entry source along with alternative layout.

- zalgo. Invoking the Power of Zalgo.

- nested-logrus-formatter. Converts logrus fields to a nested structure.

- powerful-logrus-formatter. get fileName, log's line number and the latest function's name when print log; Sava log to files.

- caption-json-formatter. logrus's message json formatter with human-readable caption added.

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

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

SetTextFormatter sets the log formatter to the default text log formatter for use with TTY logging. Use

Log.SetJSONFormatter(defaultJSONFormatter)

to return to set JSON formatting of logs.

Many third party logging formatters are available.

- FluentdFormatter. Formats entries that can be parsed by Kubernetes and Google Container Engine.

- GELF. Formats entries so they comply to Graylog's GELF 1.1 specification.

- logstash. Logs fields as Logstash Events.

- prefixed. Displays log entry source along with alternative layout.

- zalgo. Invoking the Power of Zalgo.

- nested-logrus-formatter. Converts logrus fields to a nested structure.

- powerful-logrus-formatter. get fileName, log's line number and the latest function's name when print log; Sava log to files.

- caption-json-formatter. logrus's message json formatter with human-readable caption added. Reference: https://pkg.go.dev/github.com/sirupsen/logrus#TextFormatter

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

	// EnableJSON enables JSON formatting of log errors
	EnableJSON()

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