cl

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 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
  • func (r *Registry) Add(s *SubSystem)
  • func (r *Registry) Get(name string) (out *SubSystem)
  • func (r *Registry) List() (out []string)
  • func (r *Registry) SetAllLevels(level string)
• type StringClosure
• type SubSystem
  • func NewSubSystem(name, level string) (ss *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

Variables

var (
	// Levels is the map of name to level
	Levels = map[string]int{
		"off":   _off,
		"fatal": _fatal,
		"error": _error,
		"warn":  _warn,
		"info":  _info,
		"debug": _debug,
		"trace": _trace,
	}
	// Color turns on and off colouring of error type tag
	Color = true
	// ColorChan accepts a bool and flips the state accordingly
	ColorChan = make(chan bool)
	// ShuttingDown indicates if the shutdown switch has been triggered
	ShuttingDown bool
	// Writer is the place thelogs put out
	Writer = io.MultiWriter(os.Stdout)
	// Og is the root channel that processes logging messages, so, cl.Og <- Fatalf{"format string %s %d", stringy, inty} sends to the root
	Og = make(chan interface{}, 27)

	// Quit signals the logger to stop. Invoke like this:
	//     close(clog.Quit)
	// You can call init() again to start it up again
	Quit = make(chan struct{})
	// Register is the registry of subsystems in operation
	Register = make(Registry)
	// GlobalLevel is the ostensible global level currently set
	GlobalLevel = "info"

	// LogDBC is a channel that can be set to push log messages to another goroutine
	//
	LogDBC chan string
)

var Ine = func() string {
	_, file, line, _ := runtime.Caller(1)
	files := strings.Split(file, "git.parallelcoin.io/dev/pod/")
	file = "./" + files[1]
	return colorstring.Color(fmt.Sprintf(" [dim]%s:%d", file, line))
}

Ine (cl.Ine) returns caller location in source code

var Ine3 = func() string {
	_, file, line, _ := runtime.Caller(3)
	return colorstring.Color(fmt.Sprintf(" [dim]%s:%d", file, line))
}

Ine3 (cl.Ine) returns caller location in source code

Functions

func Shutdown

func Shutdown()

Shutdown the application, allowing the logger a moment to clear the channels

Types

type Dbg

type Dbg string

Dbg is a log type that is just one string

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 Err

type Err string

Err is a log type that is just one string

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 Ftl

type Ftl string

Ftl is a log type that is just one string

type Inf

type Inf string

Inf is a log type that is just one string

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

type Registry map[string]*SubSystem

Registry is

func (*Registry) Add

func (r *Registry) Add(s *SubSystem)

Add appends a new subsystem to its map for access and introspeection

func (*Registry) Get

func (r *Registry) Get(name string) (out *SubSystem)

Get returns the subsystem. This could then be used to close or set its level eg `*r.Get("subsystem").SetLevel("debug")`

func (*Registry) List

func (r *Registry) List() (out []string)

List returns a string slice containing all the available subsystems registered with clog

func (*Registry) SetAllLevels

func (r *Registry) SetAllLevels(level string)

SetAllLevels is

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

func NewSubSystem(name, level string) (ss *SubSystem)

NewSubSystem starts up a new subsystem logger

func (*SubSystem) Close

func (s *SubSystem) Close()

Close a 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) SetLevel

func (s *SubSystem) SetLevel(level string)

SetLevel changes the level of a subsystem by level name

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 Trc

type Trc string

Trc is a log type that is just one string

type Value

type Value []interface{}

Value is the generic list of things processed by the log chan

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

type Warnf

type Warnf Value

Warnf is a log value that indicates level and how to interpret the interface slice

type Wrn

type Wrn string

Wrn is a log type that is just one string