mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-15 08:28:54 +00:00
5fcbcd6b56
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@351562 c90b9560-bf6c-de11-be94-00142212c4b1
408 lines
12 KiB
XML
408 lines
12 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!-- $Revision$ -->
|
|
<chapter xml:id="oci8.dtrace" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
|
|
<title>OCI8 and DTrace Dynamic Tracing</title>
|
|
<section>
|
|
<para>
|
|
OCI8 2.0 introduced static DTrace probes that can be used on
|
|
operating systems that support DTrace.
|
|
See <link linkend="features.dtrace">DTrace Dynamic Tracing</link>
|
|
for an overview of PHP and DTrace.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Installing OCI8 with DTrace Support</title>
|
|
<para>
|
|
To enable DTrace support in PHP OCI8, build OCI8 as a shared
|
|
extension after setting <literal>PHP_DTRACE</literal>.
|
|
</para>
|
|
<para>
|
|
<informalexample>
|
|
<screen>
|
|
<![CDATA[
|
|
$ export PHP_DTRACE=yes
|
|
$ pecl install oci8
|
|
]]>
|
|
</screen>
|
|
</informalexample>
|
|
</para>
|
|
<para>
|
|
Edit php.ini,
|
|
set <link linkend="ini.extension-dir">extension_dir</link> to the
|
|
directory with the created <filename>oci8.so</filename> and also
|
|
enable the extension by adding:
|
|
</para>
|
|
<para>
|
|
<informalexample>
|
|
<screen>
|
|
<![CDATA[
|
|
extension=oci8.so
|
|
]]>
|
|
</screen>
|
|
</informalexample>
|
|
</para>
|
|
<para>
|
|
If you install PHP OCI8 from PECL using <filename>phpize</filename> and
|
|
<filename>configure</filename> (instead
|
|
of <filename>pecl</filename>), you will still need to set
|
|
<literal>PHP_DTRACE=yes</literal>. This is because
|
|
the <literal>--enable-dtrace</literal> option will be ignored by the
|
|
limited <filename>configure</filename> script of a PECL bundle.
|
|
</para>
|
|
|
|
<para>
|
|
See <link linkend="install.pecl">Installation of PECL
|
|
extensions</link> for general PECL installation instructions.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>DTrace Static Probes in PHP OCI8</title>
|
|
<table>
|
|
<title>The following static probes are available in PHP OCI8</title>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Probe Name</entry>
|
|
<entry>Probe Description</entry>
|
|
<entry>Probe Arguments</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry><literal>oci8-connect-entry</literal></entry>
|
|
<entry>Initiated by oci_connect(), oci_pconnect() and oci_new_connect(). Fires before database connection is established.</entry>
|
|
<entry>char *<varname>username</varname>, char *<varname>dbname</varname>, char *<varname>charset</varname>, long <varname>session_mode</varname>, int <varname>persistent</varname>, int <varname>exclusive</varname></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>oci8-connect-return</literal></entry>
|
|
<entry>Fires at the end of connection.</entry>
|
|
<entry>void *<varname>connection</varname></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>oci8-check-connection</literal></entry>
|
|
<entry>Fires if an Oracle error might have caused the connection to become invalid.</entry>
|
|
<entry>void *<varname>connection</varname>, char *<varname>client_id</varname>, int <varname>is_open</varname>, long <varname>errcode</varname>, unsigned long <varname>server_status</varname></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>oci8-sqltext</literal></entry>
|
|
<entry>Fires when oci_parse() is executed.</entry>
|
|
<entry>void *<varname>connection</varname>, char *<varname>client_id</varname>, void *<varname>statement</varname>, char *<varname>sql</varname></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>oci8-connection-close</literal></entry>
|
|
<entry>Fires when the connection to the database is completely destroyed.</entry>
|
|
<entry>void *<varname>connection</varname></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>oci8-error</literal></entry>
|
|
<entry>Fires if an Oracle error occurs.</entry>
|
|
<entry>int <varname>status</varname>, long <varname>errcode</varname></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>oci8-execute-mode</literal></entry>
|
|
<entry>Fires at <function>oci_execute</function> to show the execution mode.</entry>
|
|
<entry>void *<varname>connection</varname>, char *<varname>client_id</varname>, void *<varname>statement</varname>, unsigned int <varname>mode</varname></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
<para>
|
|
These probes are useful for tracing OCI8 scripts.
|
|
</para>
|
|
|
|
<para>
|
|
The <varname>connection</varname> and <varname>statement</varname>
|
|
are the pointers to internal structures used for tracking PHP
|
|
connections and executed statements.
|
|
</para>
|
|
|
|
<para>
|
|
The <varname>client_id</varname> is the value set
|
|
by <function>oci_set_client_identifier</function>.
|
|
</para>
|
|
|
|
<para>
|
|
</para>
|
|
|
|
<para>
|
|
</para>
|
|
|
|
<para>
|
|
</para>
|
|
|
|
|
|
<para>
|
|
Core PHP also has static probes.
|
|
See <link linkend="features.dtrace.static-probes">DTrace Static
|
|
Probes in Core PHP</link>.
|
|
</para>
|
|
|
|
<table>
|
|
<title>Internal Debugging DTrace Probes in OCI8</title>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Probe Name</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry><literal>oci8-connect-expiry</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>oci8-connect-lookup</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>oci8-connect-p-dtor-close</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>oci8-connect-p-dtor-release</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>oci8-connect-type</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>oci8-sesspool-create</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>oci8-sesspool-stats</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>oci8-sesspool-type</literal></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
<para>
|
|
These probes are useful for OCI8 maintainers. Refer to the OCI8 source code for arguments and to see when the will fire.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Listing DTrace Static Probes in PHP OCI8</title>
|
|
<para>
|
|
To list available probes, start a PHP process and then run:
|
|
<informalexample>
|
|
<programlisting>
|
|
<![CDATA[
|
|
# dtrace -l
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
|
|
<para>
|
|
The output will be similar to:
|
|
<informalexample>
|
|
<programlisting>
|
|
<![CDATA[
|
|
ID PROVIDER MODULE FUNCTION NAME
|
|
[ . . . ]
|
|
17 phpoci22116 oci8.so php_oci_dtrace_check_connection oci8-check-connection
|
|
18 phpoci22116 oci8.so php_oci_do_connect oci8-connect-entry
|
|
19 phpoci22116 oci8.so php_oci_persistent_helper oci8-connect-expiry
|
|
20 phpoci22116 oci8.so php_oci_do_connect_ex oci8-connect-lookup
|
|
21 phpoci22116 oci8.so php_oci_pconnection_list_np_dtor oci8-connect-p-dtor-close
|
|
22 phpoci22116 oci8.so php_oci_pconnection_list_np_dtor oci8-connect-p-dtor-release
|
|
23 phpoci22116 oci8.so php_oci_do_connect oci8-connect-return
|
|
24 phpoci22116 oci8.so php_oci_do_connect_ex oci8-connect-type
|
|
25 phpoci22116 oci8.so php_oci_connection_close oci8-connection-close
|
|
26 phpoci22116 oci8.so php_oci_error oci8-error
|
|
27 phpoci22116 oci8.so php_oci_statement_execute oci8-execute-mode
|
|
28 phpoci22116 oci8.so php_oci_create_spool oci8-sesspool-create
|
|
29 phpoci22116 oci8.so php_oci_create_session oci8-sesspool-stats
|
|
30 phpoci22116 oci8.so php_oci_create_session oci8-sesspool-type
|
|
31 phpoci22116 oci8.so php_oci_statement_create oci8-sqltext
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
|
|
<para>
|
|
The Provider column values consist of <literal>phpoci</literal> and
|
|
the process id of the currently running PHP process.
|
|
</para>
|
|
|
|
<para>
|
|
The Function column refers to PHP's internal C implementation
|
|
function names where each provider is located.
|
|
</para>
|
|
|
|
<para>
|
|
If a PHP process is not running, then no PHP probes will be shown.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>DTrace with PHP OCI8 Example</title>
|
|
<para>
|
|
This example shows the basics of the DTrace D scripting language.
|
|
<example>
|
|
<title><filename>user_oci8_probes.d</filename> for tracing all user-level PHP OCI8 Static Probes with DTrace</title>
|
|
<programlisting>
|
|
<![CDATA[
|
|
#!/usr/sbin/dtrace -Zs
|
|
|
|
#pragma D option quiet
|
|
|
|
php*:::oci8-connect-entry
|
|
{
|
|
printf("%lld: PHP connect-entry\n", walltimestamp);
|
|
printf(" credentials=\"%s@%s\"\n", arg0 ? copyinstr(arg0) : "", arg1 ? copyinstr(arg1) : "");
|
|
printf(" charset=\"%s\"\n", arg2 ? copyinstr(arg2) : "");
|
|
printf(" session_mode=%ld\n", (long)arg3);
|
|
printf(" persistent=%d\n", (int)arg4);
|
|
printf(" exclusive=%d\n", (int)arg5);
|
|
}
|
|
|
|
php*:::oci8-connect-return
|
|
{
|
|
printf("%lld: PHP oci8-connect-return\n", walltimestamp);
|
|
printf(" connection=0x%p\n", (void *)arg0);
|
|
}
|
|
|
|
php*:::oci8-connection-close
|
|
{
|
|
printf("%lld: PHP oci8-connect-close\n", walltimestamp);
|
|
printf(" connection=0x%p\n", (void *)arg0);
|
|
}
|
|
|
|
php*:::oci8-error
|
|
{
|
|
printf("%lld: PHP oci8-error\n", walltimestamp);
|
|
printf(" status=%d\n", (int)arg0);
|
|
printf(" errcode=%ld\n", (long)arg1);
|
|
}
|
|
|
|
php*:::oci8-check-connection
|
|
{
|
|
printf("%lld: PHP oci8-check-connection\n", walltimestamp);
|
|
printf(" connection=0x%p\n", (void *)arg0);
|
|
printf(" client_id=\"%s\"\n", arg1 ? copyinstr(arg1) : "");
|
|
printf(" is_open=%d\n", arg2);
|
|
printf(" errcode=%ld\n", (long)arg3);
|
|
printf(" server_status=%lu\n", (unsigned long)arg4);
|
|
}
|
|
|
|
php*:::oci8-sqltext
|
|
{
|
|
printf("%lld: PHP oci8-sqltext\n", walltimestamp);
|
|
printf(" connection=0x%p\n", (void *)arg0);
|
|
printf(" client_id=\"%s\"\n", arg1 ? copyinstr(arg1) : "");
|
|
printf(" statement=0x%p\n", (void *)arg2);
|
|
printf(" sql=\"%s\"\n", arg3 ? copyinstr(arg3) : "");
|
|
}
|
|
|
|
php*:::oci8-execute-mode
|
|
{
|
|
printf("%lld: PHP oci8-execute-mode\n", walltimestamp);
|
|
printf(" connection=0x%p\n", (void *)arg0);
|
|
printf(" client_id=\"%s\"\n", arg1 ? copyinstr(arg1) : "");
|
|
printf(" statement=0x%p\n", (void *)arg2);
|
|
printf(" mode=0x%x\n", arg3);
|
|
}
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
|
|
<para>
|
|
This script uses the <literal>-Z</literal> option to
|
|
<filename>dtrace</filename>, allowing it to be run when there is no
|
|
PHP process executing. If this option were omitted the script
|
|
would immediately terminate when no PHP executable was running
|
|
because it knows none of the probes to be monitored are in
|
|
existence.
|
|
</para>
|
|
|
|
<para>
|
|
On multi-CPU machines the probe ordering might not appear to be
|
|
sequential. This depends on which CPU was processing the probes,
|
|
and how threads migrate across CPUs. Displaying probe time stamps
|
|
helps reduce confusion.
|
|
</para>
|
|
|
|
<para>
|
|
The script traces all user-level PHP OCI8 static probe points
|
|
throughout the duration of a running PHP script. Run the D script:
|
|
<informalexample>
|
|
<programlisting>
|
|
<![CDATA[
|
|
# ./user_oci8_probes.d
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
|
|
<para>
|
|
Run a PHP script or application. The monitoring D script will
|
|
output each probe's arguments as it fires. For example, a simple
|
|
PHP script that queries a table might produce the following trace
|
|
output:
|
|
<informalexample>
|
|
<programlisting>
|
|
<![CDATA[
|
|
1381794982092854582: PHP connect-entry
|
|
credentials="hr@localhost/pdborcl"
|
|
charset=""
|
|
session_mode=0
|
|
persistent=0
|
|
exclusive=0
|
|
1381794982183158766: PHP oci8-connect-return
|
|
connection=0x7f4a7907bfb8
|
|
1381794982183594576: PHP oci8-sqltext
|
|
connection=0x7f4a7907bfb8
|
|
client_id="Chris"
|
|
statement=0x7f4a7907c2a0
|
|
sql="select * from employees"
|
|
1381794982183783706: PHP oci8-execute-mode
|
|
connection=0x7f4a7907bfb8
|
|
client_id="Chris"
|
|
statement=0x7f4a7907c2a0
|
|
mode=0x20
|
|
1381794982444344390: PHP oci8-connect-close
|
|
connection=0x7f4a7907bfb8
|
|
]]>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
|
|
<para>
|
|
When monitoring is complete, the D script can be terminated with a
|
|
<literal>^C</literal>.
|
|
</para>
|
|
|
|
</section>
|
|
|
|
<section>
|
|
<title>See Also</title>
|
|
<simplelist>
|
|
<member><link linkend="features.dtrace">DTrace Dynamic Tracing</link></member>
|
|
</simplelist>
|
|
</section>
|
|
|
|
</chapter>
|
|
|
|
<!-- 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:"~/.phpdoc/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
|
|
-->
|
|
|