Getting apd to run properly

This is a short summary of everything to is a precondition to be able to run APD as a PHP profiler. The description applies for PHP 5.6.2 and APD 1.0.1 and might be/is incorrect for other PHP/APD versions.

Absolute Preconditions

Do not start if you didn't ensure the following:

Deactivate the Zend platform or any other PHP optimizer. In general it is wise to disable all Zend extensions.
Install a debugging enabled PHP version (compiled using --enable-debug)

Correct APD Compilation

If you have a working PEAR setup you might want to setup APD as described in this Linux Journal article. Also try distribution packages. Otherwise APD is build as following:

Extract tarball.
Change working directory into tarball.
Run
```
<apache root>/bin/phpize
```
Run
```
./configure
```
Add "--with-php-config=<apache root>/bin/php-config" if configure fails.
Compile and install everything using
```
make
make install
```

Edit php.ini and add at least

zend_extension=<path from make install>/apd.so
apd.statement=1
apd.tracedir=/tmp/apd-traces

Create the output directory specified in php.ini.

Now before restarting your Apache ensure that the APD extension works properly. To do so simply run PHP

<apache root>/bin/php

Once entered no message should be given if the extension is loaded properly. If you get an error message here that the "apd.so" extension could not be loaded you have a problem. Ensure that you compiled against the correct PHP/Apache version and are using the same PHP runtime right now.

If PHP doesn't complain about anything enter

<?php
phpinfo();
?>

and check for some lines about the APD. If you find them you are ready for work.

Getting Some Traces

To start tracing first restart your Apache to allow the PHP module to load APD. Next you need to identify a script to trace. Add the APD call at the top of the script:

apd_set_pprof_trace();

Then make some requests and remove the statement again to avoid causing further harm.

Now have a look at the trace directory. You should find files with a naming scheme of "pprof[0-9]*.[0-9]" here. Decode them using the "pprofp" tool from your APD source tarball. Example:

<apache root>/bin/php <apd source root>/pprofp -u <trace file>

Redirect stdout if necessary. Use -t instead of -u (summary output) to get calling trees.

Tracing Pitfalls

When you create traces with -t you get a summary output too, but it doesn't contain the per-call durations. I suggest to always create both a call tree and a summary trace.