10. Performance Tests

10.1. Main Parameters

This is a non-exhaustive list of interesting parameters for CartoWeb performance tests. You may want to vary these parameters values when testing performance before and after development of new functionalities.

Cartoweb configuration
- Local SOAP, distant SOAP or direct mode
- Data on PC or through NFS
- Map size
- Number of active layers
- Dynamic legends or not
Logs and cache
- MapInfo cached or not
- MapResult cached or not
- SOAP XML cached or not
- Logs activated or not
Map data
- Number of layers (10, 50, 250)

10.2. Executing Tests

This section describes performance tests execution using APD, a debugging/profiling tool available as a Zend PHP module.

10.2.1. APD Module Installation

First thing to do is to install APD's PHP Zend module. You can download archive here.

Follow instructions to compile APD. Then load the module by adding the following two lines in php.ini:

zend_extension = <php_home>/lib/php/extensions/no-debug-non-zts-20040412/apd.so 
apd.dumpdir = /tmp/apd

On a win32 installation:

zend_extension_debug_ts = <php_lib_home>\apd.dll
apd.dumpdir = c:\apd\traces

Path to apd.so may vary. See also README file in APD archive.

You may now activate tracing by adding an empty file trace.apd in directories <cartoweb_home>/client and <cartoweb_home>/server:

touch trace.apd

When using Cartoweb in direct mode, only one trace file will be generated. When using Cartoweb in SOAP mode, two trace files will be generated, one for client and one for server. These files can be found in directory set in apd.dumpdir variable (php.ini, see above).

10.2.2. Simple Execution Times

To get global execution times, use script cwprof.php:

First usage: execute script on each trace file. This could be useful to re-parse an old trace file. If you have separated trace files for client and server, you will need to execute the script twice.
```
cd <cartoweb_home>/scripts
php cwprof.php <trace_file>
```
Second usage: execute script on a directory. The script will parse the most recent trace file. The -local option is used when client and server trace files are located in same directory. In this case, the two most recent trace files are parsed and results for client and server are merged.
```
cd <cartoweb_home>/scripts 
php cwprof.php [-local] <trace_directory>
```

Script output will look like this (times in milliseconds):

Exec client       = 451
Exec server total = 707
Exec MS obj       = 472
Exec MS other     = 85
Exec total        = 1524

Exec client: time elapsed on client. Will be empty if script is executed on a server-only trace file
Exec server total: time elapsed on server. It includes Exec MS obj and Exec MS other times. Will be empty if script is executed on a client-only trace file, or if direct mode is on
Exec MS obj: time elapsed while creating Mapserver main object. It includes reading the mapfile. Will be empty is script is executed on a client-only trace file
Exec MS other: time elapsed in other Mapserver tasks. Will be empty is script is executed on a client-only trace file
Exec total: time elapsed in total. If direct mode is off, it also includes time elapsed in SOAP data transmission

10.2.3. Graphical Interface (Unix-like)

To have more information about execution times and calls stack, you can use a powerful graphical viewer called KCachegrind. This tool is available on Unix-like environments only. On Win32, it can be used via KDE on CygWin.

KCachegrind is included in KDE (package kdesdk). To install it on a Debian distribution, type:

apt-get install kcachegrind

APD package includes a script called pprof2calltree that can translate a trace generated by APD to a file in KCachegrind format. To translate a pprof file, type:

./pprof2calltree -f <pprof_file> >/dev/null

Redirecting to /dev/null is needed because script generates a large number of PHP notices. Then you can open the resulting file in KCachegrind.