LuaLogging: A simple API to use logging features in Lua

LuaLogging
A simple API to use logging features in Lua. Portuguese version.

## 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.

LuaLogging defines one single global variable, a table called `logging` which holds a 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

## Installation

LuaLogging follows the package model for Lua 5.1, therefore it should be "installed" in you `package.path`

## Logger objects

A logger object offers the following methods that writes 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 `logging.WARN` then `logging.INFO` and `logging.DEBUG` levels messages are not logged.

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

### Methods

logger:log (level, [message]|[table]|[format, ...]|[function, ...])
  Logs a message with the specified level.
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.
logger:setLevel (level)
  This method sets a minimum level for messages to be logged.

## Examples

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

    require "logging"

    local logger = logging.new(function(self, level, message)
                                 print(level, message)
                                 return true
                               end)

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

    logger:info("trying to contact server")
    logger:warn("server did not responded 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)

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

    WARN server did not responded yet
    ERROR server unreachable

## Appenders

The following appenders are included in the standard distribution.

- Console
- File
- Rolling File
- SQL
- Socket
- Email

## 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.