php-doc-en/reference/oci8/dtrace.xml
Christopher Jones 5fcbcd6b56 Do a pass through the OCI8 doc
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@351562 c90b9560-bf6c-de11-be94-00142212c4b1
2020-11-24 04:34:15 +00:00

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
-->