PHP-APD
----------------------------------------------------------------------------- *

    Welcome to Version 2 of this README.  If you have read the README
    before, you may want to read it again.  There may be new stuff, 
    particularly regarding how to use the new pprof tracing.

Buid/Installation process:
----------------------------------------------------------------------------- *

    Make sure you have installed the CGI version of PHP and it is available
    in your current path along with the phpize script.

    Change into the source directory (either created from the downloaded TAR
    archive or from checking out CVS) an run the following commands:

        phpize  (not necessary if configure exists)
        ./configure
        make install


    This automatically should install the 'php_apd' zend module into your

        <PHP INSTALL PATH>/lib/php/<ZEND VERSION><-OPTIONAL_DEBUG>/

    directory. It isn't mandatory to have it there, in fact you can install
    it anywhere you care.


    In your INI file, add the following lines:

        zend_extension = /absolute/path/to/php_apd.so
        apd.dumpdir = /absolute/path/to/trace/directory

    Depending on your PHP build, the zend_extension directive can be one
    of the following:

        zend_extension              (non ZTS, non debug build)
        zend_extension_ts           (    ZTS, non debug build)
        zend_extension_debug        (non ZTS,     debug build)
        zend_extension_debug_ts     (    ZTS,     debug build)

        zend_extension_debug = /absolute/path/to/php_apd.so

    apd.dumpdir:

        This can either be an absolute path or a relative path. Relative
        means always relative to your where from you run your executeable.


    *** NOTE ******************************************************************
    *
    * If you're running the CGI version of PHP, you will need to add the '-e'
    * flag to enable extended information for apd to work properly:
    *
    *     php -e -f script.php
    *
    ***************************************************************************


Win32ism
----------------------------------------------------------------------------- *

    To build APD under windows you need a working PHP compilation
    environment as described on http://php.net/ (basically, it requires
    you to have MSVC, win32build.zip and bison/flex and some know how
    about how to get it to work). Also make sure that adp.dsp has DOS
    line endings! If it has unix line endings, MSVC will complain about it.

    You can use normal Windows path values for your PHP.INI settings:

        zend_extension_debug_ts = c:\phpdev\php_apd.dll
        apd.dumpdir = c:\phpdev\traces


How to use PHP-APD in your scripts with pprof (new style)
----------------------------------------------------------------------------- *

    This section describes the new way that profiling works under apd.  The 
    old method, which generates a non-machine parseable indented output is
    still available (see below), but is debing deprecated in favor of this,
    the pprof output style, which dumps a machine-readable file and provides
    a tool for interpreting the trace.  This allows for much greater specificity
    in the output, allows different sorts of summary generation, and a good
    deal of conrol over the call-tree output.  

    To set pprof tracing, just add the following line to the top of your
    phpp script:

        apd_set_pprof_trace();

    This will generate a pprof.<pid> file in your apd.dumpdir.  The format
    of this file is as follows:

! 1 simple.php
& 1 main 2
+ 1 1 2
- 2
& 3 hello 2
+ 3 1 9
- 3
& 4 yell 2
+ 4 1 9
& 5 strtoupper 1
+ 5 1 4
- 5
- 4
- 1


! assigns a numeric index to a file so we can easily reference that file later. 
& declares a new function and it's index for the trace.  
+ shows a function being entered and the file index and line number it was called on. 
- shows a function being exited. 
@ shows a time elapsed in the form  
    @ process_user_clock_t process_system_clock_t process_real_clock_t

The syntax of the file is largely for informational purposes, it's not designed
for human consumption.  To extract human-readable information from the trace, use
the pprofp utility, bundled with APD.  The options to apd are:

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 builtin functions
    -O <cnt>    Specifies maximum number of subroutines to display. (default 15)
    -t          Display compressed call tree.
    -T          Display uncompressed call tree

Thus, to get basic output on the trace, we would do 

pprofp -u /tmp/pprof.<pid>

and we get something like:

10:33:29(george@ballista)[~/pear/PECL/apd]> pprofp -u /tmp/pprof.23424

Trace for /data/storage/mirrors/www.php.net/index.php
Total Elapsed Time =    0.09
Total System Time  =    0.00
Total User Time    =    0.06


         Real         User        System             secs/    cumm
%Time (excl/cumm)  (excl/cumm)  (excl/cumm) Calls    call    s/call Name
------------------------------------------------------------------------
 33.3  0.02  0.02   0.02  0.02   0.00  0.00     7   0.0029    0.00 require_once
 33.3  0.01  0.01   0.02  0.02   0.00  0.00    55   0.0004    0.00 sprintf
 33.3  0.00  0.00   0.02  0.02   0.00  0.00   144   0.0001    0.00 feof
  0.0  0.00  0.00   0.00  0.00   0.00  0.00     1   0.0000    0.00 htmlspecialchars
  0.0  0.00  0.00   0.00  0.00   0.00  0.00     1   0.0000    0.00 substr
  0.0  0.00  0.00   0.00  0.00   0.00  0.00     1   0.0000    0.00 make_submit
  0.0  0.00  0.00   0.00  0.00   0.00  0.00     7   0.0000    0.00 printf
  0.0  0.02  0.02   0.00  0.00   0.00  0.00     6   0.0000    0.00 printf
  0.0  0.02  0.02   0.00  0.00   0.00  0.00     6   0.0000    0.00 getimagesize
  0.0  0.00  0.01   0.00  0.02   0.00  0.00    17   0.0000    0.00 print_link
  0.0  0.00  0.00   0.00  0.00   0.00  0.00    10   0.0000    0.00 delim
  0.0  0.00  0.00   0.00  0.00   0.00  0.00     7   0.0000    0.00 spacer
  0.0  0.00  0.00   0.00  0.00   0.00  0.00     9   0.0000    0.00 hdelim
  0.0  0.00  0.02   0.00  0.01   0.00  0.00     2   0.0000    0.01 download_link
  0.0  0.00  0.00   0.00  0.00   0.00  0.00     1   0.0000    0.00 mirror_provider_url
  0.0  0.00  0.00   0.00  0.00   0.00  0.00     1   0.0000    0.00 mirror_provider
  0.0  0.00  0.00   0.00  0.00   0.00  0.00     1   0.0000    0.00 strftime
  0.0  0.00  0.00   0.00  0.00   0.00  0.00     1   0.0000    0.00 have_stats
  0.0  0.00  0.00   0.00  0.00   0.00  0.00     1   0.0000    0.00 commonfooter
  0.0  0.00  0.00   0.00  0.00   0.00  0.00     2   0.0000    0.00 strrchr
  0.0  0.01  0.01   0.00  0.00   0.00  0.00     2   0.0000    0.00 filesize

This sorts output based on the usertime spent in subroutines, and ommits a call tree.  If
we added a -t

10:38:30(george@ballista)[~/pear/PECL/apd]> pprofp -u -t /tmp/pprof.23424

...

We would also get a call graph for the function.  Which is often very long.




How to use PHP-APD in your scripts (old style)
----------------------------------------------------------------------------- *

    In your PHP script, add the following line:

        apd_set_session_trace(N);

    where N is an integer which is formed by masking together the following
    values:

        FUNCTION_TRACE      1
        ARGS_TRACE          2
        ASSIGNMENT_TRACE    4
        STATEMENT_TRACE     8
        MEMORY_TRACE        16
        TIMING_TRACE        32
        SUMMARY_TRACE       64

    I would seriously not recommend using MEMORY_TRACE.  It is very slow and
    does not appear to be accurate (great, huh?)  also ASSIGNMENT_TRACE is not
    implemented. So, to turn on all functional traces (TIMING, FUNCTIONS, ARGS
    SUMMARY (like strace -c)) use:

        apd_set_session_trace(99);


    Now run your script.


    The dump output will be writting to:

        <apd.dumpdir>/apd_dump_<pid>

    The output itself will look something like:

16:37:51(george@wasabi)[~/src/apd]> cat /tmp/apd_dump_31994 


APD - Advanced PHP Debugger Trace File
---------------------------------------------------------------------------
Process Pid (31994)
Trace Begun at Fri Aug 10 16:37:45 2001
---------------------------------------------------------------------------
(  0.000000): apd_set_session_trace called at somewhere
(  0.001482): apd_set_session_trace() returned.  Elapsed (997475865.364909)
(  0.001563): getcwd() /opt/apache/htdocs/a.php:4
(  0.001628): getcwd() returned.  Elapsed (0.000065)
(  0.001819): require() /opt/apache/htdocs/a.php:6
              ++ argv[0] $(??) = /tmp/a.php
(  0.002231):   getcwd() /tmp/a.php:3
(  0.002290):   getcwd() returned.  Elapsed (0.000059)
(  0.002375):   include_once() /tmp/a.php:4
                ++ argv[0] $(??) = /tmp/aa.php
(  0.003276):   include_once() returned.  Elapsed (0.000901)
(  0.003334): require() returned.  Elapsed (0.001515)
(  0.003381): require_once() /opt/apache/htdocs/a.php:7
              ++ argv[0] $(??) = /tmp/aa.php
(  0.003515): require_once() returned.  Elapsed (0.000134)
(  0.003564): include() /opt/apache/htdocs/a.php:8
              ++ argv[0] $(??) = /tmp/b.php
(  0.003792): include() returned.  Elapsed (0.000228)
(  0.018341): RSHUTDOWN called - end of trace
---------------------------------------------------------------------------
Process Pid (31994)
Trace Ended at Fri Aug 10 16:37:45 2001
---------------------------------------------------------------------------


Implemented Debugging Functions
----------------------------------------------------------------------------- *

    array apd_callstack()
        Returns the current call stack as an array (very cool).

    apd_cluck([string warning[,string line delimiter])
        Behaves like perl's Carp::cluck. Throw a warning and a callstack.
        The default line delimiter is "<BR />\n".

    apd_croak([string error[, string line delimiter]])
        Behaves like perl's Carp::croak. Throw an error, a callstack and then
        exit.  The default line delimiter is "<BR />\n".

    array apd_dump_regular_resources()
        Return all current regular resources as an array.

    array apd_dump_persistent_resources()
        Return all persistent resources as an array.

    override_function(string func_name, string func_args, string func_code):
        Syntax similar to create_function(). Overrides built-in functions
        (replaces them in the symbol table).

    rename_function(string orig_name, string new_name)
        Renames orig_name to new_name in the global function_table.  Useful
        for temporarly overriding builtin functions.