log4drupal - an updated logging api for drupal 6

drupal 6 included an upgrade to the built in logging functionality (watchdog). drupal 6 exposes a new hook, hook_watchdog which modules may implement to log Drupal events to custom destinations. it also includes two implementations, the dblog module which logs to the watchdog table, and the syslog module which logs to syslog.

with these upgrades, log4drupal is less critical addition to a drupal install, and i hesitated before providing a drupal 6 upgrade. however, eventually i decided that log4drupal is still a useful addition to a drupal development environment as log4drupal provides the following features still not provided by the upgraded drupal 6 watchdog implementation :

• a java-style stacktrace including file and line numbers, showing the path of execution
• automatic recursive printing of all variables passed to the log methods
• ability to change the logging level on the fly

in addition, the drupal 6 version of log4drupal includes the following upgrades from the drupal 5 version

• all messages sent to the watchdog method are also output via log4drupal
• severity levels have been expanded to confirm to RFC 3164
• log module now loaded during the drupal bootstrap phase so that messages may be added within hook_boot implementations.

you may download the drupal 6 version here. see below for general information on what this module is about and how it works.

what is log4drupal?

log4drupal is a simple api that writes messages to a log file. each message is tagged with a particular log priority level (e.g., debug, info, warn, error or emergency) and you may also set the overall log threshold for your system. only messages with a priority level above your system threshold are actually printed to your log file. the system threshold may changed at any time, using the log4drupal administrative interface. you may also specify a level above which a stack trace will be appended to each mesage.

installation

don't forget to read the included README.txt file. before enabling this module you must install the Pear Log package on your server.

module options

the module options are very similar to the drupal 5 version, and are shown below.

examples

log4drupal is best explained by example. suppose you had a module example.module containing the following code:

if your logging level is set to debug and you stacktrace level is set to warn, your log file will contain the following messages. notice that the $account object is automatically rendered recursively.

if your logging level is set to warn and you stacktrace level is set to error, your log file will contain the following messages. notice that the debug message is no longer printed at all, and the warn message no longer includes a stacktrace.

[10:40:06 03/30/09] [warning] [example.module:8] That nasty super-user is creeping around again!!

all watchdog messages will also appear in your log4drupal log file. for example, as long as your logging level is set to notice or below, you will see the following message in your log file each time a user logs in

[11:02:43 03/30/09] [notice] [user.module:1368] Session opened for admin.

suggestions for new features always welcome.