README

go-llog

The leven logging library

GoDoc

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.

Expand ▾ Collapse ▴

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

    Constants

    This section is empty.

    Variables

    View Source
    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.

      View Source
      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

          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