commonlog

CommonLog

A common Go API for structured and unstructured logging with support for runtime-pluggable backends.

The main design goal is to allow for libraries that can integrate well with others without having to change their logging code. For example, a library can plug into the klog backend if it's being used together with the Kubernetes client.

A secondary design goal is to provide a home for a full-featured unstructured logging library, which we here call the "simple" backend. It supports rich formatting, including ANSI coloring when logging to a terminal, including on Windows.

API features:

• Fine-grained control over verbosity via hierarchical log names. For example, "engine.parser.background" inherits from "engine.parser", which in turn inherits from "engine". The empty name is the root of the hierarchy. Each name's default verbosity is that of its parent, which you can then override with commonlog.SetMaxLevel.
• Support for call stack depth. This can be used by a backend (for example, klog) to find out where in the code the logging happened.
• No need to create loggers. The true API entrypoint is the global function commonlog.NewMessage, which you provide with a name and a level. The default logger type is just a convenient wrapper around it that provides the familiar unstructured functions.
• That said, the commonlog.Logger type is an interface, allowing you to more easily switch implementations. For example, you can assign the commonlog.MOCK_LOGGER to disable a logger without changing your code. (It's unfortunate that Go's Logger type is a struct.)

Basic Usage

The easiest way to plug in a backend is to anonymously import the correct sub-package into your program's main package:

import (
    _ "github.com/tliron/commonlog/simple"
)

This should enable the backend with sensible defaults. Specifically it will log to stderr with verbosity at the "notice" max level.

Example of structured logging:

import (
    "github.com/tliron/commonlog"
    _ "github.com/tliron/commonlog/simple"
    "github.com/tliron/kutil/util"
)

func main() {
    if m := commonlog.NewMessage([]string{"engine", "parser"}, commonlog.Error, 0); m != nil {
        m.Set("message", "Hello world!").Set("myfloat", 10.2).Send()
    }
    util.Exit(0)
}

Note that commonlog.NewMessage will return nil if the message cannot be created, for example if the message level is higher than the max level for that name.

Set can accept any key and value, but two keys are recognized by the API:

• message: The main description of the message. This is the key used by unstructured logging.
• scope: An optional identifier that can be used to group messages, making them easier to filter (e.g. by grep). Backends may handle this specially. Unstructured backends may, for example, add it as a bracketed prefix for messages.

Also note that calling util.Exit(0) to exit your program is not absolutely necessary, however it's good practice because it makes sure to flush buffered log messages for some backends.

Example of unstructured logging:

import (
    "github.com/tliron/commonlog"
    _ "github.com/tliron/commonlog/simple"
    "github.com/tliron/kutil/util"
)

var log = commonlog.GetLogger("engine.parser")

func main() {
    log.Errorf("Hello %s!", "world")
    util.Exit(0)
}

Use conditional logging to optimize for costly unstructured message creation, e.g.:

if log.AllowLevel(commonlog.Debug) {
    log.Debugf("Status is: %s", getStatusFromDatabase())
}

The scope logger can be used to automatically set the "scope" key for another logger. It automatically detects nesting, in which case it appends the new scope separated by a ".", e.g.:

var log = commonlog.GetLogger("engine.parser")
var validationLog = commonlog.NewScopeLogger(log, "validation")
var syntaxLog = commonlog.NewScopeLogger(validationLog, "syntax")

func main() {
    // Nested scope will be "validation.syntax"
    syntaxLog.Errorf("Hello %s!", "world")
    ...
}

Configuration

All backends can be configured via the same API. For example, to increase verbosity and write to a file:

func main() {
    path := "myapp.log"
    commonlog.Configure(1, &path)
    ...
}

Backends may also have their own (non-portable) configuration APIs.

You can set the max level (verbosity) using either the global API or a logger. For example, here is a way to make all logging verbose by default, except for one name:

func init() {
    commonlog.SetMaxLevel(nil, commonlog.Debug) // nil = the root
    commonlog.SetMaxLevel([]string{"engine", "parser"}, commonlog.Error)
}

Note that descendents of "engine.parser", e.g. "engine.parser.analysis", would acquire its log levels rather than the root's. Here's the same effect using loggers:

var rootLog = commonlog.GetLogger("")
var parserLog = commonlog.GetLogger("engine.parser")

func init() {
    rootLog.SetMaxLevel(commonlog.Debug)
    parserLog.SetMaxLevel(commonlog.Error)
}

It's important to note that the configuration APIs are not thread safe. This includes Configure and SetMaxLevel. Thus, make sure to get all your configuration done before you start sending log messages. A good place for this is init() or main() functions.

Color

For the simple backend you must explicitly attempt to enable ANSI color if desired. Note that if it's unsupported by the terminal then no ANSI codes will be sent (unless you force it via terminal.EnableColor(true)):

import (
    "github.com/tliron/commonlog"
    _ "github.com/tliron/commonlog/simple"
    "github.com/tliron/kutil/terminal"
    "github.com/tliron/kutil/util"
)

func main() {
    terminal.EnableColor(false)
    commonlog.GetLogger("engine.parser").Error("Hello world!") // errors are in red
    util.Exit(0)
}