README
¶
clog
Clog is a logger that works by receiving values, including closures, on channels and triggering an output through a configurable output function. The log level can be changed on the fly and immediately takes effect. There is colour available for tags if desired.
Documentation
See here at our private godoc (or go get it and run your own :) )
Automatic
As soon as you import it into your application it is instantly activated by an automatic init routine, and is available package-wide, enabling easy per-subsystem logging based on the application's filesystem hierarchy, as well as within packages, it is a one liner to declare a new subsystem.
Channel-based
Because the loggers are channel based, the overhead of logging function calls, which can be quite extensive, is completely eliminated from the main goroutines the logging calls are located.
Each log call only costs the processing time for loading a channel and notifying the main goroutine manager that the channel now has a new thing in it, which will run in a separate goroutine from where the log strings were sent.
To further reduce interruptions inside intensive, long running loops, there is a 'closure' type which can be used to embed more expensive queries for internal data that will only incur a processing cost if the log level is enabled.
Thus, in the background thread running the subsystem logger, when the log level enabled is lower than the specific entry in question, the cost will be in receiving the log string or pointer to the closure, and then a comparison and if it aborts, the logger returns to waiting for the next log entry to arrive on its given channel.
Each subsystem spawns its own goroutine, and disabled ones just discard, so even within the subsystem, actually processing enabled log levels are in separate threads as well.
Subsystems
One simply calls clog.NewSubSystem with a name and level and you get back a struct containing named channels that sit waiting to prepend your prescribed name string on whatever you put in the channel, and then forward it to the appropriate level of the root clog logger (accessible through clog.L).
It is recommended to make all of the names right-padded with spaces in order to keep the start of log entries in a consistent position, this is not handled automatically.
Example launch and log
ss := clog.NewSubSystem("TEST", clog.Ndbg)
ss.Info <- "this will print an info message"
Output will be like this:
2019-01-15 11:59:58.155324 UTC [INF] this will print an info message
Note also that by default, the log level identifiers are colour coded to help more easily distinguish between log types.
Documentation
¶
Overview ¶
Package cl is clog, the channel logger
What's this for ¶
Many processes involve very tight loops that number in the hundreds of nanoseconds per iteration, and logging systems can contribute a significant additional time to this.
This library provides a logging subsystem that works by pushing logging data into channels and allowing the cost of logging to be minimised especially in tight loop situations. To this end also there is a closure channel type that lets you defer the query of data for a log indefinitely if the log level is currenntly inactive.
The main benefit of using channels to coordinate logging is that it allows logging to occupy a separate thread to execution, meaning issues involving blocking on the processing but especially output to pipes and tty devices never affects main loops directly.
Index ¶
- Variables
- func GetLevelOpts() (s []string)
- func Shutdown()
- type Dbg
- type Debug
- type Debugc
- type Debugf
- type Err
- type Error
- type Errorc
- type Errorf
- type Fatal
- type Fatalc
- type Fatalf
- type Ftl
- type Inf
- type Info
- type Infoc
- type Infof
- type Registry
- type StringClosure
- type SubSystem
- func (s *SubSystem) Close()
- func (s *SubSystem) Dbgc(closure StringClosure)
- func (s *SubSystem) Errc(closure StringClosure)
- func (s *SubSystem) Ftlc(closure StringClosure)
- func (s *SubSystem) Infc(closure StringClosure)
- func (s *SubSystem) SetLevel(level string)
- func (s *SubSystem) Trcc(closure StringClosure)
- func (s *SubSystem) Wrnc(closure StringClosure)
- type Trace
- type Tracec
- type Tracef
- type Trc
- type Value
- type Warn
- type Warnc
- type Warnf
- type Wrn
Constants ¶
This section is empty.
Variables ¶
var Color = true
Color turns on and off colouring of error type tag
var ColorChan = make(chan bool)
ColorChan accepts a bool and flips the state accordingly
var Ine = func() error { _, file, line, _ := runtime.Caller(1) return fmt.Errorf("[%s:%d]", file, line) }
Ine (cl.Ine) returns caller location in source code
var Levels = map[string]int{
"off": _off,
"fatal": _fatal,
"error": _error,
"warn": _warn,
"info": _info,
"debug": _debug,
"trace": _trace,
}
Levels is the map of name to level
var Og = make(chan interface{}, 1)
Og is the root channel that processes logging messages, so, cl.Og <- Fatalf{"format string %s %d", stringy, inty} sends to the root
var Quit = make(chan struct{})
Quit signals the logger to stop. Invoke like this:
close(clog.Quit)
You can call init() again to start it up again
var Register = make(Registry)
Register is the central registry for the logger
var ShuttingDown bool
ShuttingDown indicates if the shutdown switch has been triggered
var Writer = io.MultiWriter(os.Stdout)
Writer is the place thelogs put out
Functions ¶
func GetLevelOpts ¶
func GetLevelOpts() (s []string)
Types ¶
type Debug ¶
type Debug Value
Debug is a log value that indicates level and how to interpret the interface slice
type Debugc ¶
type Debugc StringClosure
Debugc is for passing a closure when the log entry is expensive to compute
type Debugf ¶
type Debugf Value
Debugf is a log value that indicates level and how to interpret the interface slice
type Error ¶
type Error Value
Error is a log value that indicates level and how to interpret the interface slice
type Errorc ¶
type Errorc StringClosure
Errorc is for passing a closure when the log entry is expensive to compute
type Errorf ¶
type Errorf Value
Errorf is a log value that indicates level and how to interpret the interface slice
type Fatal ¶
type Fatal Value
Fatal is a log value that indicates level and how to interpret the interface slice
type Fatalc ¶
type Fatalc StringClosure
Fatalc is for passing a closure when the log entry is expensive to compute
type Fatalf ¶
type Fatalf Value
Fatalf is a log value that indicates level and how to interpret the interface slice
type Info ¶
type Info Value
Info is a log value that indicates level and how to interpret the interface slice
type Infoc ¶
type Infoc StringClosure
Infoc is for passing a closure when the log entry is expensive to compute
type Infof ¶
type Infof Value
Infof is a log value that indicates level and how to interpret the interface slice
type Registry ¶
Registry is a map of all the subsystems that have been started up
func (*Registry) Get ¶
Get returns the subsystem. This could then be used to close or set its level eg `*r.Get("subsystem").SetLevel("debug")`
func (*Registry) List ¶
List returns a string slice containing all the available subsystems registered with clog
func (*Registry) SetAllLevels ¶
type StringClosure ¶
type StringClosure func() string
StringClosure is a function that returns a string, used to defer execution of expensive logging operations
type SubSystem ¶
type SubSystem struct {
Name string
Ch chan interface{}
Level int
LevelString string
MaxLen int
// contains filtered or unexported fields
}
A SubSystem is a logger with a specific prefix name prepended to the entry
func NewSubSystem ¶
NewSubSystem starts up a new subsystem logger
func (*SubSystem) Dbgc ¶
func (s *SubSystem) Dbgc(closure StringClosure)
Dbgc appends the subsystem name to the front of a closure's output and this runs only if the log entry is called
func (*SubSystem) Errc ¶
func (s *SubSystem) Errc(closure StringClosure)
Errc appends the subsystem name to the front of a closure's output and this runs only if the log entry is called
func (*SubSystem) Ftlc ¶
func (s *SubSystem) Ftlc(closure StringClosure)
Ftlc appends the subsystem name to the front of a closure's output and this runs only if the log entry is called
func (*SubSystem) Infc ¶
func (s *SubSystem) Infc(closure StringClosure)
Infc appends the subsystem name to the front of a closure's output and this runs only if the log entry is called
func (*SubSystem) Trcc ¶
func (s *SubSystem) Trcc(closure StringClosure)
Trcc appends the subsystem name to the front of a closure's output and this runs only if the log entry is called
func (*SubSystem) Wrnc ¶
func (s *SubSystem) Wrnc(closure StringClosure)
Wrnc appends the subsystem name to the front of a closure's output and this runs only if the log entry is called
type Trace ¶
type Trace Value
Trace is a log value that indicates level and how to interpret the interface slice
type Tracec ¶
type Tracec StringClosure
Tracec is for passing a closure when the log entry is expensive to compute
type Tracef ¶
type Tracef Value
Tracef is a log value that indicates level and how to interpret the interface slice
type Warn ¶
type Warn Value
Warn is a log value that indicates level and how to interpret the interface slice
type Warnc ¶
type Warnc StringClosure
Warnc is for passing a closure when the log entry is expensive to compute
Source Files