Tech Spec - pd93/plog GitHub Wiki
The following document describes the technical specification for the PLog library. It provides an overview of the structures and functions and the flow of data through them.
Components
Log
A Log
is a representation of a single message created by one of the logging functions (e.g. log.Info()
). This log is parsed to a logger (or loggers) for printing. Each log contains the log level, a timestamp, a series of tags and the string(s) or variable(s) to print.
Logger
A Logger
represents a single configuration for performing logging. You can create as many loggers as you need and each one can have a different output, format and configuration. All loggers have an unexported write()
method which is called when passing a Log
to that logger.
Formatter
It is the formatters job to turn a Log
into a string ready for writing to the configured output. PLog contains several commonly used formatters such as JSON and CSV as well as regular text format, but also allows the user to provide an entirely custom formatter function.
File
This structure wraps the standard library's os.File
structure and extends it by allowing for the automatic rotation of files and custom writers that can produce valid parsable files such as JSON and CSV. This component is not necessary to write to a file and if you don't require the above features you can just set a regular os.File
(or any other io.Writer
) as the output for a logger.
Sequencer
The sequencer is only used when the logger output is set to use plog.File
. It is used to determine the output of the next file's name if file rotation is enabled. Sequencers are designed to take the previous filename, deconstruct it and reconstruct a new one using a given format. PLog contains several basic sequencers, but also allows the user to provide an entirely custom sequencer function.
Writer
The writer is only used when the logger output is set to use plog.File
. It allows how users to control how the log messages are written to a file and make decisions based on the existing content. Some examples of uses include:
- File format validation (JSON/CSV)
- Seeking or writing to a specific location in the file
- Removal of extra whitespace / unsupported characters etc.
- Adding opening/closing punctuation or file headers.
PLog contains several commonly used writers such as JSON and CSV as well as regular text format, but also allows the user to provide an entirely custom writer function.
Note: The writer is not responsible for formatting the log message itself. This is the job of the log formatter which also supports JSON and CSV.
- Read more...
- TODO: Example
Flow Diagram
The diagram below roughly describes the flow between the above components. It is heavily simplified, but it helps to illustrate where components sit and how they interract with one another.