For Developers: Using the debug facility - n4af/TR4W GitHub Wiki

TR4W now has an internal debug facility that uses a module called Log4D. This is patterned after Log4J (if you have any Java experience). The idea is there are debug levels:

• NONE
• FATAL
• ERROR
• WARN
• INFO
• DEBUG
• TRACE

Depending what level its set, that and the higher level is logger. For example, if I have code I want to only show up when TRACE is set, this is the statement: logger.trace('Hello trace');

If I have the debug level set to ERROR, since it is higher, I will not see that when I use the above statement. But, if the trace level is ERROR, when I do this statement, the command is logged: logger.fatal('Halting because log is not available').

Performance

The logger is quite efficient. Each call to logger.debug or whatever level, does a procedure invocation and checks if a variable called IsEnabled. Hence, loger.debug checks if IsDebugEnabled. If you had some particularly complicated code to log a message, it may be better to check for IsDebugEnabled before you do the following pseudo-code:

if logger.IsDebugEnabled then
   begin
   // Read the log and check for valid contents
   while not EOF(...
      begin
      logger.debug('The record hash is ' + Hash(recBuf));
      end;
   end;

the statement logger.debug('The record hash is ' + Hash(recBuf)); illustrated another point:

While I could do that statement, the issue is that even if debug is not the log level, before the call I would still hash the record. Instead of doing this type of calculation all the time, I added a format variant to DEBUG and TRACE where you can pass a format string and an array just like you would use a format statement from SysUtils.

So the above statement is better written: logger.debug('The record hash is %s', [Hash(recBuf)]);

This way, the hash will not be done until it is referenced in the debug function and if we are not at the DEBUG level, we do NOT incur the overhead of the processing (hash in this example).

I recommend you make judicious of these debug statements. Reserve TRACE for things like TCP/IP messages, radio control strings, and other data. TRACE is expected to be voluminous. DEBUG is an intermediate where it can give me the state iff variables I may want to know about, but is not simply to show you the code execution (which is TRACE). No doubt the line between TRACE and DEBUG its fluid and we may have to adjust.

There is also a CTRL-J option to control the DEBUG LOG LEVEL. It is FATAL by default so if you have a reported issue from a user, ask them to set the DEBUG LOG LEVEL to DEBUG or TRACE, and send you the TR4W.LOG created in the program directory.