plog

package module
v0.5.0 Latest Latest
Warning

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

 Go to latest Published: Dec 20, 2020 License: MIT Imports: 8 Imported by: 0

README

PLog (pre-release)

PLog
--- A lightweight and feature rich logger for Golang ---

Note: PLog is in pre-release and should not be used in production systems until v1 is released.

Travis CodeCov Release GoDoc Licence

Features

  • Speed - Your logger shouldn't slow your software down. PLog is fast, lightweight and has no dependencies.
  • Multiple Outputs - No more multi-writers. PLog lets you write to as many outputs as you like. Each output can specify its own format and log level.
  • Multiple Formats - Output your logs in a format that suits your needs.
    • Text - A pretty printed plaintext string with color support.
    • JSON - Each log gets stored as a JSON object to allow parsing and filtering.
    • CSV - Comma-separated values. Compatible with spreadsheets.
    • Custom - Specify your own formatter function to style your log output however you like.
  • Log Tags - Tag your logs to make them easier to search and filter.
  • Custom Colors - Override the default colors for each logging level and tag.
  • Log File Rotation - Plog can automatically generate and rotate log files. You can specify custom conditions for when these files should be rotated and how to name them using a built-in or custom sequencer.
  • And more to come! See our Roadmap.

Documentation

Credits

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AddLogger 

func AddLogger(name string, logger *Logger)

AddLogger adds the provided logger to PLog. See `type Logger` for more details.

func Debug 

func Debug(variables ...interface{})

Debug will print any number of variables to all loggers at debug level.

func Debugf 

func Debugf(format string, variables ...interface{})

Debugf will print a formatted message to all loggers at debug level.

func DeleteLogger 

func DeleteLogger(name string)

DeleteLogger removes the specified logger from PLog.

func Error 

func Error(err error)

Error will print a non-fatal error message to all loggers.

func Errorf 

func Errorf(format string, err error)

Errorf will print a formatted, non-fatal error message.

func Fatal 

func Fatal(err error)

Fatal will print a fatal error message to all loggers.

func Fatalf 

func Fatalf(format string, err error)

Fatalf will print a formatted, non-fatal error message.

func Info 

func Info(variables ...interface{})

Info will print any number of variables to all loggers at info level.

func Infof 

func Infof(format string, variables ...interface{})

Infof will print a formatted message to all loggers at info level.

func Options added in v0.5.0 

func Options(opts ...LoggerOption)

Options will apply the given options to all loggers. Any number of functional options can be passed to this method. You can read more information on functional options on the PLog wiki: https://github.com/pd93/plog/wiki/Functional-Options.

func TDebug added in v0.3.0 

func TDebug(tags Tags, variables ...interface{})

TDebug will print any number of variables at debug level and meta-tag the log.

func TDebugf added in v0.3.0 

func TDebugf(tags Tags, format string, variables ...interface{})

TDebugf will print a formatted message at debug level and meta-tag the log.

func TError added in v0.3.0 

func TError(tags Tags, err error)

TError will print a non-fatal error message and meta-tag the log.

func TErrorf added in v0.3.0 

func TErrorf(tags Tags, format string, err error)

TErrorf will print a formatted, non-fatal error message and meta-tag the log.

func TFatal added in v0.3.0 

func TFatal(tags Tags, err error)

TFatal will print a fatal error message and meta-tag the log.

func TFatalf added in v0.3.0 

func TFatalf(tags Tags, format string, err error)

TFatalf will print a formatted, fatal error message and meta-tag the log.

func TInfo added in v0.3.0 

func TInfo(tags Tags, variables ...interface{})

TInfo will print any number of variables at info level and meta-tag the log.

func TInfof added in v0.3.0 

func TInfof(tags Tags, format string, variables ...interface{})

TInfof will print a formatted message at info level and meta-tag the log.

func TTrace added in v0.3.0 

func TTrace(tags Tags, variables ...interface{})

TTrace will print any number of variables at trace level and meta-tag the log.

func TTracef added in v0.3.0 

func TTracef(tags Tags, format string, variables ...interface{})

TTracef will print a formatted message at trace level and meta-tag the log.

func TWarn added in v0.3.0 

func TWarn(tags Tags, variables ...interface{})

TWarn will print any number of variables at warn level and meta-tag the log.

func TWarnf added in v0.3.0 

func TWarnf(tags Tags, format string, variables ...interface{})

TWarnf will print a formatted message at warn level and meta-tag the log.

func Trace 

func Trace(variables ...interface{})

Trace will print any number of variables to all loggers at debug level.

func Tracef 

func Tracef(format string, variables ...interface{})

Tracef will print a formatted message to all loggers at debug level.

func Warn 

func Warn(variables ...interface{})

Warn will print any number of variables to all loggers at warn level.

func Warnf 

func Warnf(format string, variables ...interface{})

Warnf will print a formatted message to all loggers at warn level.

Types

type Attribute 

type Attribute int

Attribute defines a single SGR Code 

const (
	Reset Attribute = iota
	Bold
	Faint
	Italic
	Underline
	BlinkSlow
	BlinkRapid
	ReverseVideo
	Concealed
	CrossedOut
)

Font decorations: 

const (
	FgBlack Attribute = iota + 30
	FgRed
	FgGreen
	FgYellow
	FgBlue
	FgMagenta
	FgCyan
	FgWhite
)

Foreground text colors: 

const (
	FgHiBlack Attribute = iota + 90
	FgHiRed
	FgHiGreen
	FgHiYellow
	FgHiBlue
	FgHiMagenta
	FgHiCyan
	FgHiWhite
)

Foreground text colors (Hi-Intensity): 

const (
	BgBlack Attribute = iota + 40
	BgRed
	BgGreen
	BgYellow
	BgBlue
	BgMagenta
	BgCyan
	BgWhite
)

Background text colors: 

const (
	BgHiBlack Attribute = iota + 100
	BgHiRed
	BgHiGreen
	BgHiYellow
	BgHiBlue
	BgHiMagenta
	BgHiCyan
	BgHiWhite
)

Background text colors (Hi-Intensity):

type File 

type File struct {
	*os.File // The currently open file
	// contains filtered or unexported fields
}

File represents a log file or a sequence of log files.

func NewCSVFile added in v0.5.0 

func NewCSVFile(format string, opts ...FileOption) (file *File, err error)

NewCSVFile will create and open a new file for writing CSV. CSV headers will be automatically configured and validated when writing. Any number of additional functional options can be passed to this method and they will be applied on creation. These additional options will override any of the settings mentioned above. You can read more information on functional options on the PLog wiki: https://github.com/pd93/plog/wiki/Functional-Options.

func NewFile 

func NewFile(format string, opts ...FileOption) (file *File, err error)

NewFile will create and open a new file for writing.

func NewJSONFile added in v0.5.0 

func NewJSONFile(format string, opts ...FileOption) (file *File, err error)

NewJSONFile will create and open a new file for writing JSON. Square brackets will wrap the logs (an array of log objects). Commas are inserted as necessary and the file is validated. Any number of additional functional options can be passed to this method and they will be applied on creation. These additional options will override any of the settings mentioned above. You can read more information on functional options on the PLog wiki: https://github.com/pd93/plog/wiki/Functional-Options.

func NewTextFile added in v0.5.0 

func NewTextFile(format string, opts ...FileOption) (file *File, err error)

NewTextFile will create and open a new file for writing text. Any number of additional functional options can be passed to this method and they will be applied on creation. These additional options will override any of the settings mentioned above. You can read more information on functional options on the PLog wiki: https://github.com/pd93/plog/wiki/Functional-Options.

func (*File) Format added in v0.5.0 

func (file *File) Format() string

Format returns the format of the file name.

func (*File) MaxFileSize added in v0.5.0 

func (file *File) MaxFileSize() int64

MaxFileSize returns the maximum file size allowed.

func (*File) Options added in v0.5.0 

func (file *File) Options(opts ...FileOption)

Options will apply the given options to the file. Any number of functional options can be passed to this method. You can read more information on functional options on the PLog wiki: https://github.com/pd93/plog/wiki/Functional-Options.

func (*File) Rotate added in v0.5.0 

func (file *File) Rotate() (err error)

Rotate will close the old file and open a new one with the next name in the sequence.

func (*File) Sequencer added in v0.5.0 

func (file *File) Sequencer() Sequencer

Sequencer returns the sequencer function used to determine file names.

func (*File) ShouldRotate added in v0.5.0 

func (file *File) ShouldRotate(p []byte) (shouldRotate bool, err error)

ShouldRotate will return true or false depending on whether the log file should be rotated. It uses the message being written and the current file size to do this.

func (*File) Write 

func (file *File) Write(p []byte) (n int, err error)

Write will write bytes to the file.

func (*File) Writer added in v0.5.0 

func (file *File) Writer() Writer

Writer returns the writer used to log the messages.

type FileOption added in v0.5.0 

type FileOption func(file *File)

A FileOption is a function that sets an option on a given file.

func WithFormat added in v0.5.0 

func WithFormat(format string) FileOption

WithFormat will return a function that sets the format of the filename. The format acts as a fixed filename when using a normal logger. The filename is dynamic when using a format alongside a sequencer function. Take a look at the example sequencers included with PLog for more information.

func WithMaxFileSize added in v0.5.0 

func WithMaxFileSize(maxFileSize int64) FileOption

WithMaxFileSize will return a function that sets the maximum size of a file. If the maximum file size is set to -1, any size file is allowed.

func WithSequencer added in v0.5.0 

func WithSequencer(sequencer Sequencer) FileOption

WithSequencer will return a function that sets the sequencer for a file. This sequencer will determine the log file names during rotation based on the format and the previous file name. PLog includes several sequencers for convenience (See `sequencers` subpackage). Users can also provide a their own function if they want a custom file name sequence.

func WithWriter added in v0.5.0 

func WithWriter(writer Writer) FileOption

WithWriter will return a function that sets the writer for a file. This writer will determine how the message should be written to the file. PLog includes several writers for convenience (See `writers` subpackage). Users can also provide a their own function if they want custom writing behaviour.

type Formatter added in v0.4.0 

type Formatter func(timestamp, logLevel string, variables []interface{}, tags []string) (string, error)

A Formatter is a function that generates a formatted string from a log.

type Log added in v0.4.0 

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

A Log holds a single message along with its log level and timestamp.

func (*Log) LogLevel added in v0.4.0 

func (log *Log) LogLevel() LogLevel

LogLevel will return the level at which this log is set to write.

func (*Log) Tags added in v0.4.0 

func (log *Log) Tags() Tags

Tags will return the list of tags associated with the log.

func (*Log) Timestamp added in v0.4.0 

func (log *Log) Timestamp() time.Time

Timestamp will return the log creation timestamp.

func (*Log) Variables added in v0.4.0 

func (log *Log) Variables() []interface{}

Variables will return the list of log output variables.

type LogLevel 

type LogLevel int

LogLevel dictates when a logged message should be displayed or recorded. 

const (
	// None will stop all logs being printed
	None LogLevel = iota
	// FatalLevel should only be used to log errors that stop the program from continuing execution
	FatalLevel
	// ErrorLevel should be used to display non-fatal errors
	ErrorLevel
	// WarnLevel should be used when an error isn't appropriate, but the message needs be highlighted
	WarnLevel
	// InfoLevel should be used for logging events and basic information
	InfoLevel
	// DebugLevel should be used for logging variables during debugging
	DebugLevel
	// TraceLevel should be used for extremely detailed logs
	TraceLevel
)

Available log levels:

func (LogLevel) String 

func (logLevel LogLevel) String(colorLogging bool, logLevelColorMap LogLevelColorMap) (str string)

String will stringify the log level into a readable format and color it if necessary.

type LogLevelColorMap added in v0.3.0 

type LogLevelColorMap map[LogLevel][]Attribute

LogLevelColorMap lists which text attributes should be used for each log level.

func NewLogLevelColorMap added in v0.3.0 

func NewLogLevelColorMap(opts ...LogLevelColorMapping) (logLevelColorMap LogLevelColorMap)

NewLogLevelColorMap creates and returns an instance of LogLevelColorMap with the default values.

func (LogLevelColorMap) Get added in v0.3.0 

func (logLevelColorMap LogLevelColorMap) Get(logLevel LogLevel) []Attribute

Get will return the list of text atrributes for a log level.

func (LogLevelColorMap) Options added in v0.5.0 

func (logLevelColorMap LogLevelColorMap) Options(opts ...LogLevelColorMapping)

Options will apply the given options to the log level color map. Any number of functional options can be passed to this method. You can read more information on functional options on the PLog wiki: https://github.com/pd93/plog/wiki/Functional-Options.

type LogLevelColorMapping added in v0.5.0 

type LogLevelColorMapping func(logLevelColorMap LogLevelColorMap)

A LogLevelColorMapping is a function that sets a color mapping on a given log level color map.

func WithLogLevelColorMapping added in v0.5.0 

func WithLogLevelColorMapping(logLevel LogLevel, attributes ...Attribute) LogLevelColorMapping

WithLogLevelColorMapping will return a function that sets a color mapping in a log level color map.

type Logger 

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

A Logger is a channel for writing logs.

func GetLogger 

func GetLogger(name string) *Logger

GetLogger returns the specified logger.

func NewCSVFileLogger 

func NewCSVFileLogger(file *File, opts ...LoggerOption) *Logger

NewCSVFileLogger creates and returns an instance of Logger which will write to the specified file. The log level is set to TraceLevel (log everything) and color logging is disabled. The logs will be written in CSV format, but the file name does not need to end in '.csv'. Any number of additional functional options can be passed to this method and they will be applied on creation. These additional options will override any of the settings mentioned above. You can read more information on functional options on the PLog wiki: https://github.com/pd93/plog/wiki/Functional-Options.

func NewJSONFileLogger 

func NewJSONFileLogger(file *File, opts ...LoggerOption) *Logger

NewJSONFileLogger creates and returns an instance of Logger which will write to the specified file. The log level is set to TraceLevel (log everything) and color logging is disabled. The logs will be written in JSON format, but the file name does not need to end in '.json'. Any number of additional functional options can be passed to this method and they will be applied on creation. These additional options will override any of the settings mentioned above. You can read more information on functional options on the PLog wiki: https://github.com/pd93/plog/wiki/Functional-Options.

func NewLogger 

func NewLogger(opts ...LoggerOption) (logger *Logger)

NewLogger creates and returns an instance of Logger with the default variables. Any number of functional options can be passed to this method and they will be applied on creation. You can read more information on functional options on the PLog wiki: https://github.com/pd93/plog/wiki/Functional-Options.

func NewTextFileLogger added in v0.4.0 

func NewTextFileLogger(file *File, opts ...LoggerOption) *Logger

NewTextFileLogger creates and returns an instance of Logger which will write to the specified file. The log level is set to TraceLevel (log everything) and color logging is disabled. The logs will be written in text format, but the file name does not need to end in '.txt'. Any number of additional functional options can be passed to this method and they will be applied on creation. These additional options will override any of the settings mentioned above. You can read more information on functional options on the PLog wiki: https://github.com/pd93/plog/wiki/Functional-Options.

func (*Logger) ColorLogging 

func (logger *Logger) ColorLogging() bool

ColorLogging will return whether or not color logging is enabled.

func (*Logger) Debug 

func (logger *Logger) Debug(variables ...interface{})

Debug will print any number of variables at debug level.

func (*Logger) Debugf 

func (logger *Logger) Debugf(format string, variables ...interface{})

Debugf will print a formatted message at debug level.

func (*Logger) Error 

func (logger *Logger) Error(err error)

Error will print a non-fatal error message.

func (*Logger) Errorf 

func (logger *Logger) Errorf(format string, err error)

Errorf will print a formatted, non-fatal error message.

func (*Logger) Fatal 

func (logger *Logger) Fatal(err error)

Fatal will print a fatal error message.

func (*Logger) Fatalf 

func (logger *Logger) Fatalf(format string, err error)

Fatalf will print a formatted, non-fatal error message.

func (*Logger) Formatter added in v0.4.0 

func (logger *Logger) Formatter() Formatter

Formatter will return the logger's current log format.

func (*Logger) Info 

func (logger *Logger) Info(variables ...interface{})

Info will print any number of variables at info level.

func (*Logger) Infof 

func (logger *Logger) Infof(format string, variables ...interface{})

Infof will print a formatted message at info level.

func (*Logger) LogLevel 

func (logger *Logger) LogLevel() LogLevel

LogLevel will return the logger's current log level.

func (*Logger) LogLevelColorMap added in v0.3.0 

func (logger *Logger) LogLevelColorMap() LogLevelColorMap

LogLevelColorMap will return the logger's text attributes for each log level.

func (*Logger) Options added in v0.5.0 

func (logger *Logger) Options(opts ...LoggerOption)

Options will apply the given options to the logger. Any number of functional options can be passed to this method. You can read more information on functional options on the PLog wiki: https://github.com/pd93/plog/wiki/Functional-Options.

func (*Logger) Output 

func (logger *Logger) Output() io.Writer

Output will return the logger's current output.

func (*Logger) TDebug added in v0.3.0 

func (logger *Logger) TDebug(tags Tags, variables ...interface{})

TDebug will print any number of variables at debug level and meta-tag the log.

func (*Logger) TDebugf added in v0.3.0 

func (logger *Logger) TDebugf(tags Tags, format string, variables ...interface{})

TDebugf will print a formatted message at debug level and meta-tag the log.

func (*Logger) TError added in v0.3.0 

func (logger *Logger) TError(tags Tags, err error)

TError will print a non-fatal error message and meta-tag the log.

func (*Logger) TErrorf added in v0.3.0 

func (logger *Logger) TErrorf(tags Tags, format string, err error)

TErrorf will print a formatted, non-fatal error message and meta-tag the log.

func (*Logger) TFatal added in v0.3.0 

func (logger *Logger) TFatal(tags Tags, err error)

TFatal will print a fatal error message and meta-tag the log.

func (*Logger) TFatalf added in v0.3.0 

func (logger *Logger) TFatalf(tags Tags, format string, err error)

TFatalf will print a formatted, fatal error message and meta-tag the log.

func (*Logger) TInfo added in v0.3.0 

func (logger *Logger) TInfo(tags Tags, variables ...interface{})

TInfo will print any number of variables at info level and meta-tag the log.

func (*Logger) TInfof added in v0.3.0 

func (logger *Logger) TInfof(tags Tags, format string, variables ...interface{})

TInfof will print a formatted message at info level and meta-tag the log.

func (*Logger) TTrace added in v0.3.0 

func (logger *Logger) TTrace(tags Tags, variables ...interface{})

TTrace will print any number of variables at trace level and meta-tag the log.

func (*Logger) TTracef added in v0.3.0 

func (logger *Logger) TTracef(tags Tags, format string, variables ...interface{})

TTracef will print a formatted message at trace level and meta-tag the log.

func (*Logger) TWarn added in v0.3.0 

func (logger *Logger) TWarn(tags Tags, variables ...interface{})

TWarn will print any number of variables at warn level and meta-tag the log.

func (*Logger) TWarnf added in v0.3.0 

func (logger *Logger) TWarnf(tags Tags, format string, variables ...interface{})

TWarnf will print a formatted message at warn level and meta-tag the log.

func (*Logger) TagColorMap added in v0.3.0 

func (logger *Logger) TagColorMap() TagColorMap

TagColorMap will return the logger's text attributes for each tag.

func (*Logger) TimestampFormat 

func (logger *Logger) TimestampFormat() string

TimestampFormat will return the logger's current timestamp format.

func (*Logger) Trace 

func (logger *Logger) Trace(variables ...interface{})

Trace will print any number of variables at debug level.

func (*Logger) Tracef 

func (logger *Logger) Tracef(format string, variables ...interface{})

Tracef will print a formatted message at debug level.

func (*Logger) Warn 

func (logger *Logger) Warn(variables ...interface{})

Warn will print any number of variables at warn level.

func (*Logger) Warnf 

func (logger *Logger) Warnf(format string, variables ...interface{})

Warnf will print a formatted message at warn level.

type LoggerOption added in v0.5.0 

type LoggerOption func(logger *Logger)

A LoggerOption is a function that sets an option on a given logger.

func WithColorLogging added in v0.5.0 

func WithColorLogging(colorLogging bool) LoggerOption

WithColorLogging will return a function that sets the color logging flag of a logger.

func WithFormatter added in v0.5.0 

func WithFormatter(formatter Formatter) LoggerOption

WithFormatter will return a function that sets the formatter of a logger. PLog includes several formatters for convenience (See `formatters` subpackage). Users can also provide a their own function if they want a custom format.

func WithLogLevel added in v0.5.0 

func WithLogLevel(logLevel LogLevel) LoggerOption

WithLogLevel will return a function that sets the log level of a logger.

func WithLogLevelColorMap added in v0.5.0 

func WithLogLevelColorMap(logLevelColorMap LogLevelColorMap) LoggerOption

WithLogLevelColorMap will return a function that sets the color of each log level for a logger.

func WithOutput added in v0.5.0 

func WithOutput(output io.Writer) LoggerOption

WithOutput will return a function that sets the output of a logger to the provided io.Writer. Examples include 'os.Stdout', 'os.File' and 'bytes.Buffer'.

func WithTagColorMap added in v0.5.0 

func WithTagColorMap(tagColorMap TagColorMap) LoggerOption

WithTagColorMap will return a function that sets the color of each tag for a logger.

func WithTimestampFormat added in v0.5.0 

func WithTimestampFormat(timestampFormat string) LoggerOption

WithTimestampFormat will return a function that sets the timestamp format of a logger. The default format is 'time.RFC3339'. You can find the documentation on time formatting in Golang here: https://golang.org/pkg/time/#Time.Format.

type Sequencer added in v0.5.0 

type Sequencer func(format, prev string) (next string, err error)

A Sequencer is a function that generates a file name for the next log file given the name of the previous file.

type Tag added in v0.3.0 

type Tag string

A Tag is a metadata string that can be assigned to any log message.

func (Tag) String added in v0.4.0 

func (tag Tag) String(colorLogging bool, tagColorMap TagColorMap) string

String will stringify the tag into a readable format and color it if necessary.

type TagColorMap added in v0.3.0 

type TagColorMap map[Tag][]Attribute

TagColorMap lists which text attributes should be used for each tag.

func NewTagColorMap added in v0.3.0 

func NewTagColorMap(opts ...TagColorMapping) (tagColorMap TagColorMap)

NewTagColorMap creates and returns an instance of TagColorMap with the default values.

func (TagColorMap) Get added in v0.3.0 

func (tagColorMap TagColorMap) Get(tag Tag) []Attribute

Get will return the list of text atrributes for a log level.

func (TagColorMap) Options added in v0.5.0 

func (tagColorMap TagColorMap) Options(opts ...TagColorMapping)

Options will apply the given options to the tag color map. Any number of functional options can be passed to this method. You can read more information on functional options on the PLog wiki: https://github.com/pd93/plog/wiki/Functional-Options.

type TagColorMapping added in v0.5.0 

type TagColorMapping func(tagColorMap TagColorMap)

A TagColorMapping is a function that sets a color mapping on a given tag color map.

func WithTagColorMapping added in v0.5.0 

func WithTagColorMapping(tag Tag, attributes ...Attribute) TagColorMapping

WithTagColorMapping will return a function that sets a color mapping in a tag color map.

type Tags added in v0.3.0 

type Tags []Tag

Tags is a slice of Tag.

func (Tags) String added in v0.5.0 

func (tags Tags) String(colorLogging bool, tagColorMap TagColorMap) (strs []string)

String will stringify the tag into a readable format and color it if necessary.

type Writer added in v0.5.0 

type Writer func(file *os.File, p []byte) (n int, err error)

A Writer is a function that writes to a file acording to a specifc set of rules.

Source Files

View all Source files

Directories

Path Synopsis
examples
basic_example
color_example
file_example
formatter_example
rotation_example
sequencer_example
tag_example
writer_example

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.