LUA - Projects

What is Log4LUA?

Log4LUA is a logging framework in the style of Log4J. It is simple and pretty much straightforward though.

Log4LUA Version 0.2b - 2008-09-23

Please upgrade to the latest version.
Download the current release. View generated luadoc.
Report errors or feature requests here (JIRA).

See this blog post for an introduction and a discussion of the differences to other logging frameworks such as LuaLogging.

Features

  • External configuration: Configure your logging system via a config file.
  • Logger categories: Configure different categories for different logging tasks.
  • Detailed information available: source file, line, function or the whole stack trace
  • Different appenders: console, file and smtp (email)
  • Multiple appenders per category: Log to a file and get the worst errors by email
  • Level threshold for smtp appender: Don't get every log message by mail only the ones above a defined level.
  • Log file rotations for file appender: Based on a date pattern
  • Test if a certain log level is enabled: Even if DEBUG is turned off it might have a performance impact since the debug string has to build up etc.

Installation

Download and unpack to a directory of your choice. Make sure that InstallDirectory/src/?.lua is in your LUA_PATH.

Configuration

Write your configuration just like this:

log4lua.conf.lua
local logger = require("optivo.common.log4lua.logger")
local console = require("optivo.common.log4lua.appenders.console")
local file = require("optivo.common.log4lua.appenders.file")
local smtp = require("optivo.common.log4lua.appenders.smtp")

local config = {}

-- Create a default smtp appender sending message of level WARN or higher.
local defaultSmtp = smtp.new(
    {
        headers = {
            from = "myserver@mydomain.com",
            to = "admin@mydomain.com",
            subject = "%LEVEL: %MESSAGE"
        },
        body = "Hi, an error occurred at %FILE:%LINE.\n\nLevel: %LEVEL\nMessage: %MESSAGE\n"
    },
    "mail.mydomain.com",
   logger.WARN
)

-- ROOT category must be configured.
-- For the root category we use console and smtp appender
config["ROOT"] = logger.Logger.new({console.new(), defaultSmtp}, "ROOT", logger.INFO)

-- Category "core" uses rotating file appender and the default message pattern
config["core"] = logger.Logger.new(file.new("core-%s.log", "%Y-%m-%d"), "core", logger.INFO)

-- The config table must be returned.
return config

More detailed information is available in the configuration reference.

Usage

myapp.lua
local logger = require("optivo.common.log4lua.logger")

-- I would prefer calling the main logger LOG.
-- This will return a logger for category "ROOT" since there is no category "mycode".
local LOG = logger.getLogger("mycode")

-- This will return a logger of the category "core" since the category name 
-- "core.moduleA" starts with "core"
local LOG_CORE = logger.getLogger("core.moduleA")

-- Log something
LOG:info("My first log message")

-- Tables are converted to string for you.
LOG:warn({name = "Paul", age = "22"})

-- Log to different category.
LOG_CORE:fatal("System error")

-- Test if a level is enabled.
if (LOG:isLevel(LOG.DEBUG)) then
    LOG:debug("Only execute this statement if DEBUG is really enabled.")
end

-- Load a configuration by hand (you shouldn't have to do this).
logger.loadConfig("myOtherConfig.lua")

Running

The environment variable LOG4LUA_CONFIG_FILE contains the path to the logging configuration to be used.

Run with specified logging configuration
LOG4LUA_CONFIG_FILE = "log4lua.conf.lua" lua myapp.lua

Changes

Version 0.2 2008-09-05

  • All constructor methods are changed from "create" to "new". This seems to be a bit more "LUA coding convention like".
  • The Logger class is now return by the module. So it is
    local logger = require("optivo.common.log4lua.logger")
    local LOG = logger.new(...)

    instead of

    local logger = require("optivo.common.log4lua.logger")
    local LOG = logger.Logger.create(...)
  • Logger:isLevel(level) added. So you can ask whether a given level is enabled. Useful if you use quite heavy debug messages.
  • Code quality improvements due to using lualint and luacov.

Version 0.1 2008-09-02

  • Initial release