log4matlab

Simple logger written with Apache's log4cxx & log4j in mind

__ Outline: __
Almost every large application includes its own logging API. Inserting log statements into code is a low-tech method for debugging it.

Logging is an important component of the development cycle. It offers several advantages: precise context about a run of the application; once inserted into the code, the generation of logging output requires no human intervention; and log output can be saved in persistent medium to be studied at a later time.

[Note] Above text is taken from Apache log4cxx webpage and modified slightly

Log4matlab is designed to be reliable, fast and extensible. Since logging is rarely the main focus of an application, the API strives to be simple to understand and to use. It has been a useful tool for me for logging from multiple classes/functions. Writing log messages to command line is not scalable for large projects with many classes.

__ Features: __
- If the logger is made a singleton for a project then all classes can write their log messages to the same file.
- Supports DEBUG, WARN and ERROR messages.
- Logs to file within milliseconds of message being sent

__ Usage: __

In order to set the file with which to log to

L = log4matlab('logFileName.log');
--

To log a debug message about a class called 'myClassName'

L.mlog = {L.DEBUG,'myClassName','This is a debug message'};
--

To log a warning message about a function called 'SomeFunction'

L.mlog = {L.WARN,'SomeFunction','This is a warning message'};
--

To log an error message about a script called 'ThisIsArbitrary'

L.mlog = {L.ERROR,'ThisIsArbitrary','This is an error message'};
--

To set the logger level for class called 'myClassName' so that only warnings and errors are shown.
Then to send 3 log messages of which only 2 will now be logged

L.SetLoggerLevel('myClassName',L.WARN)
L.mlog = {L.DEBUG,'myClassName','This is a debug message'};
L.mlog = {L.WARN,'myClassName','This is a warning message'};
L.mlog = {L.ERROR,'myClassName','This is an error message'};
--

To set the logger level for function called 'SomeFunction' so that only errors are shown.
Then to send 3 log messages of which only 1 will now be logged

L.SetLoggerLevel('SomeFunction',L.ERROR)
L.mlog = {L.DEBUG,'SomeFunction','This is a debug message'};
L.mlog = {L.WARN,'SomeFunction','This is a warning message'};
L.mlog = {L.ERROR,'SomeFunction','This is an error message'};
--

To get the logger level for myClassName, SomeFunction and ThisIsArbitrary and see they are equal to what we expect

L.GetLoggerLevel('myClassName') == L.WARN
L.GetLoggerLevel('SomeFunction') == L.ERROR
L.GetLoggerLevel('ThisIsArbitrary') == L.DEBUG
--

To allow WARN and ERROR messages be printed to the command window

L.SetCommandWindowLevel(L.WARN)
--

To set back to no message printed to the command window

L.SetCommandWindowLevel(L.NONE)
--

To log a matrix

L.mlog = {L.DEBUG,'myClassName',['The transform is',L.MatrixToString(eye(4))]};
--

To Log an exception (such as generated when trying to access a zeroth (0th) index)

try
a(0);
catch ME
L.mlog = {L.DEBUG,'myClassName',['There was an error',L.ExceptionToString(ME)]};
end
--

To get the name of the current function inside a class (MUST RUN IN THE example in TestClass2.m)

self.L.mlog = {self.L.DEBUG,mfilename('class'),[self.L.Me,'a =',num2str(a)]};

--
For more details see the log4matlab.doxy file.

--
For an example script start with the 'Example.m' script that shows how to use log4matlab as a script and also how to use it in a project containing multiple classes and classes in namespaces.

Try the example classes TestClass1 and TestClass2 as well as NameSpace.TestClass1

file.

__ Additional: __

Although NOT NECESSRY BUT as an additional extra, if you wish to run the unit test cases file log4matlabTestCase.m you need the sourceforge project: mlUnit - Testing Framework for MATLAB (http://sourceforge.net/projects/mlunit/)