sypl

README

sypl

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

Usage

See example_test.go, and sypl_test.go file.

Documentation

Run $ make doc or check out online.

How it works

A picture worth thousand words.

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

• type IBasePrinter
• type IBasicPrinter
• type IConvenientPrinter
• type ILeveledPrinter
• type ISypl
  • func New(name string, outputs ...output.IOutput) ISypl
• type Printers

Examples

• New (Chained)
• New (ChainedUsingBuiltin)
• New (Flags)
• New (InlineUsingBuiltin)
• New (NotChained)
• New (PrintPretty)
• New (PrintWithOptions)
• New (SerrorX)

Types

type IBasePrinter

type IBasePrinter interface {
	// PrintMessage prints the specified message. It's a powerful option because
	// it gives full-control over the message. Use `NewMessage` to create the
	// message.
	PrintMessage(m message.IMessage) ISypl

	// PrintWithOptions is a more flexible way of printing, allowing to specify
	// a few message's options. For full-control over the message is possible
	// via `PrintMessage`.
	PrintWithOptions(o *options.Options, l level.Level, args ...interface{}) ISypl

	// PrintWithOptionsf prints according with the specified format. It's a more
	// flexible way of printing, allowing to specify a few message's options.
	// For full-control over the message is possible via `PrintMessage`.
	PrintWithOptionsf(o *options.Options, l level.Level, format string, args ...interface{}) ISypl

	// PrintWithOptionsf prints according with the specified format, also adding
	// a new line to the end. It's a more flexible way of printing, allowing to
	// specify a few message's options. For full-control over the message is
	// possible via `PrintMessage`.
	PrintWithOptionslnf(o *options.Options, l level.Level, format string, args ...interface{}) ISypl

	// PrintWithOptionsf prints, also adding a new line to the end. It's a more
	// flexible way of printing, allowing to specify a few message's options.
	// For full-control over the message is possible via `PrintMessage`.
	PrintWithOptionsln(o *options.Options, l level.Level, args ...interface{}) ISypl
}

IBasePrinter specifies the foundation for other printers.

type IBasicPrinter

type IBasicPrinter interface {
	// Print just prints.
	Print(l level.Level, args ...interface{}) ISypl

	// Printf prints according with the specified format.
	Printf(l level.Level, format string, args ...interface{}) ISypl

	// Printlnf prints according with the specified format, also adding a new
	// line to the end.
	Printlnf(l level.Level, format string, args ...interface{}) ISypl

	// Println prints, also adding a new line to the end.
	Println(l level.Level, args ...interface{}) ISypl
}

IBasicPrinter specifies the basic printers.

type IConvenientPrinter

type IConvenientPrinter interface {
	// PrintPretty prints data structures as JSON text.
	//
	// Notes:
	// - Only exported fields of the data structure will be printed.
	// - Message isn't processed.
	PrintPretty(l level.Level, data interface{}) ISypl

	// PrintlnPretty prints data structures as JSON text, also adding a new line
	// to the end.
	//
	// Notes:
	// - Only exported fields of the data structure will be printed.
	// - Message isn't processed.
	PrintlnPretty(l level.Level, data interface{}) ISypl
}

IConvenientPrinter specifies convenient printers.

type ILeveledPrinter

type ILeveledPrinter interface {
	// Fatal prints, and exit with os.Exit(1).
	Fatal(args ...interface{}) ISypl

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

	// Fatallnf prints according with the format, also adding a new line to the
	// end, and exit with os.Exit(1).
	Fatallnf(format string, args ...interface{}) ISypl

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

	// Error prints @ the Error level.
	Error(args ...interface{}) ISypl

	// Errorf prints according with the format @ the Error level.
	Errorf(format string, args ...interface{}) ISypl

	// Errorlnf prints according with the format @ the Error level, also adding
	// a new line to the end.
	Errorlnf(format string, args ...interface{}) ISypl

	// Errorln prints, also adding a new line to the end @ the Error level.
	Errorln(args ...interface{}) ISypl

	// Serror prints like Error, and returns an error with the non-processed
	// content.
	Serror(args ...interface{}) error

	// Serrorf prints like Errorf, and returns an error with the non-processed
	// content.
	Serrorf(format string, args ...interface{}) error

	// Serrorlnf prints like Errorlnf, and returns an error with the
	// non-processed content.
	Serrorlnf(format string, args ...interface{}) error

	// Serrorln prints like Errorln, and returns an error with the non-processed
	// content.
	Serrorln(args ...interface{}) error

	// Info prints @ the Info level.
	Info(args ...interface{}) ISypl

	// Infof prints according with the specified format @ the Info level.
	Infof(format string, args ...interface{}) ISypl

	// Infolnf prints according with the specified format @ the Info level, also
	// adding a new line to the end.
	Infolnf(format string, args ...interface{}) ISypl

	// Infoln prints, also adding a new line to the end @ the Info level.
	Infoln(args ...interface{}) ISypl

	// Warn prints @ the Warn level.
	Warn(args ...interface{}) ISypl

	// Warnf prints according with the specified format @ the Warn level.
	Warnf(format string, args ...interface{}) ISypl

	// Warnlnf prints according with the specified format @ the Warn level, also
	// adding a new line to the end.
	Warnlnf(format string, args ...interface{}) ISypl

	// Warnln prints, also adding a new line to the end @ the Warn level.
	Warnln(args ...interface{}) ISypl

	// Debug prints @ the Debug level.
	Debug(args ...interface{}) ISypl

	// Debugf prints according with the specified format @ the Debug level.
	Debugf(format string, args ...interface{}) ISypl

	// Debuglnf prints according with the specified format @ the Debug level,
	// also adding a new line to the end.
	Debuglnf(format string, args ...interface{}) ISypl

	// Debugln prints, also adding a new line to the end @ the Debug level.
	Debugln(args ...interface{}) ISypl

	// Trace prints @ the Trace level.
	Trace(args ...interface{}) ISypl

	// Tracef prints according with the specified format @ the Trace level.
	Tracef(format string, args ...interface{}) ISypl

	// Tracelnf prints according with the specified format @ the Trace level,
	// also adding a new line to the end.
	Tracelnf(format string, args ...interface{}) ISypl

	// Traceln prints, also adding a new line to the end @ the Trace level.
	Traceln(args ...interface{}) ISypl
}

ILeveledPrinter specifies the leveled printers.

type ISypl

type ISypl interface {
	meta.IMeta
	Printers

	// AddOutputs adds one or more outputs.
	AddOutputs(outputs ...output.IOutput) ISypl

	// Returns the registered output by its name. If not found, will be nil.
	GetOutput(name string) output.IOutput

	// Sets one or more outputs.
	SetOutputs(outputs ...output.IOutput)

	// GetOutputs returns registered outputs.
	GetOutputs() []output.IOutput

	// GetOutputsNames returns the names of the registered outputs.
	GetOutputsNames() []string

	// Process the message, per output, process accordingly.
	Process(m message.IMessage)
}

ISypl specified what a Sypl does.

func New

func New(name string, outputs ...output.IOutput) ISypl

New is the Sypl factory.

Example (Chained)

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

package main

import (
	"os"

	"github.com/saucelabs/sypl"
	"github.com/saucelabs/sypl/level"
	"github.com/saucelabs/sypl/message"
	"github.com/saucelabs/sypl/output"
	"github.com/saucelabs/sypl/processor"
	"github.com/saucelabs/sypl/shared"
)

func main() {
	// Creates logger, and name it.
	sypl.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.
		AddOutputs(output.NewOutput("Console", level.Info, os.Stdout)).
		// Creates a `Processor`. It will prefix all messages. It will only
		// prefix messages for this specific `Output`, and @ `Error` level.
		AddOutputs(output.NewOutput("Error", level.Error, os.Stderr).
			AddProcessors(func(prefix string) processor.IProcessor {
				return processor.NewProcessor("Prefixer", func(message message.IMessage) error {
					if message.GetLevel() == level.Error {
						message.GetContent().SetProcessed(prefix + message.GetContent().GetProcessed())
					}

					return nil
				})
			}(shared.DefaultPrefixValue))).
		// Prints:
		// Test info message
		Println(level.Info, "Test info message").
		// Prints:
		// Test error message
		// My Prefix - Test error message
		Println(level.Error, "Test error message")

	

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

package main

import (
	"github.com/saucelabs/sypl"
	"github.com/saucelabs/sypl/level"
	"github.com/saucelabs/sypl/output"
	"github.com/saucelabs/sypl/processor"
	"github.com/saucelabs/sypl/shared"
)

func main() {
	// Creates logger, and name it.
	sypl.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.
		AddOutputs(output.Console(level.Info).AddProcessors(processor.Prefixer(shared.DefaultPrefixValue))).
		// Prints: My Prefix - Test info message
		Infoln("Test info message")

}

Output:

My Prefix - Test info message

Example (Flags)

Flags example.

package main

import (
	"github.com/saucelabs/sypl"
	"github.com/saucelabs/sypl/flag"
	"github.com/saucelabs/sypl/level"
	"github.com/saucelabs/sypl/options"
	"github.com/saucelabs/sypl/output"
	"github.com/saucelabs/sypl/processor"
	"github.com/saucelabs/sypl/shared"
)

func main() {
	// Creates logger, and name it.
	sypl.New("Testing Logger", output.Console(level.Info, processor.Prefixer(shared.DefaultPrefixValue))).
		// Message will be processed, and printed independent of `Level`
		// restrictions.
		PrintWithOptionsln(&options.Options{
			Flag: flag.Force,
		}, level.Debug, shared.DefaultContentOutput).

		// Message will be processed, but not printed.
		PrintWithOptionsln(&options.Options{
			Flag: flag.Mute,
		}, level.Info, shared.DefaultContentOutput).

		// Message will not be processed, but printed.
		PrintWithOptionsln(&options.Options{
			Flag: flag.Skip,
		}, level.Info, shared.DefaultContentOutput).

		// Should not print - restricted by level.
		Debugln(shared.DefaultContentOutput).

		// SkipAndForce message will not be processed, but will be printed
		// independent of `Level` restrictions.
		PrintWithOptionsln(&options.Options{
			Flag: flag.SkipAndForce,
		}, level.Debug, shared.DefaultContentOutput).

		// Message will not be processed, neither printed.
		PrintWithOptionsln(&options.Options{
			Flag: flag.SkipAndMute,
		}, level.Debug, shared.DefaultContentOutput)

}

Output:

My Prefix - contentTest
contentTest
contentTest

Example (InlineUsingBuiltin)

inlineUsingBuiltin same as `ChainedUsingBuiltin` but using inline form.

package main

import (
	"github.com/saucelabs/sypl"
	"github.com/saucelabs/sypl/level"
	"github.com/saucelabs/sypl/output"
	"github.com/saucelabs/sypl/processor"
	"github.com/saucelabs/sypl/shared"
)

func main() {
	sypl.New("Testing Logger", output.Console(level.Info).
		AddProcessors(processor.Prefixer(shared.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.

package main

import (
	"fmt"
	"strings"

	"github.com/saucelabs/sypl"
	"github.com/saucelabs/sypl/level"
	"github.com/saucelabs/sypl/message"
	"github.com/saucelabs/sypl/output"
	"github.com/saucelabs/sypl/processor"
	"github.com/saucelabs/sypl/shared"
)

func main() {
	buf := new(strings.Builder)

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

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

	// Creates a `Processor`. It will prefix all messages.
	Prefixer := func(prefix string) processor.IProcessor {
		return processor.NewProcessor("Prefixer", func(message message.IMessage) error {
			message.GetContent().SetProcessed(prefix + message.GetContent().GetProcessed())

			return nil
		})
	}

	// Adds `Processor` to `Output`.
	ConsoleToStdOut.AddProcessors(Prefixer(shared.DefaultPrefixValue))

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

	// Writes: "My Prefix - Test message"
	testingLogger.Print(level.Info, "Test info message")

	fmt.Println(buf.String())

}

Output:

My Prefix - Test info message

Example (PrintPretty)

PrintPretty example.

package main

import (
	"github.com/saucelabs/sypl"
	"github.com/saucelabs/sypl/level"
	"github.com/saucelabs/sypl/output"
)

func main() {
	type TestType struct {
		Key1 string
		Key2 int
	}

	sypl.New("Testing Logger", output.Console(level.Info)).PrintPretty(level.Info, &TestType{
		Key1: "text",
		Key2: 12,
	})

}

Output:

{
	"Key1": "text",
	"Key2": 12
}

Example (PrintWithOptions)

printWithOptions demonstrates `sypl` flexibility. `Options` enhances the usual `PrintX` methods allowing to specify flags, and tags.

package main

import (
	"fmt"
	"strings"

	"github.com/saucelabs/sypl"
	"github.com/saucelabs/sypl/level"
	"github.com/saucelabs/sypl/message"
	"github.com/saucelabs/sypl/options"
	"github.com/saucelabs/sypl/output"
	"github.com/saucelabs/sypl/processor"
	"github.com/saucelabs/sypl/safebuffer"
	"github.com/saucelabs/sypl/shared"
)

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

	// Creates 3 `Output`s, all called "Console" that will print to `stdout`, and
	// max print level @ `Info`.
	var c1buf safebuffer.Buffer
	Console1ToStdOut := output.NewOutput("Buffer 1", level.Info, &c1buf)

	var c2buf safebuffer.Buffer
	Console2ToStdOut := output.NewOutput("Buffer 2", level.Info, &c2buf)

	var c3buf safebuffer.Buffer
	Console3ToStdOut := output.NewOutput("Buffer 3", level.Info, &c3buf)

	// Creates a `Processor`. It will `prefix` all messages with the Output, and
	// Processor names.
	Prefixer := func() processor.IProcessor {
		return processor.NewProcessor("Prefixer", func(message message.IMessage) error {
			prefix := fmt.Sprintf("Output: %s Processor: %s Content: ",
				message.GetOutputName(),
				message.GetProcessorName(),
			)

			message.GetContent().SetProcessed(prefix + message.GetContent().GetProcessed())

			return nil
		})
	}

	// Creates a `Processor`. It will `suffix` all messages with the specified
	// `tag`.
	SuffixBasedOnTag := func(tag string) processor.IProcessor {
		return processor.NewProcessor("SuffixBasedOnTag", func(message message.IMessage) error {
			if message.ContainTag(tag) {
				message.GetContent().SetProcessed(message.GetContent().GetProcessed() + " - My Suffix")
			}

			return nil
		})
	}

	// Adds `Processor`s to `Output`s.
	Console1ToStdOut.AddProcessors(Prefixer(), SuffixBasedOnTag("SuffixIt"))
	Console2ToStdOut.AddProcessors(Prefixer(), SuffixBasedOnTag("SuffixIt"))
	Console3ToStdOut.AddProcessors(Prefixer(), SuffixBasedOnTag("SuffixIt"))

	// Adds all `Output`s to logger.
	testingLogger.AddOutputs(Console1ToStdOut, Console2ToStdOut, Console3ToStdOut)

	// Prints with prefix, without suffix.
	testingLogger.Print(level.Info, shared.DefaultContentOutput)

	fmt.Println(strings.EqualFold(c1buf.String(), "Output: Buffer 1 Processor: Prefixer Content: contentTest"))
	fmt.Println(strings.EqualFold(c2buf.String(), "Output: Buffer 2 Processor: Prefixer Content: contentTest"))
	fmt.Println(strings.EqualFold(c3buf.String(), "Output: Buffer 3 Processor: Prefixer Content: contentTest"))

	c1buf.Reset()
	c2buf.Reset()
	c3buf.Reset()

	// Prints with prefix, and suffix.
	testingLogger.PrintWithOptions(&options.Options{
		OutputsNames:    []string{"Buffer 1"},
		ProcessorsNames: []string{"Prefixer", "SuffixBasedOnTag"},
		Tags:            []string{"SuffixIt"},
	}, level.Info, shared.DefaultContentOutput)

	fmt.Println(strings.EqualFold(c1buf.String(), "Output: Buffer 1 Processor: Prefixer Content: contentTest - My Suffix"))

	// fmt.Print(c1buf.String(), c2buf.String(), c3buf.String())

}

Output:

true
true
true
true

Example (SerrorX)

Serror{f|lnf|ln} example.

package main

import (
	"errors"
	"fmt"

	"github.com/saucelabs/sypl"
	"github.com/saucelabs/sypl/level"
	"github.com/saucelabs/sypl/output"
	"github.com/saucelabs/sypl/shared"
)

func main() {
	// Creates logger, and name it.
	testingLogger := sypl.New("Testing Logger", output.Console(level.Info))

	sErrorResult := testingLogger.Serror(shared.DefaultContentOutput)

	errExample := errors.New("Failed to reach something")
	sErrorfResult := testingLogger.Serrorf("Failed to do something, %s", errExample)
	sErrorlnfResult := testingLogger.Serrorlnf("Failed to do something, %s", errExample)
	sErrorlnResult := testingLogger.Serrorln(shared.DefaultContentOutput)

	fmt.Print(
		sErrorResult.Error() == shared.DefaultContentOutput,
		sErrorfResult.Error() == "Failed to do something, Failed to reach something",
		sErrorlnfResult.Error() == "Failed to do something, Failed to reach something"+"\n",
		sErrorlnResult.Error() == shared.DefaultContentOutput+"\n",
	)

}

Output:

contentTestFailed to do something, Failed to reach somethingFailed to do something, Failed to reach something
contentTest
true true true true

type Printers

type Printers interface {
	IBasePrinter
	IBasicPrinter
	IConvenientPrinter
	ILeveledPrinter
}

Printers is all available printers.