sypl

package module
v1.0.0 Latest Latest
Warning

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

 Go to latest Published: Jul 9, 2021 License: MIT Imports: 9 Imported by: 3

README

sypl

spyl provides a Simple Yet Powerful Logger built on top of the Golang sypl. A sypl logger can have many Outputs, and each Output is responsible for writing to a specified destination. Each Output can have multiple Processors, which run in isolation manipulating the log message. The order of execution is important, and is according to the registering (add) order. These features allow sypl to fit into many different logging flows.

Install

$ go get github.com/saucelabs/sypl

Specific version

Example:

$ go get github.com/saucelabs/sypl@v1.0.0

Usage

See example/ folder, and sypl_test.go file or run $ make doc

How it works

A picture worth thousand words.

high-level-arch

Development

Check out CONTRIBUTION.

Release

  1. Update CHANGELOG accordingly.
  2. Once changes from MR are merged.
  3. Tag and release.

Roadmap

Check out CHANGELOG.

Documentation

Overview

Package spyl provides a Simple Yet Powerful Logger built on top of the Golang logger. A sypl logger can have many `Output`s, and each `Output` is responsible for writing to a specified destination. Each Output can have multiple `Processor`s, which run in isolation manipulating the log message. The order of execution is according to the registering order. The above features allow sypl to fit into many different logging flows and needs.

Index

Examples

Constants

This section is empty.

Variables

View Source 
var (
	Red        = color.New(color.FgRed).SprintFunc()
	BoldRed    = color.New(color.FgRed, color.Bold).SprintFunc()
	Green      = color.New(color.FgGreen).SprintFunc()
	BoldGreen  = color.New(color.FgGreen, color.Bold).SprintFunc()
	Yellow     = color.New(color.FgYellow).SprintFunc()
	BoldYellow = color.New(color.FgYellow, color.Bold).SprintFunc()
)

Built-in available colors.

Functions

func IsValidLevelFromInt 

func IsValidLevelFromInt(level int) bool

IsValidLevelFromInt validates if a given level - integer format, is valid.

func LevelsToString 

func LevelsToString(levels []Level) string

LevelsToString converts a slice of levels to string (concatenated).

func OutputsNames 

func OutputsNames(outputs []*Output) string

OutputsNames extract the names of the given outputs.

Types

type Casing 

type Casing string

Casing definition, e.g.: Upper, Lower, Title, etc. 

const (
	// Lowercase casing.
	Lowercase Casing = "lowercase"

	// Uppercase casing.
	Uppercase Casing = "uppercase"
)

type Color 

type Color func(a ...interface{}) string

Color specification.

type FileRotationOptions 

type FileRotationOptions lumberjack.Logger

FileRotationOptions for the log file.

type Level 

type Level int

Level specification. 

const (
	NONE Level = iota
	FATAL
	ERROR
	INFO
	WARN
	DEBUG
	TRACE
)

Available levels.

func LevelFromInt 

func LevelFromInt(level int) Level

LevelFromInt return a `Level` from a given integer.

Notes: - It'll be automatically validated. - It'll exit if it's invalid.

func LevelFromString 

func LevelFromString(level string) Level

LevelFromInt return a `Level` from a given integer.

Note: It'll exit if it's invalid.

func MustBeValidFromInt 

func MustBeValidFromInt(level int) Level

MustBeValidFromInt validates the given `level`. It'll exit if it's invalid. If `level` is valid, it returns the respective `Level`.

func (Level) String 

func (l Level) String() string

String translates enum levels to string. Invalid translation will result in Fatal error. The following would causa a fatal error: 

fmt.Println(Level(15))

`15` is out of the range of `levelsString`.

type Message 

type Message struct {
	ContentOriginal  string
	ContentProcessed string
	Level            Level
	// contains filtered or unexported fields
}

Message envelops the content storing references of the `Logger`, `Output` and used `Processor`s. The original content is also stored, and can be used - but no changed by `Processor`s.

type Output 

type Output struct {
	Logger *builtin.Builtin
	// contains filtered or unexported fields
}

output defines and output that could be a console, a file, or anything that implements io.Writer.

Notes: - Any message with a `level` beyond `maxLevel` will not be written. - Messages are processed according to the order `processors` are added.

func Console 

func Console(maxLevel Level, processors ...*Processor) *Output

Console is a specialized `output` that outputs to the console (stdout).

func File 

func File(path string, maxLevel Level, processors ...*Processor) *Output

File is a specialized `output` that outputs to the specified file.

func FileBased 

func FileBased(name string, path string, maxLevel Level, writer io.Writer, processors ...*Processor) *Output

FileBased is a specialized `output` that outputs to a file. If the usual, and common used "-" is used, it will behave as a Console writing to stdout and named "-".

func FileWithRotation 

func FileWithRotation(
	path string,
	maxLevel Level,
	options *FileRotationOptions,
	processors ...*Processor,
) *Output

FileWithRotation is a specialized `output` that outputs to the specified file, with rotation.

func NewOutput 

func NewOutput(name string, maxLevel Level, writer io.Writer, processors ...*Processor) *Output

NewOutput creates a new `output`.

Notes: - The created `output` is enabled by default. - processors can be added here, or later using the `AddProcessor` method. - This method is chainable.

func (*Output) AddProcessor 

func (o *Output) AddProcessor(processor *Processor) *Output

AddProcessor adds a processor.

Note: This method is chainable.

func (*Output) GetStatus 

func (o *Output) GetStatus() bool

GetStatus returns if the output is enabled or disabled.

func (*Output) SetStatus 

func (o *Output) SetStatus(status bool)

SetStatus allows to enable or disable an output.

type Printer 

type Printer interface {
	// Print prints the message.
	Print(level Level, args ...interface{}) *Sypl

	// Printf prints the message according with the specified format.
	Printf(level Level, format string, args ...interface{}) *Sypl

	// Print prints the message, also adding a new line and the end.
	Println(level Level, args ...interface{}) *Sypl

	// Fatal prints the message, and exit with os.Exit(1).
	Fatal(level Level, args ...interface{})

	// Fatalf prints the message according with the specified format, and exit
	// with os.Exit(1).
	Fatalf(level Level, format string, args ...interface{})

	// Fatalln prints the message, also adding a new line and the end, and exit
	// with os.Exit(1).
	Fatalln(level Level, args ...interface{})
}

Printer defines possible printers.

type Processor 

type Processor struct {
	// contains filtered or unexported fields
}

Processor processes messages. `Processor`s are self-contained algorithms that run in isolation. Any error, should be properly handled, within the processor context itself, and not bubbled up. Don't need to handle cases where message has no content - it's already done, see `sypl.Process`.

func ChangeFirstCharCase 

func ChangeFirstCharCase(casing Casing) *Processor

ChangeFirstCharCase changes message content's first char to the specified case.

Notes: - `casing` because `case` is a reserved word. - Order matters! If this comes after another processor like the Prefixer, it will change the case of the first char of the Prefix mask, not the message content!

func ColorizeBasedOnLevel 

func ColorizeBasedOnLevel(levelColorMap map[Level]Color) *Processor

ColorizeBasedOnLevel colorize messages based on the specified levels.

func ColorizeBasedOnWord 

func ColorizeBasedOnWord(wordColorMap map[string]Color) *Processor

ColorizeBasedOnWord colorize a messages with the specified colors if a message contains a specified word.

func EnableDisableOutputs 

func EnableDisableOutputs(status bool, names ...string) *Processor

EnableDisableOutputs enables or disables the specified outputs.

Note: Order matters! Enabling or disabling an output that was already executed as no effect at all!

func EnableDisableProcessors 

func EnableDisableProcessors(status bool, names ...string) *Processor

EnableDisableProcessors enables or disables the specified processors.

Note: Order matters! Enabling or disabling a processor that was already executed as no effect at all!

func ForceBasedOnLevel 

func ForceBasedOnLevel(levels ...Level) *Processor

ForceBasedOnLevel force messages to be printed based on the specified levels.

func MuteBasedOnLevel 

func MuteBasedOnLevel(levels ...Level) *Processor

MuteBasedOnLevel mute messages based on the specified levels.

func NewProcessor 

func NewProcessor(name string, processorFunc ProcessorFunc) *Processor

NewProcessor creates a new `Processor`.

Notes: - The created `Processor` is enabled by default. - This method is chainable.

func PrefixBasedOnMask 

func PrefixBasedOnMask(timestampFormat string) *Processor

PrefixBasedOnMask prefixes messages with the predefined mask.

Example: 2021-06-22 12:51:46.089 [80819] [CLI] INFO.

func PrefixBasedOnMaskExceptForLevels 

func PrefixBasedOnMaskExceptForLevels(timestampFormat string, levels ...Level) *Processor

PrefixBasedOnMaskExceptForLevels is a specialized version of the `PrefixBasedOnMask`. It prefixes all messages, except for the specified levels.

func Prefixer 

func Prefixer(prefix string) *Processor

Prefixer prefixes messages with the given string.

func Suffixer 

func Suffixer(suffix string) *Processor

Suffixer suffixes messages with the given string.

func (*Processor) GetStatus 

func (p *Processor) GetStatus() bool

GetStatus returns if the processor is enabled or disabled.

func (*Processor) Run 

func (p *Processor) Run(message *Message)

Process the message.

func (*Processor) SetStatus 

func (p *Processor) SetStatus(status bool)

SetStatus allows to enable or disable a processor.

type ProcessorFunc 

type ProcessorFunc func(message *Message)

ProcessorFunc is the processor's `do` specification.

type Sypl 

type Sypl struct {
	// contains filtered or unexported fields
}

sypl definition. It's able to print messages according to the definition of each `output`.

func New 

func New(name string, outputs ...*Output) *Sypl

New creates a new custom logger.

Notes: Outputs can be added here, or later using the `AddOutput` method.

Example (Chained)

Chained is the chained example of creating, and setting up a `sypl` logger. It writes to both `stdout` and `stderr`. 

// Creates logger, and name it.
New("Testing Logger").
	// Creates two `Output`s. "Console" and "Error". "Console" will print to
	// `Fatal`, `Error`, and `Info`. "Error" will only print `Fatal`, and
	// `Error` levels.
	AddOutput(NewOutput("Console", INFO, os.Stdout)).
	// Creates a `Processor`. It will prefix all messages. It will only
	// prefix messages for this specific `Output`, and @ `ERROR` level.
	AddOutput(NewOutput("Error", ERROR, os.Stderr).
		AddProcessor(func(prefix string) *Processor {
			return NewProcessor("Prefixer", func(message *Message) {
				if message.Level == ERROR {
					message.ContentProcessed = prefix + message.ContentProcessed
				}
			})
		}(defaultPrefixValue))).
	// Prints:
	// Test info message
	Println(INFO, "Test info message").
	// Prints:
	// Test error message
	// My Prefix - Test error message
	Println(ERROR, "Test error message")

Output:
Example (ChainedUsingBuiltin)

ChainedUsingBuiltin is the chained example of creating, and setting up a `sypl` logger using built-in `Output`, and `Processor`. It writes to `stdout`, and `stderr`. 

// Creates logger, and name it.
New("Testing Logger").
	// Adds an `Output`. In this case, called "Console" that will print to
	// `stdout` and max print level @ `INFO`.
	//
	// Adds a `Processor`. It will prefix all messages.
	AddOutput(Console(INFO).AddProcessor(Prefixer(defaultPrefixValue))).
	// Prints: My Prefix - Test info message
	Infoln("Test info message")

Output:

My Prefix - Test info message
Example (InlineUsingBuiltin)

inlineUsingBuiltin same as `ChainedUsingBuiltin` but using inline form. 

New("Testing Logger", Console(INFO).AddProcessor(Prefixer(defaultPrefixValue))).Infoln("Test info message")

Output:

My Prefix - Test info message
Example (NotChained)

NonChained is a non-chained example of creating, and setting up a `sypl` logger. It writes to a custom buffer. 

var buf bytes.Buffer
bufWriter := bufio.NewWriter(&buf)

// Creates logger, and name it.
testingLogger := New("Testing Logger")

// Creates an `Output`. In this case, called "Console" that will print to
// `stdout` and max print level @ `INFO`.
ConsoleToStdOut := NewOutput("Console", INFO, bufWriter)

// Creates a `Processor`. It will prefix all messages.
Prefixer := func(prefix string) *Processor {
	return NewProcessor("Prefixer", func(message *Message) {
		message.ContentProcessed = prefix + message.ContentProcessed
	})
}

// Adds `Processor` to `Output`.
ConsoleToStdOut.AddProcessor(Prefixer(defaultPrefixValue))

// Adds `Output` to logger.
testingLogger.AddOutput(ConsoleToStdOut)

// Prints: "My Prefix - Test message"
testingLogger.Print(INFO, "Test info message")

bufWriter.Flush()

fmt.Println(buf.String())

Output:

My Prefix - Test info message

func (*Sypl) AddOutput 

func (cL *Sypl) AddOutput(output *Output) *Sypl

AddOutput adds an `output` to logger.

Note: This method is chainable.

func (*Sypl) Debug 

func (cL *Sypl) Debug(args ...interface{}) *Sypl

Debug prints the message (if has content) @ the DEBUG level.

func (*Sypl) Debugf 

func (cL *Sypl) Debugf(format string, args ...interface{}) *Sypl

Debugf prints the message (if has content) according with the specified format @ the DEBUG level.

func (*Sypl) Debugln 

func (cL *Sypl) Debugln(args ...interface{}) *Sypl

Debugln prints the message (if has content), also adding a new line to the end @ the DEBUG level.

func (*Sypl) Error 

func (cL *Sypl) Error(args ...interface{}) *Sypl

Error prints the message (if has content) @ the ERROR level.

func (*Sypl) Errorf 

func (cL *Sypl) Errorf(format string, args ...interface{}) *Sypl

Errorf prints the message (if has content) according with the specified format @ the ERROR level.

func (*Sypl) Errorln 

func (cL *Sypl) Errorln(args ...interface{}) *Sypl

Errorln prints the message (if has content), also adding a new line to the end @ the ERROR level.

func (*Sypl) Fatal 

func (cL *Sypl) Fatal(args ...interface{})

Fatal prints the message (if has content), and exit with os.Exit(1).

func (*Sypl) Fatalf 

func (cL *Sypl) Fatalf(format string, args ...interface{})

Fatalf prints the message (if has content) according with the specified format, and exit with os.Exit(1).

func (*Sypl) Fatalln 

func (cL *Sypl) Fatalln(args ...interface{})

Fatalln prints the message (if has content), also adding a new line and the end, and exit with os.Exit(1).

func (*Sypl) Info 

func (cL *Sypl) Info(args ...interface{}) *Sypl

Info prints the message (if has content) @ the INFO level.

func (*Sypl) Infof 

func (cL *Sypl) Infof(format string, args ...interface{}) *Sypl

Infof prints the message (if has content) according with the specified format @ the INFO level.

func (*Sypl) Infoln 

func (cL *Sypl) Infoln(args ...interface{}) *Sypl

Infoln prints the message (if has content), also adding a new line to the end @ the INFO level.

func (*Sypl) Print 

func (cL *Sypl) Print(level Level, args ...interface{}) *Sypl

Print prints the message (if has content).

func (*Sypl) PrintByOutput 

func (cL *Sypl) PrintByOutput(outputsNames []string, level Level, args ...interface{}) *Sypl

PrintByOutput prints the message (if has content) to the specified outputs.

func (*Sypl) Printf 

func (cL *Sypl) Printf(level Level, format string, args ...interface{}) *Sypl

Printf prints the message (if has content) according with the specified format.

func (*Sypl) PrintfByOutput 

func (cL *Sypl) PrintfByOutput(outputsNames []string, level Level, format string, args ...interface{}) *Sypl

PrintfByOutput prints the message (if has content) according with the specified format, and to the specified outputs.

func (*Sypl) Println 

func (cL *Sypl) Println(level Level, args ...interface{}) *Sypl

Println prints the message (if has content), also adding a new line to the end.

func (*Sypl) PrintlnByOutput 

func (cL *Sypl) PrintlnByOutput(outputsNames []string, level Level, args ...interface{}) *Sypl

PrintlnByOutput prints the message (if has content), also adding a new line to the end, and to the specified outputs.

func (*Sypl) Trace 

func (cL *Sypl) Trace(args ...interface{}) *Sypl

Trace prints the message (if has content) @ the TRACE level.

func (*Sypl) Tracef 

func (cL *Sypl) Tracef(format string, args ...interface{}) *Sypl

Tracef prints the message (if has content) according with the specified format @ the TRACE level.

func (*Sypl) Traceln 

func (cL *Sypl) Traceln(args ...interface{}) *Sypl

Traceln prints the message (if has content), also adding a new line to the end @ the TRACE level.

func (*Sypl) Warn 

func (cL *Sypl) Warn(args ...interface{}) *Sypl

Warn prints the message (if has content) @ the WARN level.

func (*Sypl) Warnf 

func (cL *Sypl) Warnf(format string, args ...interface{}) *Sypl

Warnf prints the message (if has content) according with the specified format @ the WARN level.

func (*Sypl) Warnln 

func (cL *Sypl) Warnln(args ...interface{}) *Sypl

Warnln prints the message (if has content), also adding a new line to the end @ the WARN level.

Source Files

View all Source files

Directories

Path Synopsis
internal
builtin
Package log implements a simple logging package.
 Package log implements a simple logging package.

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.