The Jaws_Log core subsystem (X)

Package: Jaws API File: Jaws/Log.php Object: Jaws::$Log

The importance of logging error messages can't be stressed enough. Logging also serves other purposes, like debugging. The logging core subsystem is automatically loaded during initiation. Depending on the run time mode, the logging options are read from the configuration file (with the configuration subsystem) or set to defaults.

Classes

The Jaws_Log core subsystem is made of two classes and one interface.

Jaws_Log

The Jaws_Log class is the class that is instantiated as a singleton and accessed through Jaws::$Log.

Jaws_Log_Msg

A Jaws_Log_Msg class is created for all the log messages created by Jaws_Log. It contains several methods to get information on the log message.

Jaws_Log_Msg_Interface

The Jaws_Log_Msg interface is implemented by all classes that can be passed on the logging queue. The best example is the Jaws_Exception class.

Log message levels

The message level indicates the importance of a message. Here is the list, in increasing importance:

  • Debug message (Jaws_Log_Msg::LVL_DEBUG)
  • Information message (Jaws_Log_Msg::LVL_INFOR)
  • Warning (Jaws_Log_Msg::LVL_WARNG)
  • Error (Jaws_Log_Msg::LVL_ERROR)
  • Fatal error (Jaws_Log_Msg::LVL_FATERR)
  • Core fatal error (Jaws_Log_Msg::LVL_CORE)

The Jaws_Log::setLogLvl() can be used to set the global log message level, which determines if a message is ignored or treated. In exemplis, if a message of level LVL_DEBUG is thrown and the global log level is LVL_ERROR, it will be ignored. The previous method is generally used in the Jaws_Log constructor where the level is set accordingly with the configuration options.

Facilities

Jaws 2 offers different logging facilities which can be used separately or concurrently. Here is the list:

Syslog

Constant: Jaws_Log::LOGFAC_SYSLOG
This facility requires additional configuration:

  • 'priorityAssoc': An array containing associations between syslog priorities and log levels. If an association is not specified, default (JawsLog::LOGFAC_SYSLOG_DEFAULTPRIORITY) applies.

The webserver/PHP error

Constant: Jaws_Log::LOGFAC_WEBSER

A file

Constant: Jaws_Log::LOGFAC_FILE
This facility requires additional configuration:

  • 'filename': The filename where to log

Output print

Constant: Jaws_Log::LOGFAC_PRINT

Configuration

The logging subsystem uses the Jaws::$Cnf->log subsection in the configuration file which is automatically loaded in most cases. Here is a list of configuration options:

Log level

Option: integer Jaws::$Cnf->log->level
This option sets the log level. This can also be set with Jaws_Log::setLvl()

Facilities options

Option: array Jaws::$Cnf->log->options
A numerically-indexed array (one for each log level) of arrays, in the following form:

array(Jaws_Log::LOGMSG_level1 => 
        array('facilities' => Jaws_Log::LOGFAC_fac3 | Jaws_Log::LOGFAC_fac2,
              'foo' => 'bar'),
     )

Where foo is an option specific to the particular facilities used.

Create a log event

To log a message, you have to use the put() method of the Log object.

Jaws::$Log->put($level, $message)

Additionally, if backtrace information is not available, it can be specified explicitly:

Jaws::$Log->put($level, $message, $file, $line);

If the message is of sufficient level, the message will be put into the message queue.

Flush the queue

When exiting, the queue has to be flushed, otherwise no actions will be taken. This is done with the flush() method.

Jaws::$Log->flush()

This is called by the destructor of the Jaws object in most cases.

< Click here to go back to the Core subsystems section