9. Logging and Debugging

9.1. Introduction

This chapter is about the logging framework used in CartoWeb, and gives some tips for debugging the application. The two concepts are somewhat related, as logging is often used as a way to ease debugging.

9.2. Logging

Logging is an important feature for being able to see what happens, debug more easily the application, and track invalid or unexpected situations.

The logging framework used for CartoWeb is Log4php. Log4php is a portage to Php of the famous Log4j Java logging library. Thus, Log4php has lots of similarities with Log4j, and users familiar with it will have no problems understanding it.

9.2.1. Log4php Activation

To activate the logging with the default settings, uncomment the line :

    ;log4php.rootLogger=DEBUG, A1

in client_conf/cartoclientLogger.properties

9.2.2. Log4php Configuration Files

Log4php settings are customizable in the client_conf/cartoclientLogger.properties configuration file on the CartoClient and server_conf/cartoserverLogger.properties on the CartoServer.

For the detailed syntax of the configuration file, see the Log4php documentation. A very short introduction is given there. The line "log4php.rootLogger=DEBUG, A1" can be uncommented, which will activate the loggers defined in the lines starting with log4php.appender.NAME, (where NAME is the name in the list "DEBUG, A1"). After the loggers are activated, the the log output will be redirected to the corresponding location. In the line log4php.appender.A1.file="LOG_HOME/cartoclient.log" the LOG_HOME variable has a special meaning: it is expanded to the log directory of the CartoWeb distribution.

One powerful feature of Log4php, among others, is the ability to filter log message according to their severity. Each log message has a severity which may be ALL, DEBUG, INFO, WARN, ERROR, FATAL, OFF. As described in the configuration file comments, the lines like log4php.logger.CLASSNAME can be used to apply a filtering of the log message for the class CLASSNAME. For instance, adding a line "log4php.logger.Cartoclient = INFO", means that only log message of severity INFO or above will be printed. This is useful to avoid displaying unwanted log messages.

9.2.3. Default Log File Location

Default log messages will be written to log/cartoclient.log and the CartoServer ones to log/cartoserver.log. Of course, the Log4php configuration files can be adapted to write messages elsewhere.

9.2.4. Using Log4php in Source Files

The Log4php usage in code is quite easy.

For objects, it is advised to store a Logger object as an instance variable

class MyClass {
    /**
     * @var Logger
     */
    private $log;
    
    [...]
    
    /**
     * Constructor
     */
    public function __construct() {
        $this->log =& LoggerManager::getLogger(__CLASS__);
        [ ... ]
        parent::__construct();
    }

For non object, a reference to a Logger object can be obtained this way:

  $log =& LoggerManager::getLogger(__METHOD__);

Tip

Using __METHOD__ allows the same line to be used independently of the method where it is located.

On the Logger object, several methods can be used to log messages: debug(), info(), warn(), error(), fatal() They take a string as argument, which is the message to log. Example:
```
  $this->log->debug('My Message'); // Inside objects
  $log->warn('My Message');        // Outside objects  
```

9.3. Debugging

Debugging is a large topic. Everyone has its preference over the tool to be used like using an integrated debugging tool inside an IDE, using print statements, code printing and reading, ... Because of this, this section does not tells what tools to use, but rather gives some tips when debugging.

9.3.1. Understanding Exceptions and Stack Traces

When a failure is encountered in CartoWeb the Php5 mechanism for exceptions handling is used to manage exception and display stack traces. People knowing the Java™ language will be familiar with such stack traces. The following example shows such a stack trace display. It is easily understood as the list of functions called, and the line numbers where the call happened.

Failure

class:   SoapFault
message:   Error [8, Undefined property:  ServerMapquery::$currentQeury, 
         /var/www/cartoweb3/coreplugins/mapquery/server/ServerMapquery.php, 222]
Backtrace:

file: 182 - /var/www/cartoweb3/common/Common.php
call: Common::cartowebErrorHandler()

file: 222 - /var/www/cartoweb3/coreplugins/mapquery/server/ServerMapquery.php
call: Common::cartowebErrorHandler()

file: 222 - /var/www/cartoweb3/coreplugins/mapquery/server/ServerMapquery.php
call: ServerMapquery::queryByBbox()

file: 248 - /var/www/cartoweb3/coreplugins/query/server/ServerQuery.php
call: ServerMapquery->queryByBbox(8, "Undefined property:  
     ServerMapquery::$currentQeury", 
     "/var/www/cartoweb3/coreplugins/mapquery/server...", 222, Array(2))

file: 369 - /var/www/cartoweb3/coreplugins/query/server/ServerQuery.php
call: ServerQuery->queryLayer("polygon", Object(Bbox))

file: 58 - /var/www/cartoweb3/server/ServerPluginHelper.php
call: ServerQuery->handlePreDrawing(Object(Bbox), Object(QuerySelection))

file: 96 - /var/www/cartoweb3/server/ServerPluginHelper.php
call: ClientResponderHelper->callHandleFunction(Object(QueryRequest))

9.3.2. Using Direct for More Verbosity

In some situations, a fatal error on the server will display a message with not much verbosity:

Failure

class: SoapFault
message: parse error, unexpected T_VARIABLE

The fact no line number and Php file is displayed is a limitation of the Php SOAP implementation (workarounds are welcomed ;-) ).

In such a situation, a solution for this problem is to enable the CartoWeb direct access mode of operation. Direct access mode is set with the cartoserverDirectAccess parameter of the client_conf/client.ini configuration file. For more details about this parameter, see Section 4.2, “ client.ini ”.