llog

README

go-llog

The leven logging library

A simple general purpose logging library with multiple logging levels

Goals

The goal in llog is to write logs which have a general, static error message attached to them, describing what kind of an message happened and at what step it happened, but leaving out any context about the message (such as which user caused it, or what a particular parameter to a function was). The context is then provided in the form of optional key/value pairs, which can then be easily parsed by something like elk.

The benefits of this system is that it makes it very easy to categorize messages, and also very easy to scan all messages across services for a particular pattern. For instance, if you always include the IP address in the key/value set across all projects, you can very easily determine all the actions taken by a particular IP address.

Usage

import "github.com/levenlabs/go-llog"

func main() {
    llog.Info("Here's a generic log message!")
    llog.Error("an error happened", llog.KV{"userID":1111, "err": err, "sky": "blue"})
}

These will output:

~ INFO -- Here's a generic log message!
~ ERROR -- an error happened -- userID="1111" err="some error" sky="blue"

log.Logger

If you need a log.Logger interface you can use NewLogger(level, KV) and it will take each string sent to the Logger interface and log it via the default llog instance with the sent level and with the sent KV.

You can also send filter functions into NewLogger if you wish to filter out spammy or annoying log messages.

Once https://github.com/golang/go/issues/13182 is resolved and there is a better interface we expect that the above solution would be depreated in favor of the new interface.

Tests

If you have logging output during tests, the asynchronous nature of the logging might end up mangling the "--- PASS: Function" output which could cause CI parsing to think a test failed. You should set BlockByDefault to true during tests if that is affecting you.

Documentation

Overview

Package llog is a generic logging library used by leven labs. The log methods come in different severities: Debug, Info, Warn, Error, and Fatal.

The log methods take in a string describing the error, and a set of key/value pairs giving the specific context around the error. The string is intended to always be the same no matter what, while the key/value pairs give information like which userID the error happened to, or any other relevant dynamic information.

By default logs will be output to Stdout, without a timestamp attached to them, and only showing entries of level Info or above. All of these can be configured.

All public functions in this package are thread-safe and can be called at any time. The public variables in this package are NOT thread-safe and should only be modified before any logging takes place

Examples:

Info("Something important has occurred")
Error("Could not open file", llog.KV{"filename": filename}, llog.ErrKV(err))

Index

• Variables
• func CtxWithKV(ctx context.Context, kvs ...KV) context.Context
• func Debug(msg string, kv ...KV)
• func ErrWithKV(err error, kvs ...KV) error
• func Error(msg string, kv ...KV)
• func Fatal(msg string, kv ...KV)
• func Flush()
• func Info(msg string, kv ...KV)
• func NewLogger(lvl Level, kv KV, filters ...func(string) (string, error)) *log.Logger
• func NewWriter(lvl Level, kv KV, filters ...func(string) (string, error)) io.Writer
• func SetLevel(l Level)
• func SetLevelFromString(ls string) error
• func Truncate(s string, size int) string
• func Warn(msg string, kv ...KV)
• type KV
  • func CtxKV(ctx context.Context) KV
  • func ErrKV(err error) KV
  • func Merge(kvs ...KV) KV
  • func (kv KV) Copy() KV
  • func (kv KV) Set(k string, v interface{}) KV
  • func (kv KV) StringSlice() [][2]string
• type Level
  • func GetLevel() Level
  • func (l Level) String() string
• type LogFunc

Variables

var BlockByDefault = false

BlockByDefault controls whether the non-Fatal functions wait for the write to Out to complete. This can be useful to set to true for tests so that logging doesn't end up mangling test output.

var DisplayTimestamp bool

DisplayTimestamp determines whether or not a timestamp is displayed in the log messages. By default one is not displayed. This can be changed by it should only be changed before any logging occurs

var Out io.Writer = os.Stdout

Out is the io.Writer all log entries will be written to. It can be changed to anything you like, but the change should happen before any logging occurs. If an error occurs while writing to Out the entry will be written to Stdout instead

Functions

func CtxWithKV

func CtxWithKV(ctx context.Context, kvs ...KV) context.Context

CtxWithKV embeds a KV into a Context, returning a new Context instance. If the Context already has a KV embedded in it then the returned context's KV will be the merging of the two.

func Debug

func Debug(msg string, kv ...KV)

Debug writes a Debug message to Out, with an optional set of key/value pairs which will be Merge'd together.

func ErrWithKV

func ErrWithKV(err error, kvs ...KV) error

ErrWithKV embeds the merging of a set of KVs into an error and Marks the function for convenience, returning a new error instance. If the error already has a KV embedded in it then the returned error will have the merging of them all.

func Error

func Error(msg string, kv ...KV)

Error writes an Error message to Out, with an optional set of key/value pairs which will be Merge'd together.

func Fatal

func Fatal(msg string, kv ...KV)

Fatal writes a Fatal message to Out, with an optional set of key/value pairs which will be Merge'd together. Once written the process will be exited with an exit code of 1

func Flush

func Flush()

Flush will attempts to flush any buffered data in Out. Will block until the flushing has been completed

func Info

func Info(msg string, kv ...KV)

Info writes an Info message to Out, with an optional set of key/value pairs which will be Merge'd together.

func NewLogger

func NewLogger(lvl Level, kv KV, filters ...func(string) (string, error)) *log.Logger

NewLogger returns an instance of log.Logger that uses llog to log the messages under the sent level with the passed KV. Multiple filter functions can be passed. If an error is returned from the filter function, it's sent to the caller of the Write method. If an empty string is returned then the message is ignored.

func NewWriter

func NewWriter(lvl Level, kv KV, filters ...func(string) (string, error)) io.Writer

NewWriter returns an io.Writer that uses llog to log the sent writes with the sent log level. Multiple filter functions can be passed. If an error is returned from the filter function, it's sent to the caller of the Write method. If an empty string is returned then the message is ignored.

func SetLevel

func SetLevel(l Level)

SetLevel sets the current minimum log level which will be written to Out

func SetLevelFromString

func SetLevelFromString(ls string) error

SetLevelFromString attempts to interpret the given string as a log level and sets the current log level to that. If the string can't be interpreted an error is returned and the log level remains what it was

func Truncate

func Truncate(s string, size int) string

Truncate is a helper function to truncate a string to a given size. It will add 3 trailing elipses, so the returned string will be at most size+3 characters long

func Warn

func Warn(msg string, kv ...KV)

Warn writes a Warn message to Out, with an optional set of key/value pairs which will be Merge'd together.

Types

type KV

type KV map[string]interface{}

KV is used to provide context to a log entry in the form of a dynamic set of key/value pairs which can be different for every entry.

func CtxKV

func CtxKV(ctx context.Context) KV

CtxKV returns a copy of the KV embedded in the Context by CtxWithKV

func ErrKV

func ErrKV(err error) KV

ErrKV returns a copy of the KV embedded in the error by ErrWithKV as well as any line from errctx.Mark as the key "source" if "source" wasn't already set. Returns empty KV if no KV was previously embedded and no line was marked. Will automatically set the "err" field on the returned KV as well.

func Merge

func Merge(kvs ...KV) KV

Merge takes in multiple KVs and returns a single KV which is the union of all the passed in ones. Key/vals on the rightmost of the set take precedence over conflicting ones to the left. This function will never return nil

func (KV) Copy

func (kv KV) Copy() KV

Copy returns a copy of the KV being called on. This method will never return nil

func (KV) Set

func (kv KV) Set(k string, v interface{}) KV

Set returns a copy of the KV being called on with the given key/val set on it. The original KV is unaffected

func (KV) StringSlice

func (kv KV) StringSlice() [][2]string

StringSlice converts the KV into a slice of [2]string entries (first index is the key, second is the string form of the value).

type Level

type Level int

Level describes the severity of a particular log message

const (
	DebugLevel Level = iota
	InfoLevel
	WarnLevel
	ErrorLevel
	FatalLevel
)

All defined log levels

func GetLevel

func GetLevel() Level

GetLevel returns the current log level

func (Level) String

func (l Level) String() string

type LogFunc

type LogFunc func(string, ...KV)

LogFunc is the function signature used by the different log functions (Debug, Info, Warn, Error, and Fatal). It's useful for writing wrapper functions