catlogger

README

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

Documentation

Overview

catlogger is derived from the JavaScript package categorical-logger, which can be found at https://github.com/openlibraryenvironment/categorical-logger The present version of this library falls short of its ancestor in two respects:

1. It does not support logging functional arguments
2. It does not have the the setter methods

Index

• type Logger
  • func MakeLogger(categories string, prefix string, timestamp bool) *Logger
  • func (l *Logger) HasCategory(cat string) bool
  • func (l *Logger) Log(cat string, args ...string)

Types

type Logger

type Logger struct {
	// contains filtered or unexported fields
}

Logger is an opaque structure created by MakeLogger and which encapsulates the configuration passed into that function. Typically a program will make just one of these, and pass it around as necessary.

func MakeLogger

func MakeLogger(categories string, prefix string, timestamp bool) *Logger

MakeLogger creates a catlogger object on which the Log method may subsequently be called. The logger is configured by three parameters:

categories: a string containing zero or more comma-separated logging categories, such as "init,config,url", for which the logger should emit messages. There is no predefined list of categegories, and no hierarchy between categories -- unlike the FATAL, ERROR, WARN, INFO, DEBUG hierarchy in log4j and similar libraries. Applications can use whatever categories they wish.

prefix: a short string or nil. If the former, then it is included at the start of each log message.

timestamp: a boolean indicating whether or not a timestamp is to be included in each log message

func (*Logger) HasCategory

func (l *Logger) HasCategory(cat string) bool

HasCategory returns true is the logger has been configured to include the named category and false if not.

func (*Logger) Log

func (l *Logger) Log(cat string, args ...string)

Log does nothing if the named category is not among those that the logger is configured to use. But if the logged is configured to include the category, then it logs a message to standard error, consisting of the logger prefix (if defined), a timestamp (if configured), and all the supplied strings, separated by spaces and terminated by a newline.