Logging

PRADO provides a highly flexible and extensible logging functionality. Messages logged can be classified according to log levels, message categories and originating control. Using level, category, control or timestamp filters, the messages can be further routed to different destinations, such as files, emails, browser windows, etc. The following diagram shows the basic architecture of PRADO logging mechanism,

Log router

Using Logging Functions

The following two methods are provided for logging messages in PRADO, 

Prado::log($message, $logLevel, $category, $control);
Prado::trace($message, $category, $control);

The difference between Prado::log() and Prado::trace() is that the latter automatically selects the log level according to the application mode. If the application is in Debug mode, stack trace information is appended to the messages. Prado::trace() is widely used in the core code of the PRADO framework.

Message Routing

Messages logged using the above two functions are kept in memory. To make use of the messages, developers need to route them to specific destinations, such as files, emails, or browser windows. The message routing is managed by System.Util.TLogRouter module. When plugged into an application, it can route the messages to different destination in parallel. Currently, PRADO provides four types of routes:

  • TFileLogRoute - filtered messages are stored in a specified log file. By default, this file is named prado.log under the runtime directory of the application. File rotation is provided.
  • TEmailLogRoute - filtered messages are sent to pre-specified email addresses.
  • TBrowserLogRoute - filtered messages are appended to the end of the current page output.
  • TFirebugLogRoute - filtered messages are sent to the Firebug console

To enable message routing, plug in and configure the TLogRouter module in application configuration, 

<module id="log" class="System.Util.TLogRouter">
  <route class="TBrowserLogRoute"
      Levels="Info"
      Categories="System.Web.UI.TPage, System.Web.UI.WebControls" />
  <route class="TFileLogRoute"
      Levels="Warning, Error"
      Categories="System.Web" />
</module>

In the above, the Levels and Categories specify the log and category filters to selectively retrieve the messages to the corresponding destinations.

Message Filtering

Messages can be filtered according to their log levels and categories. Each log message is associated with a log level and a category. With levels and categories, developers can selectively retrieve messages that they are interested on.

Log levels defined in System.Util.TLogger include : DEBUG, INFO, NOTICE, WARNING, ERROR, ALERT, FATAL. Messages can be filtered according log level criteria. For example, if a filter specifies WARNING and ERROR levels, then only those messages that are of WARNING and ERROR will be returned.

Message categories are hierarchical. A category whose name is the prefix of another is said to be the ancestor category of the other category. For example, System.Web category is the ancestor of System.Web.UI and System.Web.UI.WebControls categories. Messages can be selectively retrieved using such hierarchical category filters. For example, if the category filter is System.Web, then all messages in the System.Web are returned. In addition, messages in the child categories, such as System.Web.UI.WebControls, are also returned.

By convention, the messages logged in the core code of PRADO are categorized according to the namespace of the corresponding classes. For example, messages logged in TPage will be of category System.Web.UI.TPage.