Routing and filtering of log information
The iXperion logging subsystem is configured in Smartsite.logging.config. The underlying Logging Application Block of the Microsoft Enterprise Library allows for a detailed configuration, not always required in all cases. The steps below focus on a basic configuration, accepting default behaviour and simplifying configuration where possible.
Logging for example starts with the following viper.
| Smartsite SXML |
Copy Code
|
|---|---|
{logging.addinformation("Informational message", MyCategory, 2)}
|
|
This viper specifies the log type information, the log message Informational message, the log category MyCategory and the log level 2.
Log type
The set of log types is a closed set: you cannot add log types. The logtypes are, ordered from most important to least important:
- Critical: for severe errors, for which recovery is hard
- Error: for recoverable errors
- Warning: for issues that could require further investigation
- Information: for informational messages, implying success
- Verbose: for many and detailed messages, useful for debugging
A sixth type Trace is omitted from the list. Activity trace or trace for short is intended to correlate the behaviour of cooperating systems. Critical could be omitted as well, using Error instead. Verbose could be omitted as well, using Information instead, tuning the amount of log information using the log level. As a result the following log types are a useful minimum set:
- Error, viper logging.adderror
- Warning, viper logging.addwarning
- Information, viper logging.addinformation
Log message
The log message is a free text, up to the application.
Log category
The set of log categories is an open set: you can add category names. Using a new category name is usually not sufficient to obtain logging; configuration in Smartsite.logging.config is normally also required. A subsystem or a module typically introduces one or a few categories.
The underlying logging system is prepared for logging of an event to multiple categories. It is a simplification to log to one category only, and the vipers for logging indeed support to to log to one category at the time.
Log level
The log level is by convention a value in the range 1 to 10, where
- 1 is used for messages that are most important and that are the first to be logged if the logging threshold is raised above 0,
- to 10 for detailed messages that are the first not to be logged when the log threshold level is lowered.
Listeners
Log messages are routed to listeners, and log messages are filtered.
- A listener is a destination for log messages, for example table LogEntries in the database, log files on disk, and also a mail listener exists.
- Routing connects categories to listeners: the log messages of a particular category are routed to one or more listeners.
- Filtering is applying a threshold log level, for example allowing to specify that the messages for a particular category are only logged if the message log level is 1 or 2.
If the invocation of the logging viper does not result in actual logging check the configuration. The message is only logged if the used log category is connected to a listener, and the log message is not filtered given its log level.
The following listeners are typically configured.
- A database listener. This listener writes log messages to database table LogEntries. It is possible to view the logging by means of a Manager action. The audience is for example a CMS system administrator. The purpose is for example regular system management.
- An XML file listener. This listener writes log messages to files on disk, for example in server folder D:\Sites\<your site>\logfiles\Cms. The files are less friendly to access and require downloading for analysis or require access to the server. The audience is the system administrator, a web consultant, or a CMS developer. The purpose can be incident-related system management, or debugging.
- An email listener. This listener causes mails to be sent upon log messages that are routed to this listener and that are not filtered. The audience can be the CMS system administrator or possibly a service desk. The purpose is to initiate prompt action or to proactively inform about system sanity.
| XML |
Copy Code
|
|---|---|
<listeners>
<add name="Database Trace Listener" ... />
<add name="XmlFile Trace Listener" ... />
<add name="Email Trace Listener" ... />
</listeners>
|
|
Several other listeners exist: to log to the system event log, or to log using Smartsite events, to log to flat files rather than XML files.
Routing categories to listeners
Categories must be routed to listeners. A few catch-all mechanisms exist. Unless such a mechanism is used it is for example required to route category MyCategory to the database listerer, if this is the desired behaviour.
| XML |
Copy Code
|
|---|---|
<categorySources> <add name="MyCategory" ... > <listeners> <add name="Database Trace Listener"/> </listeners> </add> </categorySources> |
|
When examining the configuration file you may notice that categories include an attribute switchValue="All". This allows for additional filtering, for example "Off" to disable, or a log type threshold "Error". The proposed configuration file only uses "All" and in order to keep the configuration as simple as possible it is recommended to keep the value "All".
Filtering
Once a log message is routed to a listener it may still be filtered (blocked) given a log level threshold. This is a threshold for the combination of log type and log category.
| XML |
Copy Code
|
|---|---|
<logtype name="Information" ... > <filters> <filter category="MyCategory" minlevel="1" maxlevel="2"/> ... </filters> </logtype> |
|
Informational messages of MyCategory with a log level 1 or 2 are logged; messages with a log level 3 or more are blocked.
Although the filtering is configured for the combination of log type and log category a simplification is possible by considering the log type only, and for example assume that generally a log type Information leads to levels 1 and 2 that pass through and levels 3 and higher that are blocked. This is then considered independent from the log category, and only a few categories need tuning in the configuration.
Also consider the overall setting, just before the log filters: enable logging to have logging information at all, then route and filter at wish.
| XML |
Copy Code
|
|---|---|
<logwriterConfiguration> <logging enabled="true" ... /> <logfilter> |
|
Log type as log category
So far this is the basic configuration. A few special constructs are useful in practice.
The configuration supports to treat a log type as a log category. If a log type such as Error is prefixed with LogType it becomes a category LogTypeError. This trick allows to configure the handling of errors. It is for example possible to route errors to the database listener, without having to specify the category, and hence allowing to capture errors without having to anticipate the log categories.
| XML |
Copy Code
|
|---|---|
<add name="LogTypeError" ... > <listeners> <add name="Database Trace Listener"/> </listeners> </add> |
|
This is completed by configuring the filters with a default minimum and maximum log level.
| XML |
Copy Code
|
|---|---|
<logtype name="Error" defaultminlevel="1" defaultmaxlevel="10"> <filters> ... </filters> </logtype> |
|
The defaults allow for errors with log level 1 to 10, effectively allowing for all log levels. The filters may contain particular categories, however there is no need to specify category LogTypeError.
Routing of all events
A second special construct is the specification of routing for all events. It is for example possible to route all events to the XML file listener. You may wish to log a limited set of messages to the database, and an even further limited set of messages to the mail listener, but dump all detail to the file listener, knowing that there is a roll-over mechanism to cleanup log files as their volume grow.
| XML |
Copy Code
|
|---|---|
<allEvents name="All Events" ... > <listeners> <add name="XmlFile Trace Listener"/> </listeners> </allEvents> |
|
The filtering still applies. Given the log type and log category a log level threshold applies, either by means of an explicit configuration or by means of the default minimum and maximum threshold levels. Hence an informational message of MyCategory and with log level 2 is logged as part of all events; such a message of log level 3 is not logged as part of all events.
Other special constructs include the category Logging Errors which is connected to the system event log and which is used when the logging subsystem itself fails, and the category Unprocessed Category which is not relevant if all events are already logged.
---