loggos

README

loggos

Contents

Description

Loggos is a flexible logging package for sending logs in line format and json. Born out of need for a logging package that does both standard line logging and also json logging.

How To Use Loggos

Loggos is intended to be easy to use and flexible enough to fit most projects.

There are shortcut methods to make use of both line logger and the JSON Logger. They mimic the signature of the fmt package. These are used for simple usage of the loggers. More advanced logging is discussed further down.

Line messages are simple message that hold generally unstructured logs and are very useful in small project.

// Sending line messages
Infoln("Test Message - Infoln")
Warnln("Test Message - Warnln")
Critln("Test Message - Critln")
Debugln("Test Message - Debugln")

Infof("Test Message - %s", "Infof")
Warnf("Test Message - %s", "Warnf")
Critf("Test Message - %s", "Critf")
Debugf("Test Message - %s", "Debugf")

JSON logging is used for structured logging and generally requires a bit more effort to use but is far better in the long run as the data in the logs is easy to digest into centralized logging platforms and aggregators.

// Make a message using one of these lines.
m := JSONInfoln("Test Message - JSONInfoln")
m := JSONWarnln("Test Message - JSONWarnln")
m := JSONCritln("Test Message - JSONCritln")
m := JSONDebugln("Test Message - JSONDebugln")

m := JSONInfof("Test Message - %s", "JSONInfof")
m := JSONWarnf("Test Message - %s", "JSONWarnf")
m := JSONCritf("Test Message - %s", "JSONCritf")
m := JSONDebugf("Test Message - %s", "JSONDebugf")

//Decorate with the Add function
m.Add(key string, value interface{})

// Then Send
SendJSON(m)

Debugging needs to be turned on using the following functions.

DefaultJSONLogger.EnableDebugLogging(true|false)
DefaultLineLoggerBuffer.EnableDebugLogging(true|false)

Flexibility of Loggos

Loggos flexibility comes in 3 shared features.

• Allow users to override where logs get shipped to
• Allow users to override the time stamping
• Allow users to choose between best effort and audit shipping

Also JSON Messages with the logger have addition features

• Allow users to add default keys values pairs to all messages
• Allow users to mutate messages BEFORE they get sent to the printers buffer

Overriding the Send function

Sending logs to a aggregator is something that all people that need to do it do differently. It's dependent on your project, company and products that you make use of. It is therefore best left to the operator to make that choice and integration.

By default logs will get printed out to STDOUT. Which in most cases is fine. However when it is not you can override the where the logs go and maybe process them before shipping. See below an example of a override.

// Overrides have a interface to satisfy. Very simple.
//type Overrider interface {
//	Send(string)
//}

// Therefore this is acceptable.
type overrider struct{}
func (o overrider) Send(){}

overRider := overrider{}

DefaultJSONLogger.OverridePrinter(overRide)
DefaultLineLogger.OverridePrinter(overRide)

Overriding the time stamp

Line logger

When using the line logger you need to set and overrider for timestamps. The only requirement is that your passed in fuction need return a single string. It is not the business of loggos to decide what your time stamps should look like. In fact in testing we just set them to a static word. You are the master of your own time stamp.

// Change the default loggers time stamping
func timeStampOverrider() string {
  return "overridden"
}
DefaultLineLogger.OverrideTimeStamping(timeStampOverrider)

JSON Messages

JSON messages offer greater flexibility by storing the time stamp as a message field that you can override after creating the message.

The time stamp uses the default time stamp gained from time.Now().UnixNano().

If you to change the default timestamp you need to change the value stored in loggos.jsonessage.JSONTimeStampFunc with your own struct that satisfies the interface of loggos.jsonessage.JSONTimeStamper. Which is basically anything with a Stamp() string function.

The time stamp message field can also be changed by changing the string stored in loggos.jsonessage.JSONTimeStampKey.

// Make something that satisfies loggos.jsonessage.JSONTimeStamper
type stamper struct {}
func (s stamper) Stamp() string {return "moreFunStuff"}

// Set the default vars
loggos.jsonessage.JSONTimeStampKey = "somethingFun"
loggos.jsonessage.JSONTimeStamper = &stamper{}

Changing the loggers behavior

Logging generally follows two paths with regards to shipping.

1. Logging is less important than service and should never impact service delivery. This is called best effort logging.
2. Logging is more important than service delivery and must be done before moving on. This is called auditing.

With this in mind there are 2 ways that loggos will work. Unsurprisingly:

Best Effort

Logs are put into a buffer and printed as fast as the logger can push them out. The buffer is set by default in loggos.DefaultLineLoggerBuffer and loggos.DefaultJSONLoggerBuffer. If the buffer is filled up then new messages are dropped. If your logger is slow then you should increase the buffer limits. Just beware that larger buffer means more potential memory usage.

Audit Mode

Logs are put into a buffer, if the buffer is full then the logger waits till there is space available in the buffer. You can tweak this to allow for some risk by increasing the buffer size. If you are planning on using audit mode then you should make a really small buffer size, maybe 1.

Decorators

JSON Printers can store key value pairs in the form of map[string]interface{} that are attached to all log messages that get sent to the printer. These are sent BEFORE the below mutators are called. Use this to add something like the hostname of your server that is running your application or to add a containers tracing information.

Decorators will overwrite information that is stored in place of the keys before they get applied.

hostname, _ := os.Hostname
decoration := map[string]interface{}{
  "hostname": hostname,
}

jp := jsonprinter.New(10)
jp.AddDecorator(decoration)

Mutators

Mutators are more dangerous and you need to be careful with them. They can have destructive force over the log. They differ to decorators in that they allow you to add and remove data as well as allowing the message to be deleted.

Mutators are a simple interfaces that match the jsonprinter.Mutator signature

Mutate func(*jsonmessage.JSONMessage) bool.

To gain access to the json messages data call JSONMessage.RawDump().

You can add, remove or modify data here. If the modification fails you can return a false which will indicate to the printer that it should discard the message. If everything goes well return a true and your modified log message will be put into the printers buffer.

Documentation

Index

• Variables
• func Critf(format string, vars ...interface{})
• func Critln(msg ...interface{})
• func Debugf(format string, vars ...interface{})
• func Debugln(msg ...interface{})
• func Flush() chan bool
• func Infof(format string, vars ...interface{})
• func Infoln(msg ...interface{})
• func JSONCritf(format string, vars ...interface{}) *jsonmessage.JSONMessage
• func JSONCritln(msg ...interface{}) *jsonmessage.JSONMessage
• func JSONDebugf(format string, vars ...interface{}) *jsonmessage.JSONMessage
• func JSONDebugln(msg ...interface{}) *jsonmessage.JSONMessage
• func JSONInfof(format string, vars ...interface{}) *jsonmessage.JSONMessage
• func JSONInfoln(msg ...interface{}) *jsonmessage.JSONMessage
• func JSONLoggerAddDecoration(decoration map[string]interface{})
• func JSONLoggerAddMutator(m jsonprinter.Mutator)
• func JSONLoggerEnableDebugLogging(toggle bool)
• func JSONLoggerEnableHumanTimestamps(toggle bool)
• func JSONLoggerEnablePrettyPrint(toggle bool)
• func JSONWarnf(format string, vars ...interface{}) *jsonmessage.JSONMessage
• func JSONWarnln(msg ...interface{}) *jsonmessage.JSONMessage
• func LineLoggerEnableDebugLogging(toggle bool)
• func SendJSON(msg *jsonmessage.JSONMessage)
• func Warnf(format string, vars ...interface{})
• func Warnln(msg ...interface{})

Variables

var (
	// DefaultLineLogger is a logger that you can just call upon when you start your application.
	DefaultLineLogger lineprinter.DebugLineLogger
	// DefaultJSONLogger is a logger that you can just call upon when you start your application.
	DefaultJSONLogger jsonprinter.DebugJSONLogger
	// DefaultLineLoggerBuffer holds how many lines the line buffer will hold onto before it starts to drop
	// or slow down the application.
	DefaultLineLoggerBuffer = 500
	// DefaultJSONLoggerBuffer holds how many json messages the line buffer will hold onto before it starts to drop
	// or slow down the application.
	DefaultJSONLoggerBuffer = 500
)

Functions

func Critf

func Critf(format string, vars ...interface{})

func Critln

func Critln(msg ...interface{})

func Debugf

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

func Debugln

func Debugln(msg ...interface{})

func Flush

func Flush() chan bool

Flush on the package will stop the default logging engines that you have made use of. It will close the channel once all logging engines have flushed everything and stopped.

func Infof

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

func Infoln

func Infoln(msg ...interface{})

func JSONCritf

func JSONCritf(format string, vars ...interface{}) *jsonmessage.JSONMessage

JSONCritf is a shortcut function that will give you a JSON Message that is populated with time, level and your message ready to be shipped. It can still be decorated with more keys if needed.

func JSONCritln

func JSONCritln(msg ...interface{}) *jsonmessage.JSONMessage

JSONCritln is a shortcut function that will give you a JSON Message that is populated with time, level and your message ready to be shipped. It can still be decorated with more keys if needed.

func JSONDebugf

func JSONDebugf(format string, vars ...interface{}) *jsonmessage.JSONMessage

JSONDebugf is a shortcut function that will give you a JSON Message that is populated with time, level and your message ready to be shipped. It can still be decorated with more keys if needed.

func JSONDebugln

func JSONDebugln(msg ...interface{}) *jsonmessage.JSONMessage

JSONDebugln is a shortcut function that will give you a JSON Message that is populated with time, level and your message ready to be shipped. It can still be decorated with more keys if needed.

func JSONInfof

func JSONInfof(format string, vars ...interface{}) *jsonmessage.JSONMessage

JSONInfof is a shortcut function that will give you a JSON Message that is populated with time, level and your message ready to be shipped. It can still be decorated with more keys if needed.

func JSONInfoln

func JSONInfoln(msg ...interface{}) *jsonmessage.JSONMessage

JSONInfoln is a shortcut function that will give you a JSON Message that is populated with time, level and your message ready to be shipped. It can still be decorated with more keys if needed.

func JSONLoggerAddDecoration

func JSONLoggerAddDecoration(decoration map[string]interface{})

JSONLoggerAddDecoration starts the default JSON logger if not already started then adds the supplied decoration to the list.

func JSONLoggerAddMutator

func JSONLoggerAddMutator(m jsonprinter.Mutator)

JSONLoggerAddMutator starts the default JSON logger if not already started then adds the supplied mutator to the list.

func JSONLoggerEnableDebugLogging

func JSONLoggerEnableDebugLogging(toggle bool)

JSONLoggerEnableDebugLogging Starts the default JSON logger if not already started then enabled debug logging.

func JSONLoggerEnableHumanTimestamps

func JSONLoggerEnableHumanTimestamps(toggle bool)

JSONLoggerEnableHumanTimestamps starts the default JSON logger if not already started then enabled human timestamping requests on future logs

func JSONLoggerEnablePrettyPrint

func JSONLoggerEnablePrettyPrint(toggle bool)

JSONLoggerEnablePrettyPrint starts the default JSON logger if not already started then enabled debug logging

func JSONWarnf

func JSONWarnf(format string, vars ...interface{}) *jsonmessage.JSONMessage

JSONWarnf is a shortcut function that will give you a JSON Message that is populated with time, level and your message ready to be shipped. It can still be decorated with more keys if needed.

func JSONWarnln

func JSONWarnln(msg ...interface{}) *jsonmessage.JSONMessage

JSONWarnln is a shortcut function that will give you a JSON Message that is populated with time, level and your message ready to be shipped. It can still be decorated with more keys if needed.

func LineLoggerEnableDebugLogging

func LineLoggerEnableDebugLogging(toggle bool)

func SendJSON

func SendJSON(msg *jsonmessage.JSONMessage)

SendJSON is used to send a JSON message to the default JSON logger.

func Warnf

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

func Warnln

func Warnln(msg ...interface{})