Installing and Using APD

APD is part of PECL and can thus be installed with the PEAR installer:

# pear install apd

After APD is installed, you should enable it by setting the following in your php.ini file:

zend_extension=/path/to/apd.so
apd.dumpdir=/tmp/traces

APD works by dumping trace files that can be postprocessed with the bundled pprofp TRace-processing tool. These traces are dumped into apd.dumpdir, under the name pprof.pid, where pid is the process ID of the process that dumped the trace.

To cause a script to be traced, you simply need to call this when you want tracing to start (usually at the top of the script):

apd_set_pprof_trace();

APD works by logging the following events while a script runs:

When a function is entered.
When a function is exited.
When a file is included or required.

Also, whenever a function return is registered, APD checkpoints a set of internal counters and notes how much they have advanced since the previous checkpoint. Three counters are tracked :

Real Time (a.k.a. wall-clock time) The actual amount of real time passed.
User Time The amount of time spent executing user code on the CPU.
System Time The amount of time spent in operating system kernel-level calls.

Accuracy of Internal Timers

APD's profiling is only as accurate as the systems-level resource measurement tools it has available to it. On FreeBSD, all three of the counters are measured with microsecond accuracy. On Linux (at least as of version 2.4), the User Time and System Time counters are only accurate to the centisecond .

After a trace file has been generated, you analyze it with the pprofp script. pprofp implements a number of sorting and display options that allow you to look at a script's behavior in a number of different ways through a single trace file. Here is the list of options to pprofp:

pprofp <flags> <trace file>
    Sort options
    -a    Sort by alphabetic names of subroutines.
    -l    Sort by number of calls to subroutines
    -r    Sort by real time spent in subroutines.
    -R    Sort by real time spent in subroutines (inclusive of child calls).
    -s    Sort by system time spent in subroutines.
    -S    Sort by system time spent in subroutines (inclusive of child calls).
    -u    Sort by user time spent in subroutines.
    -U    Sort by user time spent in subroutines (inclusive of child calls).
    -v    Sort by average amount of time spent in subroutines.
    -z    Sort by user+system time spent in subroutines. (default)

    Display options
    -c    Display Real time elapsed alongside call tree.
    -i    Suppress reporting for php built-in functions
    -m    Display file/line locations in traces.
    -O <cnt>Specifies maximum number of subroutines to display. (default 15)
    -t    Display compressed call tree.
    -T    Display uncompressed call tree.

Of particular interest are the -t and -T options, which allow you to display a call tree for the script and the entire field of sort options. As indicated, the sort options allow for functions to be sorted either based on the time spent in that function exclusively (that is, not including any time spent in any child function calls) or on time spent, inclusive of function calls.

In general, sorting on real elapsed time (using -r and -R) is most useful because it is the amount of time a visitor to the page actually experiences. This measurement includes time spent idling in database access calls waiting for responses and time spent in any other blocking operations. Although identifying these bottlenecks is useful, you might also want to evaluate the performance of your raw code without counting time spent in input/output (I/O) waiting. For this, the -z and -Z options are useful because they sort only on time spent on the CPU .

Table of Contents