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