LuaLogging: A simple API to use logging features in Lua

LuaLogging
A simple API to use logging features in Lua.

## Introduction

LuaLogging provides a simple API to use logging features in Lua. Its design was based on log4j. LuaLogging currently supports console, file, email, socket and sql outputs through the use of appenders.

The `logging` module holds a `new` function to create new `logger` objects.

This logger constructor receives a function (known as the appender function) that will be called on each call to log a message.

An appender function receives three arguments:

- self: the logger object
- level: the logging level
- message: the message to be logged

The logger constructor also receives a optional second argument which should be a table with parameters

## Installation

LuaLogging is installed as a regular Lua module called `logging`.

installation is easiest using LuaRocks; "`luarocks install lualogging`", or alternatively using the `Makefile`.

## Logging module

The logging module has a number of global functions:

logging.new( function[, logLevel] )
  Creates a new logger object from a custom 'appender' function. See examples below. The appender function signature is `function(self, level, message)`. The optional logLevel argument specifies the initial log-level to set (the value must be a valid log-level constant). If omitted defaults to `logging.defaultLevel`.
patts = logging.buildLogPatterns([table], [string])
  Creates a log-patterns table. The returned table will for each level have the logPattern set to 1. the value in the table, or alternatively 2. the string value, or 3. the pattern from the global defaults.
  Returns a logPatterns table.
  Example logging source info only on debug-level, and coloring error and fatal messages:

      local patterns = logging.buildLogPatterns(
        {
          [logging.DEBUG] = "%date %level %message (%source)\n"
          [logging.ERROR] = "%date "..ansi_red.."%level %message"..ansi_reset.."\n"
          [logging.FATAL] = "%date "..ansi_red.."%level %message"..ansi_reset.."\n"
        }, "%date %level %message\n"
      )

date_val = logging.date([format,[time]])
  Compatible with standard Lua `os.date()` function, but supports second fractions. The placeholder in the format string is `"%q"`, or `"%1q"` to `"%6q"`, where the number 1-6 specifies the number of decimals. The default is 3, so `"%q"` is the same as `"%3q"`. The format will always have the specified length, padded with leading and trailing 0's where necessary.
  If the pattern is `"*t"`, then the returned table will have an extra field `"secf"` that holds the fractional part.
  Example: `"%y-%m-%d %H:%M:%S.%6q"`
  Note: if the "time" parameter is not provided, it will try and use the LuaSocket function `gettime()` to get the time. If unavailable, the fractional part will be set to 0.
patts = logging.defaultLogPatterns([string | table])
  Sets the default logPatterns (global!) if a parameter is given. If the parameter is a string then that string will be used as the pattern for all log-levels. If a table is given, then it must have all log-levels defined with a pattern string. See also `logging.buildLogPatterns`.
  The default is `"%date %level %message\n"` for all log-levels.
  Available placeholders in the pattern string are; `"%date"`, `"%level"`, `"%message"`, `"%file"`, `"%line"`, `"%function"` and `"%source"`. The `"%source"` placeholder evaluates to `"%file:%line in function'%function'"`.
  Returns the current defaultLogPatterns value.
  NOTE: since this is a global setting, libraries should never set it, only applications should.
patt = logging.defaultTimestampPattern([string])
  Sets the default timestampPattern (global!) if given. The default is `nil`, which results in a system specific date/time format. The pattern should be accepted by the function `logging.date` for formatting.
  Returns the current defaultTimestampPattern value.
  NOTE: since this is a global setting, libraries should never set it, only applications should.
level = logging.defaultLevel([level constant])
  Sets the default log-level (global!) if given. Each new logger object created will start with the log-level as specified by this value. The level parameter must be one of the log-level constants. The default is `logging.DEBUG`.
  Returns the current defaultLevel value.
  NOTE: since this is a global setting, libraries should never set it, only applications should.
logger = logging.defaultLogger([logger object])
  Sets the default logger object (global!) if given. The logger parameter must be a LuaLogging logger object. The default is to generate a new `console` logger (with "destination" set to "stderr") on the first call to get the default logger.
  Returns the current defaultLogger value.
  NOTE: since this is a global setting, libraries should never set it, only applications should. Libraries should get this logger and use it, assuming the application has set it.

      -- Example: application setting the default logger
      local color = require("ansicolors") -- https://github.com/kikito/ansicolors.lua
      local ll = require("logging")
      require "logging.console"
      ll.defaultLogger(ll.console {
        destination = "stderr",
        timestampPattern = "!%y-%m-%dT%H:%M:%S.%qZ", -- ISO 8601 in UTC
        logPatterns = {
          [ll.DEBUG] = color("%{white}%date%{cyan} %level %message (%source)\n"),
          [ll.INFO] = color("%{white}%date%{white} %level %message\n"),
          [ll.WARN] = color("%{white}%date%{yellow} %level %message\n"),
          [ll.ERROR] = color("%{white}%date%{red bright} %level %message %{cyan}(%source)\n"),
          [ll.FATAL] = color("%{white}%date%{magenta bright} %level %message %{cyan}(%source)\n"),
        }
      })

      -- Example: library using default if available (fallback to nop)
      local log do
        local ll = package.loaded.logging
        if ll and type(ll) == "table" and ll.defaultLogger and
          tostring(ll._VERSION):find("LuaLogging") then
          -- default LuaLogging logger is available
          log = ll.defaultLogger()
        else
          -- just use a stub logger with only no-op functions
          local nop = function() end
          log = setmetatable({}, {
            __index = function(self, key) self[key] = nop return nop end
          })
        end
      end

      log:debug("starting my library")

## Environment variables

The submodule `logging.envconfig` allows to configure the default logger via environment variables. This is done based on a "prefix" for the environment variables (with default value "LL"). The variables are the logger options names with the prefix in all-caps separated by "_". So if a logger takes an option "`opts.logLevel`", then it can be configured using environment variable `LL_LOGLEVEL=warn`.

The type of logger can be set using environment variable `LL_LOGGER=console` (assuming the default prefix "LL").

The defaults are "LL" for the prefix, and a console logger to "stderr".

The exposed functions:

envconfig.set_default_settings(prefix)
  Sets the default prefix and loads the configuration. Returns `true` on success, `nil, "already set a default"` if it was called before. Will throw an error if something during the configuration fails (bad user input in environment variables for example).
  This method should be called by applications at startup, to set the default prefix.
name, opts = envconfig.get_default_settings()
  returns the appender name (eg. "file", "console", etc), and the options table for configuring the appender. The table has a metatable that will dynamically lookup fields in environment variables, this ensures that any option an appender checks will be read and returned. Boolean and number values will be converted to their respective types (case insensitive).
  The common `logPatterns` field is a special case where each level can be configured by appending the level with an "_". See example below:

      # set these environment variables
      export MYAPP_LOGGER="console"
      export MYAPP_LOGLEVEL="info"
      export MYAPP_LOGPATTERN = "%message"
      export MYAPP_LOGPATTERNS_DEBUG = "%message %source"
      export MYAPP_LOGPATTERNS_FATAL = "Oh my!! %message"

      -- Lua code (see set_default_logger for a shorter version)
      local logging = require "logging"
      local logenv = require "logging.envconfig"
      assert(logenv.set_default_settings("MYAPP"))
      local logger_name, logger_opts = logenv.get_default_settings()
      local logger = assert(require("logging."..logger_name)(logger_opts))
      logging.setdefaultLogger(logger)

      logger:info("configured via environment!")

logger = envconfig.set_default_logger(prefix)
  Sets (and returns) the default logger from the environment.

      # set these environment variables
      export MYAPP_LOGGER="console"
      export MYAPP_LOGLEVEL="info"
      export MYAPP_LOGPATTERN = "%message"
      export MYAPP_LOGPATTERNS_DEBUG = "%message %source"
      export MYAPP_LOGPATTERNS_FATAL = "Oh my!! %message"

      -- Lua code
      local logenv = require "logging.envconfig"
      local logger = assert(logenv.set_default_logger("MYAPP"))

      logger:info("configured via environment!")

## Logger objects

Logger objects are created by loading the 'appender' module, and calling on it. For example:

      local logger = require("logging.console") {
        -- options go here (see appenders for options)
      }

A logger object offers the following methods that write log messages.

For each of the methods below, the parameter `message` may be any lua value, not only strings. When necessary `message` is converted to a string.

The parameter `level` can be one of the variables enumerated below. The values are presented in descending criticality, so if the minimum level is defined as `logger.WARN` then `logger.INFO` and `logger.DEBUG` level messages are not logged. The default set level at startup is `logger.DEBUG`.

### Constants

logger.DEBUG
  The DEBUG level designates fine-grained informational events that are most useful to debug an application.
logger.INFO
  The INFO level designates informational messages that highlight the progress of the application at coarse-grained level.
logger.WARN
  The WARN level designates potentially harmful situations.
logger.ERROR
  The ERROR level designates error events that might still allow the application to continue running.
logger.FATAL
  The FATAL level designates very severe error events that would presumably lead the application to abort.
logger.OFF
  The OFF level will stop all log messages.

### Methods

logger:log (level, [message]|[table]|[format, ...]|[function, ...])
  Logs a message with the specified level.
logger:setLevel (level)
  This method sets a minimum level for messages to be logged.
logger:getPrint (level)
  This method returns a print-like function that redirects all output to the logger instead of the console. The `level` parameter specifies the log-level of the output.

The following set of methods is dynamically generated from the log-levels.

logger:debug ([message]|[table]|[format, ...]|[function, ...])
  Logs a message with DEBUG level.
logger:info ([message]|[table]|[format, ...]|[function, ...])
  Logs a message with INFO level.
logger:warn ([message]|[table]|[format, ...]|[function, ...])
  Logs a message with WARN level.
logger:error ([message]|[table]|[format, ...]|[function, ...])
  Logs a message with ERROR level.
logger:fatal ([message]|[table]|[format, ...]|[function, ...])
  Logs a message with FATAL level.

## Examples

The example below creates a logger that prints the level and message to the standard output (or whatever the print function does).

    local Logging = require "logging"

    local appender = function(self, level, message)
      print(level, message)
      return true
    end

    local logger = Logging.new(appender)

    logger:setLevel(logger.WARN)
    logger:log(logger.INFO, "sending email")

    logger:info("trying to contact server")
    logger:warn("server did not respond yet")
    logger:error("server unreachable")

    -- dump a table in a log message
    local tab = { a = 1, b = 2 }
    logger:debug(tab)

    -- use string.format() style formatting
    logger:info("val1='%s', val2=%d", "string value", 1234)

    -- complex log formatting.
    local function log_callback(val1, val2)
      -- Do some complex pre-processing of parameters, maybe dump a table to a string.
      return string.format("val1='%s', val2=%d", val1, val2)
    end

    -- function 'log_callback' will only be called if the current log level is "DEBUG"
    logger:debug(log_callback, "string value", 1234)

    -- create a print that redirects to the logger at level "INFO"
    logger:setLevel (logger.INFO)
    local print = logger:getPrint(logger.INFO)
    print "hello\nthere!"

Upon execution of the above example the following lines will show in the standard output. Notice that some of the INFO log requests are not handled because the minimum level is set to WARN.

    WARN server did not responded yet
    ERROR server unreachable
    INFO hello
    INFO there!

## Appenders

The following appenders are included in the standard distribution.

- Console
- File
- Rolling File
- SQL
- Socket
- Rsyslog
- Email
- Nginx/OpenResty

## Upgrading from 1.0.0

Upgrading from LuaLogging 1.0.0 is very easy. The `logger` object is fully compatible. You just need to change the code that creates the object.

The `logger` constructor from 1.0.0 received a single argument which was a filename. To upgrade to 1.1.0 you should create a `logging.file` object instead, passing the filename as argument. As simple as this.