A simple API to use logging features in Lua.

LuaLogging

• Home
• Manual
  • Installation
  • Logger objects
  • Examples
• Appenders
  • Console
  • File
  • Rolling File
  • SQL
  • Socket
  • Rsyslog
  • Email
  • Nginx
• Project
• License

Overview

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

LuaLogging is free software and uses the same license as Lua 5.1.

Status

Current version is 1.8.2. It was developed for Lua 5.1+.

Download

LuaLogging can be downloaded from its GitHub downloads page or installed via LuaRocks.

Dependencies

LuaLogging dependencies can be separated by the used appenders:

LuaLogging Core, Console and File appenders

• Lua 5.1+

Socket, Rsyslog, and Email appenders

• LuaSocket

SQL appender

• LuaSQL 2.1.x

History

1.8.2 [27/Jan/2023]

Fix: allow to work without the debug library.

1.8.1 [23/Jan/2023]

Fix: use explicit tostring, don't rely on automatic coercion.

Fix: rsyslog appender wouldn't properly clear the socket upon an error.

1.8.0 [22/Oct/2022]

Added: new module logging.envconfig to allow log configuration via environment variables.

Refactor: refactored the appenders to be more object like. They now return a module table.

Fix: add rsyslog appender to makefile install target.

Fix: errorhandler in rsyslog was omitting 'self', and also log the failed message itself to stderr.

Fix: when using Copas and rsyslog on Lua 5.1, coxpcall is required to yield.

Fix: rsyslog; upon failure remove the closed socket from the cache to prevent the retry from using the closed socket.

1.7.0 [21/Sep/2022]

Added: new function logging.date is compatible with os.date but supports second-fractions, to be represented by %q placeholder in the timestampPattern.

Added: new bundled appender; "rsyslog". This logger will log in syslog format to a remote syslog server. It supports both BSD as well as IETF formats, and supports sending over UDP and TCP, with an option to use Copas for async-sending over TCP.

1.6.0 [09/Nov/2021]

Added: the logPattern can now be specified for each log-level individually. This allows use cases like only adding "%source" on debug level, or injecting ansi-color coding in for example the error log-level.

Added: new bundled appender; "nginx". This logger has no configuration options, but will simply pass any log messages on to the nginx log. When using LuaLogging in OpenResty, configure this logger.

Added: application level defaults. New functions logging.defaultLogPatterns() , logging.defaultTimestampPattern(), logging.defaultLevel(), and logging.defaultLogger() can be used to get/set the global application level defaults.
Use carefully, this is global state, so only applications should set those, libraries should not.

Added: the included appenders now have an extra parameter to set log-level upon creation; logLevel.

Added: the logPattern can now have new placeholders:
"%file" (source file),
"%line" (source line),
"%function" (function name), and
"%source" (evaluates to "%file:%line in function '%function'").

Added: the console logger has a new optional parameter "destination", which must be either "stderr" or "stdout" (defaults to "stdout")

1.5.2 [12/Aug/2021]

Fix: rolling-file, 'seek' can occasionally fail, handle it properly.

1.5.1 [22/Mar/2021]

Reverted: Functionality to specify custom log levels.

1.5.0 [22/Mar/2021]

Added: Functionality to specify custom log levels.

Added: Provide verbose error message when formatting fails.

Fix: disable buffering on windows files

1.4.0 [12/Aug/2020]

Fix: No more global on Lua 5.3.

Fix: Reduced log noise when changing log levels.

Added: A new log-level "off" to suspend logging.

Fix: Restored the log-level constants on the logger object.

Fix: catch exceptions when formatting log messages.

Change: creating loggers now always takes a parameters table (consistent across all appenders). The old parameters are now deprecated, but still work for backward compatibility purposes.

Added: All appenders have a new property timestampPattern to specify the format of the timestamp in the log message

Added: logger:getPrint() function that returns a print-like function, but directs all output to the logger.

1.3.0 [5/Mar/2013]

1.2.0 [20/Apr/2011]

Improved performance of logging.

Added Rolling File Appender.

1.1.4 [30/Oct/2007]

Fixed bug #1719 - inefficient handling of file loggers (Patch by Jürgen Hötzel).

1.1.3 [08/Aug/2007]

New makefile for Windows (using nmake) and configure script for Unix.

1.1.2 [14/Aug/2006]

Fixed a bug found by Carlos Augusto where tostring() was being incorrectly used with numbers.

1.1.1 [31/Mar/2006]

1.1.0 [12/Nov/2004]

1.0.0 [02/Jul/2004]

Credits

LuaLogging 1.2 and 1.3 were maintained by Robert G. Jakabosky.

LuaLogging 1.1.x was designed by Danilo Tuler and Thiago Ponte and implemented by Thiago Ponte.

LuaLogging 1.0.0 was designed by Danilo Tuler (and log4j) and implemented by Danilo Tuler and André Carregal.