< Code Documentation

Performance Tests >

## 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.

1. 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.

2. 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` ”.