Logging

Logging is the process by which errors, audit and other essential information is written to some form of persistent storage (usually disk based) for subsequent analysis.

  [MANDATORY] Always set the root logging level to WARN  

The default logging level of the root logger is DEBUG, which would cause too much information to be logged for production systems. Additionally, debug and informational messages should only be enabled for those components of interest rather than the whole system.

  [MANDATORY] Always use a suitable level to log messages.  

These levels and the messages appropriate to each level are given in the previous section. Failure to adopt these standards will cause problems when attempting to diagnose and locate the cause of unexpected issues.

  [MANDATORY] Do remember to enable/disable logging for third-party components and libraries  

Many third-party libraries do not require any logging enabled what-so-ever, so it's important to override the root logger's default value (of WARN if you've followed the standards correctly). On the other hand, some third-party components provide useful audit and information messages which may benefit debugging and testing, and should be enabled during those stages of development.

  [MANDATORY] Do prefix logger names with DEBUGGER, AUDITOR or ERROR_RECORDER  

This ensures that log messages can be targeted to difference log files based on the type of messaging being logged as well as the location of the message. This is useful, and often required, for auditing and other information messages.

  [MANDATORY] Use the is...Enabled methods for performance gains  

This is mandatory around the 'happy-path' log messages generated through information, debug and trace messages. It is optional around the warning, error and fatal messages which are expected to always to be logged. See Debug Logging for example usage.

  [MANDATORY] Always include message construction within the is...Enabled clauses  

Similar to above, always ensure that any work associated with the logging of the message is also included in the conditional block. That is, do not create a log message outside of this block if it's never going to be logged.

  [MANDATORY] Ensure message construction and logging has no side-effects  

As logging may be enabled or disabled, always ensure that the code used to create the log messages do not have any side effects that could affect the operation of the code when the logging is disabled. This is especially important when logic to generate the message has been included within an is...Enabled block.

  [MANDATORY] Always provide toString() implementations for all logged objects  

Providing toString is a requirement for all data objects already, as this ensures full debug information can be generated. However, often other objects such as service implementations may also be logged and it's important those those object also include a suitable toString implementation. In the case of service implementations, this should log the service configuration and any mutable, static and private values.

  [MANDATORY] Always use aspects (supplied by the framework) to undertake applications' trace logging  

Aspects keep the code clean of trace logging, and ensure that the intent of program methods are clear.  The only exception is where a complex conditional is encoding within a single method, and the result needs to be traced. However, where possible attempt to include other debug information in these cases and log a debug message. Never undertake your own method tracing at the start and end of methods outside of any supplied apsects.

  [MANDATORY] Remember to initialise the logging framework correctly  

This must be the first sub-system to be initialised within the application.

  [MANDATORY] Log errors (not exceptions) at the point of creation; log exceptions when handled  

There are two possible points at which errors may be logged: at the point of creation or at the point of handling (ie. within the application's error handler). The recommended approach is to log the error detail at the point of creation; only here will sufficient information be available (usually in locale variables) to log meaningful error messages. Generally speaking most exceptions, when thrown, do not contain all the necessary data to log a meaningful error when being logged by the application error handler. Conversely, once an exception has been created and thrown it should never be caught and simply logged. All exceptions should be logged within the application's error handler when the exception itself is handled, together with information that indicates what action is being (or needs to be) undertaken. Under no circumstances should caught exceptions be logged within the application code as part of the catch block, as this simply causes the exception detail to be duplicated. Occasionally, error handling paths within the request's processing (outside the application's error handler) may also need to be logged. This should be achieved by including a dedicated exception logging to log the exception before the exception is handled.

  [Recommended] Use JNDI variables to specify the root log location; suffix application specific paths to the specified root  

For example, within logging.xml use values (attributes) such as ... value="${jndi:SOME_VAR}/group/component/sub-component/debug.log" ... for file name parameters that are supplied to the Log4J appenders.  This ensures that different system can move the log files to appropriate locations using a single JNDI varaible, while keeping the logs for different component separate.

  [Recommended] Do use RollingFileAppender with MaxBackupIndex and MaxBackupSize  

Failure to use these will cause log files are too large to be transferred easily, loaded into the appropriate viewers/readers/editors for analysis, and will result in the analysis of issues being problematic.

  [Recommended] Consider use of the Object Render Configuration to format large and complex objects  

  [Disallowed] Generation of multi-line log messages  

This makes it difficult to find the corresponding elements of the message, and causes different requests to intermix log messages when being logged. It also caused problems for analytical tools which typically read the log file line by line.