dtrace.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: f4c44b86948f70a7e89f582b500e2595452e00f0 Maintainer: seros Status: ready -->
<!-- Reviewed: yes -->
<chapter xml:id="oci8.dtrace" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>OCI8 y rastreo dinámico de DTrace</title>
 <para>
  OCI8 2.0 sondeos de DTrace estáticos que se pueden usar en
   sistemas operativos que admiten DTrace.
   Véase <link linkend="features.dtrace">Rastreo dinámico de DTrace</link>
   para una visión general de PHP y DTrace.
  </para>
 
 <section>
  <title>Instalar OCI8 con soporte para DTrace</title>
  <para>
   Para habilitar el soporte para DTrace en OCI8 para PHP, construya OCI8 como una
   extensión compartida después de establecer <literal>PHP_DTRACE</literal>.
  </para>
  <para>
   <informalexample>
    <screen>
<![CDATA[
$ export PHP_DTRACE=yes
$ pecl install oci8
]]>
   </screen>
  </informalexample>
  </para>
  <para>
   Edite php.ini,
   establezca <link linkend="ini.extension-dir">extension_dir</link> al
   directorio con el <filename>oci8.so</filename> creado y también
   habilite la extensión añadiendo:
  </para>
  <para>
   <informalexample>
    <screen>
<![CDATA[
extension=oci8.so
]]>
   </screen>
  </informalexample>
  </para>
  <para>
   Si instala PHP OCI8 2.0 desde PECL usando <filename>phpize</filename> y
   <filename>configure</filename> (en lugar
   de <filename>pecl</filename>), será necesario establecer
   <literal>PHP_DTRACE=yes</literal>. Esto es así debido a que
   la opción <literal>--enable-dtrace</literal> será ignorada por el
   script limitado <filename>configure</filename> de un PECL incluido.
  </para>
  
  <para>
   Véase <link linkend="install.pecl">Instalación de extensiones
   PECL</link> para las instrucciones generales de instalación de PECL.
  </para>
 </section>
 
 <section>
  <title>Sondeos estáticos de DTrace en OCI8 para PHP</title>
  <table>
   <title>Los siguientes sondeos estáticos están disponibles en OCI8 para PHP</title>
   <tgroup cols="2">
    <thead>
     <row>
      <entry>Nombre del sondeo</entry>
      <entry>Descripción del sondeo</entry>
      <entry>Argumentos del sondeo</entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry><literal>oci8-connect-entry</literal></entry>
      <entry>Iniciado por oci_connect(), oci_pconnect() y oci_new_connect(). Lanzado antes de establecer una conexión con una base de datos.</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>Lanzado al finallde una conexión.</entry>
      <entry>void *<varname>connection</varname></entry>
     </row>
     <row>
      <entry><literal>oci8-check-connection</literal></entry>
      <entry>Lanzado si un error de Oracle podría haber causado que la conexión sea inválida.</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>Lanzado cuando oci_parse() se ejecuta.</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>Lanzado cuando la conexión a la base de datos está completamente destruida.</entry>
      <entry>void *<varname>connection</varname></entry>
     </row>
     <row>
      <entry><literal>oci8-error</literal></entry>
      <entry>Lanzado si ocurre un error de Oracle.</entry>
      <entry>int <varname>status</varname>, long <varname>errcode</varname></entry>
     </row>
     <row>
      <entry><literal>oci8-execute-mode</literal></entry>
      <entry>Lanzado en <function>oci_execute</function> para mostrar el modo de ejecución.</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>
   Estos sondeos son útiles para rastrear scripts de OCI8.
  </para>
  
  <para>
   <varname>connection</varname> y <varname>statement</varname>
   son los punteros a las estructuras internas usadas para rastrear conexiones
   de PHP y ejecutar sentencias.
  </para>
  
  <para>
   <varname>client_id</varname> es el valor establecido
   por <function>oci_set_client_identifier</function>.
  </para>
  
  <para>
  </para>
  
  <para>
  </para>
  
  <para>
  </para>
  
  
  <para>
   El núcleo de PHP también posee sondeos estáticos.
   Véase <link linkend="features.dtrace.static-probes">Sondeos estáticos
   de DTrace en el núcleo de PHP</link>.
  </para>
  
  <table>
   <title>Sondeos de DTrace de depuración interna en OCI8</title>
   <tgroup cols="2">
    <thead>
     <row>
      <entry>Nombre del sondeo</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>
   Estos sondeos son útiles para mantenedores de OCI8. Consulte el código fuente de OCI8 para los argumentos y para ver cuando serán lanzados.
  </para>
 </section>
 
 <section>
  <title>Enumerar los Sondeos estáticos de DTrace en OCI8 para PHP</title>
  <para>
   Para enumerar los sondeos disponibles, inicie un proceso de PHP y ejecute:
   <informalexample>
    <programlisting>
<![CDATA[
# dtrace -l
]]>
    </programlisting>
   </informalexample>
  </para>
  
  <para>
   La salida será similar a:
   <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>
   Los valores de la columna "Provider" (Proveedor) consisten en <literal>phpoci</literal> and
   el ID del proceso de PHP ejecutándose actualmente.
  </para>
  
  <para>
   La columna "Function" (Función) se refiere a los nombres de funciones internas
   de la implementación en C de PHP donde cada proveedor está ubicado.
  </para>
  
  <para>
   Si un proceso de PHP no se está ejecutando, no se mostrarán sondeos de PHP.
  </para>
 </section>
 
 <section>
  <title>Ejemplo de DTrace con OCI8 para PHP</title>
  <para>
   Este ejemplo muestra lo básico del lenguaje de script D de DTrace.
   <example>
    <title><filename>user_oci8_probes.d</filename> para rasrear todos los Sondeos estáticos de OCI8 para PHP al nivel de usuario con 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>
   Este script usa la opción <literal>-Z</literal> para
   <filename>dtrace</filename>, permitiéndole que sea ejecutado cuando no exista un
   procesode PHP en ejecución. Si esta opción fuera omitida, el script
   terminaría inmediatamente cuando no se ejecutara PHP
   porque no sabe de la existencia de sondeos a ser
   monitorizados.
  </para>
  
  <para>
   En máquinas multi-CPU, el orden de los sondeos no parecerá ser
   sencuencial. Esto depende de cuál CPU estaba procesando los sondeos,
   y de cómo los hilos migran entre CPUs. Mostrar las marcas de tiempo de los sondeos
   atudará a reducir la confusión.
  </para>
  
  <para>
   El script rastrea todos los sondeos estáticos de OCI8 para PHP a nivel de usuario que apuntan
   a lo largo de la duración de un script de PHP en ejecución. Ejecute el script D:
   <informalexample>
    <programlisting>
<![CDATA[
# ./user_oci8_probes.d
]]>
    </programlisting>
   </informalexample>
  </para>
  
  <para>
   Ejecute un script o aplicación de PHP. El script D de monitorización
   generará cada argumento del sondeo mientras se lanza. Por ejemplo, un sencillo
   script de PHP que requiere una tabla podría producir la siguiente salida
   de rastreo:
   <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>
   Cuando la monitorización está completa, el script D puede terminarse con un
   <literal>^C</literal>.
  </para>
  
 </section>
 
 <section>
  <title>Véase también</title>
  <simplelist>
   <member><link linkend="features.dtrace">Rastreo dinámico de DTrace</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
-->