catlogger - categorical logging for Go

Copyright (C) 2023 Index Data ApS..

This software is distributed under the terms of the Apache License, Version 2.0. See the file LICENSE for more information.

• Introduction
• Example usage
• API
  • Constructor
  • Logging
  • Category inquiry
• Provenance
• Author

Introduction

catlogger is a tiny library to do categorical logging for Go.

By "categorical" or "category-based", we mean that categorical-logger can easily be configured to include or exclude different classes of log message (e.g. "app", "core", "calc", "okapiUrl", "supercalifragilisticexpialidocious", whatever we decide to include). This is much more flexible than the traditional approach of escalating levels DEBUG -> INFO -> WARN -> ERROR -> FATAL. (It can also of course be turned off completely in production.)

Category names may not contain commas, and typically consist entirely of letters, with multiple-word categories spelled in camelCase.

Example usage

import "github.com/MikeTaylor/catlogger"
// ...
var logger *catlogger.Logger
logger = catlogger.MakeLogger("listen,action", "", false)
logger.Log("config", "configuration complete") // Does not emit a message
logger.Log("listen", fmt.Sprintf("Listen port %d", 12368)) // Emits a message

This pulls in the library and creates a logger which is configured to emit messages in the categories "listen" and "action". Two messages are logged: one in the "config" category (for which no output will be generated since that category is not configured in the present logger) and one in the "listen" category (which will be emitted).

API

The API is gratifyingly small: a single class with a constructor and two methods (one of which is rarely if ever needed).

Constructor

The constructor returns a logging object which carries a small amount of configuration. That configuration is passed in when the object is created. The constructor arguments are:

1. categories (string). A comma-separated list of zero or more short strings, each of which is the name of a logging category. There is no predefined list of such categories: each application is welcome to make up its own.

2. prefix (string). If provided, a short string which is emitted at the beginning of each log message. If not required, pass an empty string.

3. timestamp (boolean). If true, then an ISO-formatted timestamp is included in each log message.

Logging

All logging is done with a single method, logger.log(STRING, ...VALUES). Its first argument is a string naming one of the application's logging categories, and the subsequent arguments are values to be included in the log message. The message is emitted only if the specified category is one of those configured in the logger.

Output is always to standard error.

Category inquiry

You can ask a logger whether it has a particular category enabled using logger.hasCategory(cat). This is a rather ugly back-door, but it's necessary for cases where another library does its own logging and you need to create a predicate for it based on the logger's categories.

Provenance

This module is our old friend categorical-logger (formerly @folio/stripes-logger), written in JavaScript, which traces its ancestry back to the YAZ Toolkit's yaz_log function.

For dumbass-news I did a simple port from the JavaScript version to Go. Rather than replicate that in subsequent Go programs, I decided to release it as its own tiny package and depend on that.

Author

Mike Taylor, Index Data ApS. Email mike@indexdata.com