Logging use case

This is a description of a possible usage of the logging subsystem. See also the article on  a basic logging configuration, as the use case is in line with that approach.

Logging from the SXML layer is possible using a viper, for example

Smartsite SXML	Copy Code
{logging.addinformation("Informational message", MyCategory, 2)}

This produces a log entry of log type information, with a log text Informational message, using log category MyCategory, and using log level 2.

Purpose and audience

The system should not just produce log entries for the sake of logging. Instead keep the purpose of the logging in mind, and keep the audience for the logging information in mind.

• A first audience is the CMS developer or the web consultant, site developer for short. During site building it is useful to have logging for debugging purposes. The phase is probably development and test.
• A second audience is the system administrator. Several system administrator roles can be distinguished; however here only one is used. The purpose of the logging is to inform the system administrator about the regular functioning of the system, and to signal exceptional behaviour of the system. The phase is production.
• A third audience is the first-line or second-line support. In case of some system problem the logging information can be used for "post mortem" analysis. The purpose is to help finding system flaws in order to take corrective measures. The phase is production.

Listeners

The system configuration described here makes use of the following listeners:

• An XML file listener, resulting in log files in folder ..\Sites\<your site>\logfiles\Cms. All logging goes to this listener, providing the highest level of detail.
• A database listener, resulting in log information in four tables in the CMS database, of which table LogEntries is the main table. The configuration is such that all logging to the database also goes to the XML file listener.
• A mail listener, resulting in mails to the system administrator. All mailed logging also goes to the database listener and also goes to the XML file listener. This is also the difference with other mails sent by the system: those mails are not logged as integral part of logging.

A fourth listeners must be mentioned here for completeness: the logging subsystem itself may fail. In that case the related errors go to the operating system event log and can be examined using the event viewer.

Audience per listener

The audience for the three listeners is summarized below.

Retainability

The use case assumes the following retainability per listener.

• XML file listener: the logging subsystem includes a mechanism to limit the volume of logging, for example by limiting the amount of disk space used. When reaching this limit files are automatically deleted or reused. Also the system administrator may decide to delete the files manually. All of this is fine; the detailed logging information is not intended to be preserved forever.
• Database listener: the log entries are preserved and no automatic cleanup mechanism is in place. This is as intended. The log entries can be used for reporting, statistics, audit trail, and more. Deleting log entries could affect any of these functions.
• Mail listener: the mails themselves are gone once sent; the mails are however also logged to the database listener and are hence preserved.

Log categories

The use case introduces three log categories per module, per subsystem, per system function or other software unit that deserves logging. The log category names are suffixed as follows:

• _LOG: for detailed logging, to the XML file listener.
• _RECORD: in order to record logentries, using the database listener.
• _NOTIFY: if the system administrator must be notified by means of a mail, through the mail listener.

These suffixes allow for distinct configuration in file Smartsite.logging.config, and for example allow to log RECORD entries to LOG as well, and to log NOTIFY entries to RECORD and LOG as well.

Given a module X and a subsystem Y this results in the following log categories:

• MODULEX_LOG
• MODULEX_RECORD
• MODULEX_NOTIFY
• SUBSYSTEMY_LOG
• SUBSYSTEMY_RECORD
• SUBSYSTEMY_NOTIFY

Responsability of the site developer

During site development viper calls are added in order to produce logging. The site developer should continuously consider the purpose of the logging and the intended audience, and decide whether to use LOG, RECORD or NOTIFY.

• Does an error occur that requires corrective action by the system administrator, for example some recurring synchronisation process fails? This is incident management. Use NOTIFY.
• Must the system administrator be informed about some major event, for example a successful nightly synchronisation, as part of regular maintenance procedures? Use NOTIFY.
• Must the system administrator be able to lookup results, assuming that no notification means that there are no system issues? Use RECORD.
• Is it desirable to log various events in order to understand or debug the system behaviour, without targeting the system administrator as audience? Use LOG.

Log type

When logging it is required to specify the log type. Although there are six log types the use case limits itself to three log types only.

• Information, using viper {logging.addinformation(...)}, for informational messages. These messages imply successful completion of an operation.
• Warning, using viper {logging.addwarning(...)}, for warnings. Some operation was still successfully completed; however perhaps there are reasons for further investigation.
• Error, using viper {logging.adderror(...)}, for errors. These messages imply failure and usually require corrective action.

The ignored log types include Verbose, for a level of detail before Information, and Critical, for a fatal error level after Error.

The log types Information, Warning and Error are combined at wish with LOG, RECORD and NOTIFY. There are no prescriptions which combinations to use, although Information will tend to be combined with LOG and Error will tend to be combined with RECORD or NOTIFY.

Log level

When logging it is required to specify the log level. The level ranges from 1 to 10. Technically other levels are possible; the range 1 to 10 is by convention.

• 1 is for the most important events, where the messages are summaries.
• 10 is for the least important events, where the messages are detailed.

Responsability of the site developer

In order to pick a meaningful log level the site developer must consider the filtering (blocking) that takes place. The filtering is configured in Smartite.logging.config. Technically the filtering is done by specifying a log level threshold for the combination of log category and log type. The use case considers a log level threshold for the log type only, and attempts to apply the same filtering for all log categories. For new modules this is possible. For existing modules it is sometimes required to add slight adjustments in order to compensate for the level of logging by the module.

• √ log entry passes through
• × log entry is blocked

These are the default settings for production. The site developer must therefore consider:

• If some informational message should be logged in the production environment then use a log level 1 if the message is of the highest importance, and use a log level 2 if the messages is somewhat less important but still important. Do not use levels 3 to 10, knowing that these log entries will normally be filtered in the production environment.
• For informational messages to be logged in the development and test environment use log levels 3 to 10. The threshold level in the configuration file will be raised or lowered depending on the debugging needs. This allows to tune the verbosity level, towards 3 for less log entries and towards 10 for many details.
• Likewise consider the appropriate log level for warnings, knowing that the default threshold level for production is 5: 5 passes through, 6 is blocked.
• Errors are by default not filtered; all errors are considered sufficiently important to be logged in the production environement.

System reports

A final practical use of the database listener is to produce system status reports or system health reports given the log entries stored in the four logging tables. A system manager can inspect the log entries, using the Manager action available for this purpose. There may however be many log entries, obfuscating the one success entry or failure entry of interest. Given some conventions it is possible to query the log information, for example looking for entries with category MODULEX_RECORD, allowing to report whether the latest synchronization of module X was successful or whether it failed. This is approach will be subject for a distinct article on logging.

---