alog

package module
v1.0.6 Latest Latest
Warning

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

Go to latest
Published: Mar 9, 2021 License: MIT Imports: 11 Imported by: 0

README

Fully concurrent, non-IO blocking Logger for Go

CI Go Report Card codecov Go Reference PRs Welcome

Usage

Installation:

go get -u devnw.com/alog

alog

is an implementation of a fully concurrent non-IO blocking log library. Internally messages are routed through a number of subscribed destinations consisting of destination log levels, timezone formatting strings and an io.Writer for the destination to be written to.

The globally available functions utilize a singleton implementation of a global logger that is initialized when the package is loaded. This global logger utilizes os.Stdout for INFO, DEBUG, TRACE, WARN, CUSTOM logs, and os.Stderr for ERROR, CRITICAL, FATAL as defined in the method Standard()

The global logger singleton can be overridden using the "Global" method passing in the proper parameters as required by your use case.

If you prefer to use a non-global singleton logger you can use the "New" method to create a new logger which implements the alog packages "Logger" interface which can be passed throughout an application as a logger.

Each log level has an associated function:

  • INFO - Print, Printf, Println, Printc
  • DEBUG - Debug, Debugf, Debugln, Debugc
  • TRACE - Trace, Tracef, Traceln, Tracec
  • WARN - Warn, Warnf, Warnln, Warnc
  • ERROR - Error, Errorf, Errorln, Errorc
  • CRITICAL - Crit, Critf, Critln, Critc
  • FATAL - Fatal, Fatalf, Fatalln, Fatalc
  • CUSTOM Level - Custom, Customf, Customln, Customc

c(channel) functions are special methods in the logger that rather than being called directly are passed a channel which receives logs into the logger in a concurrent manner without direct calls to the c(channel) function again afterwards. These methods are particularly useful for applications where the overhead of a logger in concurrent actions is a particular nuisance. For these cases the c(channel) functions are a perfect use case. Each log level supports it's own c(channel) function.

This library currently support two log formatting types

  • STD: Formats your logs using a "PREFIX DATE [LEVEL] Log | err: Error"
  • JSON: Formats your logs using JSON in the following form
{
    "prefix":"PREFIX",
    "type":"ERROR",
    "timestamp":"2020-03-01T16:21:28-06:00",
    "error":"Error Message",
    "messages":["Log Message 1", "Log Message 2"]
}

Global Usage:


alog.Println("info log")
alog.Debugln(err, "debug log")
alog.Traceln(err, "trace log")
alog.Warnln(err, "warn log")
alog.Errorln(err, "err log")
alog.Critln(err, "critcal log")
alog.Fatalln(err, "fatal log")
alog.Customln("CUSTOM", err, "debug log")

For applications that want to ensure log completeness using alog execute alog.Wait(bool) when cleaning up your application so that the logger can correctly cleanup any lingering channels and Go routines. The boolean parameter let's the wait method know if you want to also close the logger internally.

Documentation

Overview

Package alog is an implementation of a fully concurrent non-IO blocking log library. Internally messages are routed through a number of subscribed destinations consisting of destination log levels, timezone formatting strings and an io.Writer for the destination to be written to.

The globally available functions utilize a singleton implementation of a global logger that is initialized when the package is loaded. This global logger utilizes os.Stdout for INFO, DEBUG, TRACE, WARN, CUSTOM logs, and os.Stderr for ERROR, CRITICAL, FATAL as defined in the method Standard()

The global logger singleton can be overridden using the "Global" method passing in the proper parameters as required by your use case.

If you prefer to use a non-global singleton logger you can use the "New" method to create a new logger which implements the alog packages "Logger" interface which can be passed throughout an application as a logger.

Each log level has an associated function:

INFO - Print, Printf, Println, Printc

DEBUG - Debug, Debugf, Debugln, Debugc

TRACE - Trace, Tracef, Traceln, Tracec

WARN - Warn, Warnf, Warnln, Warnc

ERROR - Error, Errorf, Errorln, Errorc

CRITICAL - Crit, Critf, Critln, Critc

FATAL - Fatal, Fatalf, Fatalln, Fatalc

CUSTOM Level - Custom, Customf, Customln, Customc

c(channel) functions are special methods in the logger that rather than being called directly are passed a channel which receives logs into the logger in a concurrent manner without direct calls to the `c(channel) function` again afterwards. These methods are particularly useful for applications where the overhead of a logger in concurrent actions is a particular nuisance. For these cases the c(channel) functions are a perfect use case. Each log level supports it's own c(channel) function.

alog currently support two log formatting types * STD => Formats your logs using a "PREFIX DATE [LEVEL] Log | err: Error" * JSON => Formats your logs using JSON in the following form `{"prefix":"PREFIX","type":"ERROR","timestamp":"2020-03-01T16:21:28-06:00","error":"ERROR","messages":["ERROR"]}`

Index

Constants

View Source
const (
	// DEFAULTBUFFER is the global default for buffer size on the async logger
	DEFAULTBUFFER = 0

	// DEFAULTTIMEFORMAT is the global default time format used by the async logger
	DEFAULTTIMEFORMAT = time.RFC3339
)

Variables

This section is empty.

Functions

func Close

func Close()

Close cancels the context throughout the logger and closes all read / write operations across the logger and IO

func Crit

func Crit(err error, v ...interface{})

Crit creates critical logs using the error and other values passed in

func Critc

func Critc(ctx context.Context, v <-chan interface{})

Critc creates critical logs based on the data coming from the concurrency channel that is passed in for processing

func Critf

func Critf(err error, format string, v ...interface{})

Critf creates a critical log using the error passed in, along with the string formatting and values

func Critln

func Critln(err error, v ...interface{})

Critln creates critical logs using the error and other values passed in. Each error and value is printed on a different line

func Custom

func Custom(ltype string, err error, v ...interface{})

Custom creates a custom log using the error and values passed into the method

func Customc

func Customc(ctx context.Context, v <-chan interface{}, ltype string)

Customc creates custom logs based on the data coming from the concurrency channel that is passed in for processing

func Customf

func Customf(ltype string, err error, format string, v ...interface{})

Customf creates a custom log using the error passed in, along with the string formatting and values

func Customln

func Customln(ltype string, err error, v ...interface{})

Customln creates custom logs using the error and other values passed in. Each error and value is printed on a different line

func Debug

func Debug(err error, v ...interface{})

Debug creates debugging logs based on the inputs

func Debugc

func Debugc(ctx context.Context, v <-chan interface{})

Debugc creates debug logs based on the data coming from the concurrency channel that is passed in for processing

func Debugf

func Debugf(err error, format string, v ...interface{})

Debugf creates an debugging log using the format and values

func Debugln

func Debugln(err error, v ...interface{})

Debugln prints the data coming in as a debug log on individual lines

func Error

func Error(err error, v ...interface{})

Error creates an error log using the error and other values passed in

func Errorc

func Errorc(ctx context.Context, v <-chan interface{})

Errorc creates error logs based on the data coming from the concurrency channel that is passed in for processing

func Errorf

func Errorf(err error, format string, v ...interface{})

Errorf creates an error log using the error passed in, along with the string formatting and values

func Errorln

func Errorln(err error, v ...interface{})

Errorln creates error logs using the error and other values passed in. Each error and value is printed on a different line

func Fatal

func Fatal(err error, v ...interface{})

Fatal creates a fatal log using the error and values passed into the method

func Fatalc

func Fatalc(ctx context.Context, v <-chan interface{})

Fatalc creates fatal logs based on the data coming from the concurrency channel that is passed in for processing

func Fatalf

func Fatalf(err error, format string, v ...interface{})

Fatalf creates an error log using the error passed in, along with the string formatting and values

func Fatalln

func Fatalln(err error, v ...interface{})

Fatalln creates fatal logs using the error and other values passed in. Each error and value is printed on a different line

func Global

func Global(
	ctx context.Context,
	prefix string,
	dateformat string,
	location *time.Location,
	buffer int,
	destinations ...Destination,
) error

Global instantiates a new logger using the passed in parameters and overwrites the package global instance of the logger

func Print

func Print(v ...interface{})

Print creates informational logs based on the inputs

func Printc

func Printc(ctx context.Context, v <-chan interface{})

Printc creates informational logs based on the data coming from the concurrency channel that is passed in for processing

func Printf

func Printf(format string, v ...interface{})

Printf creates an informational log using the format and values

func Println

func Println(v ...interface{})

Println prints the data coming in as an informational log on individual lines

func Trace

func Trace(err error, v ...interface{})

Trace creates trace logs based on the inputs

func Tracec

func Tracec(ctx context.Context, v <-chan interface{})

Tracec creates trace logs based on the data coming from the concurrency channel that is passed in for processing

func Tracef

func Tracef(err error, format string, v ...interface{})

Tracef creates an trace log using the format and values

func Traceln

func Traceln(err error, v ...interface{})

Traceln prints the data coming in as a trace log on individual lines

func Wait

func Wait(exit bool)

Wait blocks on the logger context until the context is closed

func Warn

func Warn(err error, v ...interface{})

Warn creates a warning log using the error passed in along with the values passed in

func Warnc

func Warnc(ctx context.Context, v <-chan interface{})

Warnc creates warning logs based on the data coming from the concurrency channel that is passed in for processing

func Warnf

func Warnf(err error, format string, v ...interface{})

Warnf creates a warning log using the error passed in, along with the string formatting and values

func Warnln

func Warnln(err error, v ...interface{})

Warnln creates a warning log using the error and values passed in. Each error and value is printed on a different line

Types

type Destination

type Destination struct {
	Types  LogLevel
	Format LogFmt
	Writer io.Writer
}

Destination is the destination struct for registering io.Writers to the alog library so that different log types can be passed to each writer asynchronously

func BenchDestinations

func BenchDestinations() []Destination

BenchDestinations returns a list of destinations for benchmarking. The destination returned from this method does NOTHING. It is meant to remove overhead from the logger for proper benchmarks. This destination can be used to override the logger for benchmarking.

func Standards

func Standards() []Destination

Standards returns the standard out and standard error destinations for quick access when creating a logger INFO, DEBUG, TRACE, WARNING, CUSTOM Logs are logged to Standard Out ERROR, CRITICAL, FATAL Logs are logged to Standard Error

func TestDestinations

func TestDestinations(ctx context.Context, t *testing.T) []Destination

TestDestinations returns a list of destinations for logging test data to the *testing.T that was passed in. This defaults all ERROR, CRIT, FATAL logs to the t.Error and the rest are routed to t.Log. These destinations can be used to override the logger with destinations specific to testing.

type LogFmt

type LogFmt int8

LogFmt is the logging format

const (
	// STD uses a standard logging scheme without adding delimits
	STD LogFmt = 1 << iota

	// JSON marshals composite structs to json for logging
	JSON
)

type LogLevel

type LogLevel int16

LogLevel is the logging level for the logger

const (
	// INFO is the flag for logging informational logs on a destination
	INFO LogLevel = 1 << iota

	// DEBUG is the flag for logging debugging logs on a destination
	DEBUG

	// TRACE is the flag for logging trace logs on a destination
	TRACE

	// WARN is the flag for logging warning logs on a destination
	WARN

	// ERROR is the flag for logging error logs on a destination
	ERROR

	// CRIT is the flag for logging critical logs on a destination
	CRIT

	// FATAL is the flag for logging fatal logs on a destination
	FATAL

	// CUSTOM is the flag to indicate that a custom log type is being passed
	// instead of one of the built in types
	CUSTOM
)

Log switches for sources setup using bitwise comparison

func (LogLevel) String added in v1.0.4

func (l LogLevel) String() string

type Logger

type Logger interface {

	// Printc creates informational logs based on the data coming from the
	// concurrency channel that is passed in for processing
	Printc(ctx context.Context, v <-chan interface{})

	// Print creates informational logs based on the inputs
	Print(v ...interface{})

	// Println prints the data coming in as an informational log on individual lines
	Println(v ...interface{})

	// Printf creates an informational log using the format and values
	Printf(format string, v ...interface{})

	// Debugc creates debug logs based on the data coming from the
	// concurrency channel that is passed in for processing
	Debugc(ctx context.Context, v <-chan interface{})

	// Debug creates debugging logs based on the inputs
	Debug(err error, v ...interface{})

	// Debugln prints the data coming in as a debug log on individual lines
	Debugln(err error, v ...interface{})

	// Debugf creates an debugging log using the format and values
	Debugf(err error, format string, v ...interface{})

	// Tracec creates trace logs based on the data coming from the
	// concurrency channel that is passed in for processing
	Tracec(ctx context.Context, v <-chan interface{})

	// Trace creates trace logs based on the inputs
	Trace(err error, v ...interface{})

	// Traceln prints the data coming in as a trace log on individual lines
	Traceln(err error, v ...interface{})

	// Tracef creates an trace log using the format and values
	Tracef(err error, format string, v ...interface{})

	// Warnc creates warning logs based on the data coming from the
	// concurrency channel that is passed in for processing
	Warnc(ctx context.Context, v <-chan interface{})

	// Warn creates a warning log using the error passed in along with the
	// values passed in
	Warn(err error, v ...interface{})

	// Warnln creates a warning log using the error and values passed in.
	// Each error and value is printed on a different line
	Warnln(err error, v ...interface{})

	// Warnf creates a warning log using the error passed in, along with the string
	// formatting and values
	Warnf(err error, format string, v ...interface{})

	// Errorc creates error logs based on the data coming from the
	// concurrency channel that is passed in for processing
	Errorc(ctx context.Context, v <-chan interface{})

	// Error creates an error log using the error and other values passed in
	Error(err error, v ...interface{})

	// Error creates error logs using the error and other values passed in.
	// Each error and value is printed on a different line
	Errorln(err error, v ...interface{})

	// Errorf creates an error log using the error passed in, along with the string
	// formatting and values
	Errorf(err error, format string, v ...interface{})

	// Critc creates critical logs based on the data coming from the
	// concurrency channel that is passed in for processing
	Critc(ctx context.Context, v <-chan interface{})

	// Crit creates critical logs using the error and other values passed in
	Crit(err error, v ...interface{})

	// Critln creates critical logs using the error and other values passed in.
	// Each error and value is printed on a different line
	Critln(err error, v ...interface{})

	// Critf creates a critical log using the error passed in, along with the string
	// formatting and values
	Critf(err error, format string, v ...interface{})

	// Fatalc creates fatal logs based on the data coming from the
	// concurrency channel that is passed in for processing
	Fatalc(ctx context.Context, v <-chan interface{})

	// Fatal creates a fatal log using the error and values passed into the method
	// After logging the fatal log the Fatal method throws a panic to crash the application
	Fatal(err error, v ...interface{})

	// Fatalln creates fatal logs using the error and other values passed in.
	// Each error and value is printed on a different line
	// After logging the fatal log the Fatalln method throws a panic to crash the application
	Fatalln(err error, v ...interface{})

	// Fatalf creates an error log using the error passed in, along with the string
	// formatting and values
	// After logging the fatal log the Fatalf method throws a panic to crash the application
	Fatalf(err error, format string, v ...interface{})

	// Customc creates custom logs based on the data coming from the
	// concurrency channel that is passed in for processing
	Customc(ctx context.Context, v <-chan interface{}, ltype string)

	// Custom creates a custom log using the error and values passed into the method
	Custom(ltype string, err error, v ...interface{})

	// Customln creates custom logs using the error and other values passed in.
	// Each error and value is printed on a different line
	Customln(ltype string, err error, v ...interface{})

	// Customf creates a custom log using the error passed in, along with the string
	// formatting and values
	Customf(ltype string, err error, format string, v ...interface{})

	// Close cancels the context throughout the logger and closes
	// all read / write operations across the logger and IO
	Close()

	// Wait blocks on the logger context until the context is closed
	Wait(close bool)
}

Logger provides the ability to log using different methods asynchronously

func New

func New(
	ctx context.Context,
	prefix string,
	dateformat string,
	location *time.Location,
	buffer int,
	destinations ...Destination,
) (logger Logger, err error)

New creates a new logger using the information passed in to setup the logging configuration rather than using the standard Stdout logger that is initialized automatically

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL