dbs Tue Sep 28 00:35:03 2004 EDT
Added files:
/phpdoc/en/reference/apd ini.xml
Modified files:
/phpdoc manual.xml.in
/phpdoc/en/reference rsusi.txt
/phpdoc/en/reference/apd configure.xml reference.xml
/phpdoc/en/reference/apd/functions apd-set-pprof-trace.xml
Log:
Update APD documentation; add APD to manual
http://cvs.php.net/diff.php/phpdoc/manual.xml.in?r1=1.196&r2=1.197&ty=u
Index: phpdoc/manual.xml.in
diff -u phpdoc/manual.xml.in:1.196 phpdoc/manual.xml.in:1.197
--- phpdoc/manual.xml.in:1.196 Wed Sep 22 11:52:42 2004
+++ phpdoc/manual.xml.in Tue Sep 28 00:35:02 2004
@@ -2,7 +2,7 @@
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"@srcdir@/dtds/dbxml-4.1.2/docbookx.dtd" [
-<!-- $Revision: 1.196 $ -->
+<!-- $Revision: 1.197 $ -->
<!-- Add translated specific definitions and snippets -->
<!ENTITY % language-defs SYSTEM "@srcdir@/@LANGDIR@/language-defs.ent">
@@ -121,6 +121,7 @@
-->
&reference.apache.reference;
+ &reference.apd.reference;
&reference.array.reference;
&reference.aspell.reference;
&reference.bc.reference;
http://cvs.php.net/diff.php/phpdoc/en/reference/rsusi.txt?r1=1.49&r2=1.50&ty=u
Index: phpdoc/en/reference/rsusi.txt
diff -u phpdoc/en/reference/rsusi.txt:1.49 phpdoc/en/reference/rsusi.txt:1.50
--- phpdoc/en/reference/rsusi.txt:1.49 Sun Feb 8 01:49:52 2004
+++ phpdoc/en/reference/rsusi.txt Tue Sep 28 00:35:02 2004
@@ -23,6 +23,7 @@
Extension New Ref Struct ini configure constants
--------------------------------------------------------------------------------
apache yes none none
+apd PECL 5.0 yes yes none
array none none yes
aspell removed 4.3 yes none
bc yes yes none
http://cvs.php.net/diff.php/phpdoc/en/reference/apd/configure.xml?r1=1.1&r2=1.2&ty=u
Index: phpdoc/en/reference/apd/configure.xml
diff -u phpdoc/en/reference/apd/configure.xml:1.1
phpdoc/en/reference/apd/configure.xml:1.2
--- phpdoc/en/reference/apd/configure.xml:1.1 Thu Aug 5 09:15:18 2004
+++ phpdoc/en/reference/apd/configure.xml Tue Sep 28 00:35:02 2004
@@ -1,27 +1,31 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
<section id="apd.installation">
&reftitle.install;
<para>
+ APD is currently available as a PECL extension from
+ <ulink url="&url.pecl.package;apd">&url.pecl.package;apd</ulink>.
Make sure you have installed the CGI version of PHP and it is available
in your current path along with the phpize script.
</para>
<para>
- Change into the source directory (either created from the downloaded TAR
- archive or from checking out CVS) and run the following commands:
- </para>
- <para>
- <programlisting role="shell">
+ Run the following command to download, build, and install the latest stable
+ version of APD:
+ <screen>
<![CDATA[
-./configure
-make install
+pear install apd
]]>
- </programlisting>
+ </screen>
</para>
<para>
- This automatically should install the 'php_apd' zend module into your PHP
- extensions directory. It isn't mandatory to have it there, in fact you can
- install it anywhere you care.
+ This automatically installs the APD Zend module into your PHP
+ extensions directory. It is not mandatory to keep it there; you can
+ store the module in any directory PHP can read as long as you set
+ the zend_extension parameter accordingly.
+ </para>
+ <para>
+ Windows users can download the extension dll <filename>php_apd.dll</filename>
+ from <ulink url="&url.pecl.get.win;">&url.pecl.get.win;</ulink>.
</para>
<para>
In your INI file, add the following lines:
@@ -29,15 +33,12 @@
<para>
<programlisting role="php.ini">
<![CDATA[
-zend_extension = /absolute/path/to/php_apd.so
+zend_extension = /absolute/path/to/apd.so
apd.dumpdir = /absolute/path/to/trace/directory
+apd.statement_trace = 0
]]>
</programlisting>
</para>
-</section>
-
-<section id="apd.zend_extension">
- <title>php.ini zend_extension setting</title>
<para>
Depending on your PHP build, the zend_extension directive can be one of the
following:
@@ -49,54 +50,19 @@
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
]]>
</programlisting>
</para>
</section>
-<section id="apd.dumpdir">
- <title>&php.ini; apd.dumpdir setting</title>
- <para>
- This can either be an absolute path or a relative path. Relative
- means always relative to your where from you run your executeable.
- </para>
- <para>
- <programlisting role="text">
-<![CDATA[
- *** 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
- *
- ***************************************************************************
- ]]>
- </programlisting>
- </para>
-</section>
-
<section id="apd.installwin32">
<title>Building on Win32</title>
<para>
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.
- </para>
- <para>
- You can use normal Windows path values for your &php.ini; settings:
- </para>
- <para>
- <programlisting role="php.ini">
-<![CDATA[
-zend_extension_debug_ts = c:\phpdev\php_apd.dll
-apd.dumpdir = c:\phpdev\traces
-]]>
- </programlisting>
+ environment as described on http://php.net/ -- basically, it requires
+ you to have Microsoft Visual C++, win32build.zip, bison/flex, and some know how
+ to get it to work. Also ensure that adp.dsp has DOS line endings; if it has unix
+ line endings, Microsoft Visual C++ will complain about it.
</para>
</section>
http://cvs.php.net/diff.php/phpdoc/en/reference/apd/reference.xml?r1=1.3&r2=1.4&ty=u
Index: phpdoc/en/reference/apd/reference.xml
diff -u phpdoc/en/reference/apd/reference.xml:1.3
phpdoc/en/reference/apd/reference.xml:1.4
--- phpdoc/en/reference/apd/reference.xml:1.3 Sat Sep 25 11:15:11 2004
+++ phpdoc/en/reference/apd/reference.xml Tue Sep 28 00:35:03 2004
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
<reference id="ref.apd">
<title>Advanced PHP debugger</title>
<titleabbrev>APD</titleabbrev>
@@ -8,28 +8,44 @@
<section id="apd.intro">
&reftitle.intro;
<para>
- APD is the Advanced PHP Debugger. It was written to provide strace/truss
- capability for profiling and debugging php code, as well as providing the
- ability to print out a full stack backtrace. APD does supports
- interactive and non interactive debugging, by default it writes data to
- trace files. APD provides event based logging, so that varying levels of
- information (including function calls, arguments passed, timings, etc.)
- can be turned on or off for individual scripts.
- </para>
+ APD is the Advanced PHP Debugger. It was written to provide profiling and
+ debugging capabilities for PHP code, as well as to provide the ability to
+ print out a full stack backtrace. APD supports interactive debugging, but
+ by default it writes data to trace files. It also offers event based
+ logging so that varying levels of information (including function calls,
+ arguments passed, timings, etc.) can be turned on or off for individual
+ scripts.
+ <caution>
<para>
APD is a Zend Extension, modifying the way the internals of PHP handle
function calls, and thus may or may not be compatible with other Zend
Extensions (for example Zend Optimizer).
</para>
+ </caution>
+ </para>
</section>
&reference.apd.configure;
+ &reference.apd.ini;
- <section id="apd.examples">
+ <section id="apd.resources">
+ &reftitle.resources;
+ &no.resource;
+ </section>
+
+ <section id="apd.constants">
+ &reftitle.constants;
+ &no.constants;
+ </section>
+
+ <section id="apd.examples">
<title>How to use PHP-APD in your scripts</title>
+ <procedure>
+ <step>
<para>
- In your PHP script, add the following line:
+ As the first line of your PHP script, call the apd_set_pprof_trace() function
+ to start the trace:
</para>
<para>
<programlisting role="php">
@@ -39,59 +55,71 @@
</programlisting>
</para>
<para>
- Now run your script.
- </para>
- <para>
- The dump output will be writing to:
- </para>
- <para>
- <programlisting role="text">
-<![CDATA[
-<apd.dumpdir>/apd_dump_<pid>
-]]>
- </programlisting>
+ You can insert the line anywhere in your script, but if you do not start
+ tracing at the beginning of your script you discard profile data that might
+ otherwise lead you to a performance bottleneck.
+ </para>
+ </step>
+ <step>
+ <para>
+ Now run your script. The dump output will be written to
+ <filename>apd.dumpdir/pprof_pid.ext</filename>.
+ <tip>
+ <para>
+ 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. For
+ example:
+ <userinput>php -e -f script.php</userinput>
+ </para>
+ </tip>
</para>
+
+ </step>
+ <step>
<para>
- The output itself will look something like:
+ To display formatted profile data, issue the <command>pprofp</command>
+ command with the sort and display options of your choice. The formatted
+ output will look something like:
<screen>
<![CDATA[
-16:37:51([EMAIL PROTECTED])[~/src/apd]> cat /tmp/apd_dump_31994
+bash-2.05b$ pprofp -R /tmp/pprof.22141.0
-APD - Advanced PHP Debugger Trace File
----------------------------------------------------------------------------
-Process Pid (31994)
-Trace Begun at Fri Aug 10 16:37:45 2001
----------------------------------------------------------------------------
-( 0.000000): apd_set_pprof_trace called at somewhere
-( 0.001482): apd_set_pprof_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
----------------------------------------------------------------------------
+Trace for /home/dan/testapd.php
+Total Elapsed Time = 0.00
+Total System Time = 0.00
+Total User Time = 0.00
+
+
+Real User System secs/ cumm
+%Time (excl/cumm) (excl/cumm) (excl/cumm) Calls call s/call Memory Usage Name
+--------------------------------------------------------------------------------------
+100.0 0.00 0.00 0.00 0.00 0.00 0.00 1 0.0000 0.0009 0 main
+56.9 0.00 0.00 0.00 0.00 0.00 0.00 1 0.0005 0.0005 0
apd_set_pprof_trace
+28.0 0.00 0.00 0.00 0.00 0.00 0.00 10 0.0000 0.0000 0 preg_replace
+14.3 0.00 0.00 0.00 0.00 0.00 0.00 10 0.0000 0.0000 0 str_replace
]]>
</screen>
</para>
+ <para>
+ The -R option used in this example sorts the profile table by the amount
+ of real time the script spent executing a given function. The "cumm call"
+ column reveals how many times each function was called, and the "s/call"
+ column reveals how many seconds each call to the function required, on
+ average.
+ </para>
+ </step>
+ <step>
+ <para>
+ To generate a calltree file that you can import into the KCacheGrind
+ profile analysis application, issue the <command>pprof2calltree</command>
+ comand.
+ </para>
+ </step>
+ </procedure>
</section>
<section id="apd.contact">
- <title>Contact Information</title>
+ <title>Contact information</title>
<para>
If you have comments, bugfixes, enhancements or want to help developing
this beast, you can send an mail to
http://cvs.php.net/diff.php/phpdoc/en/reference/apd/functions/apd-set-pprof-trace.xml?r1=1.1&r2=1.2&ty=u
Index: phpdoc/en/reference/apd/functions/apd-set-pprof-trace.xml
diff -u phpdoc/en/reference/apd/functions/apd-set-pprof-trace.xml:1.1
phpdoc/en/reference/apd/functions/apd-set-pprof-trace.xml:1.2
--- phpdoc/en/reference/apd/functions/apd-set-pprof-trace.xml:1.1 Sat Sep 25
11:15:12 2004
+++ phpdoc/en/reference/apd/functions/apd-set-pprof-trace.xml Tue Sep 28 00:35:03
2004
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
<refentry id="function.apd-set-pprof-trace">
<refnamediv>
<refname>apd_set_pprof_trace</refname>
@@ -12,7 +12,7 @@
<methodparam
choice="opt"><type>string</type><parameter>dump_directory</parameter></methodparam>
</methodsynopsis>
<para>
- Starts debugging to {dump_directory}/apd_dump_{process_id}, if
+ Starts debugging to {dump_directory}/pprof_{process_id}, if
dump_directory is not set, then the apd.dumpdir setting from the
&php.ini; file is used.
</para>
http://cvs.php.net/co.php/phpdoc/en/reference/apd/ini.xml?r=1.1&p=1
Index: phpdoc/en/reference/apd/ini.xml
+++ phpdoc/en/reference/apd/ini.xml
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<section id="apd.configuration">
&reftitle.runtime;
&ini.descriptions.title;
<para>
<variablelist>
<varlistentry id="ini.apd.dumpdir">
<term>
<parameter>apd.dumpdir</parameter>
<type>string</type>
</term>
<listitem>
<para>
Sets the directory in which APD writes profile dump files.
You can specify an absolute path or a relative path.
</para>
<para>
You can specify a different directory as an argument
to apd_set_pprof_trace().
</para>
</listitem>
</varlistentry>
<varlistentry id="ini.apd.statement-trace">
<term>
<parameter>apd.statement_trace</parameter>
<type>boolean</type>
</term>
<listitem>
<para>
Specfies whether or not to do per-line tracings. Turning this on (1) will
impact the performance of your application.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</section>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
