plog

package module
v0.5.1 Latest Latest
Warning

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

 Go to latest Published: Dec 21, 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(variables ...interface{})

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

func Errorf 

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

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

func Fatal 

func Fatal(variables ...interface{})

Fatal will print a fatal error message to all loggers.

func Fatalf 

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

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 

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 

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

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

func TDebugf 

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

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

func TError 

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

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

func TErrorf 

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

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

func TFatal 

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

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

func TFatalf 

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

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

func TInfo 

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

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

func TInfof 

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

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

func TTrace 

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

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

func TTracef 

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

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

func TWarn 

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

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

func TWarnf 

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 

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 

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 

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 

func (file *File) Format() string

Format returns the format of the file name.

func (*File) MaxFileSize 

func (file *File) MaxFileSize() int64

MaxFileSize returns the maximum file size allowed.

func (*File) Options 

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 

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 

func (file *File) Sequencer() Sequencer

Sequencer returns the sequencer function used to determine file names.

func (*File) ShouldRotate 

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 

func (file *File) Writer() Writer

Writer returns the writer used to log the messages.

type FileOption 

type FileOption func(file *File)

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

func WithFormat 

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 

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 

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 

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 

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 

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

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

func (*Log) LogLevel 

func (log *Log) LogLevel() LogLevel

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

func (*Log) Tags 

func (log *Log) Tags() Tags

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

func (*Log) Timestamp 

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

Timestamp will return the log creation timestamp.

func (*Log) Variables 

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 

type LogLevelColorMap map[LogLevel][]Attribute

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

func NewLogLevelColorMap 

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

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

func (LogLevelColorMap) Get 

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

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

func (LogLevelColorMap) Options 

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 

type LogLevelColorMapping func(logLevelColorMap LogLevelColorMap)

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

func WithLogLevelColorMapping 

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 

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 

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 

func (logger *Logger) LogLevelColorMap() LogLevelColorMap

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

func (*Logger) Options 

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 

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 

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 

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

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

func (*Logger) TErrorf 

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 

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

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

func (*Logger) TFatalf 

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 

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 

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 

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 

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 

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 

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 

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 

type LoggerOption func(logger *Logger)

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

func WithColorLogging 

func WithColorLogging(colorLogging bool) LoggerOption

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

func WithFormatter 

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 WithGlobalLogging 

func WithGlobalLogging(globalLogging bool) LoggerOption

WithGlobalLogging controls whether or not to include this logger when printing via the global logger map. If set to false, this logger will only be written to when manually called on the logger itself.

func WithLogLevel 

func WithLogLevel(logLevel LogLevel) LoggerOption

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

func WithLogLevelColorMap 

func WithLogLevelColorMap(logLevelColorMap LogLevelColorMap) LoggerOption

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

func WithOutput 

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 

func WithTagColorMap(tagColorMap TagColorMap) LoggerOption

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

func WithTimestampFormat 

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 

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 

type Tag string

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

func (Tag) String 

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 

type TagColorMap map[Tag][]Attribute

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

func NewTagColorMap 

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

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

func (TagColorMap) Get 

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

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

func (TagColorMap) Options 

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 

type TagColorMapping func(tagColorMap TagColorMap)

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

func WithTagColorMapping 

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

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

type Tags 

type Tags []Tag

Tags is a slice of Tag.

func (Tags) String 

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 

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