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.

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.

XHTML 1.0 válido!