documentation/manual/es/module_specs/Zend_Db_Profiler.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- EN-Revision: 20115 -->
   3     <!-- Reviewed: no -->
   4 <sect1 id="zend.db.profiler" xmlns:xi="http://www.w3.org/2001/XInclude">
   5
   6     <title>Zend_Db_Profiler</title>
   7
   8     <sect2 id="zend.db.profiler.introduction">
   9
  10         <title>Introducción</title>
  11
  12         <para>
  13             <classname>Zend_Db_Profiler</classname> puede ser habilitado para
  14             Perfilar las consultas. Los Perfiles incluyen la consulta procesada
  15             por el adaptador como el tiempo as transcurrido en la ejecución de
  16             las consultas, permitiendo inspeccionar las consultas realizadas win
  17             necesidad de agregar información de depuración extra en el código de
  18             las clases. El uso avanzado también permite que el desarrollador
  19             filtre las consultas que desea perfilar. </para>
  20
  21         <para>Habilite el perfilador pasando una directiva al al constructor del
  22             adaptador, o pidiendole al adaptador permitirlo más adelante.</para>
  23
  24         <programlisting language="php"><![CDATA[
  25 $params = array(
  26     'host'     => '127.0.0.1',
  27     'username' => 'webuser',
  28     'password' => 'xxxxxxxx',
  29     'dbname'   => 'test'
  30     'profiler' => true  // enciende el perfilador
  31                         // establezca false para deshabilitar (está deshabilitado por defecto)
  32 );
  33
  34 $db = Zend_Db::factory('PDO_MYSQL', $params);
  35
  36 // apagar el perfilador:
  37 $db->getProfiler()->setEnabled(false);
  38
  39 // encender el perfilador:
  40 $db->getProfiler()->setEnabled(true);
  41 ]]></programlisting>
  42
  43         <para> El valor de la opción ' <property>profiler</property> ' es
  44             flexible. Es interpretada de distintas formas dependiendo del tipo.
  45             Normalmente, debería usar un valor booleano simple, pero otros tipos
  46             le permiten personalizar el comportamiento del perfilador. </para>
  47
  48         <para> Un argumento booleano establece el perfilador como habilitado si
  49             el valor es <constant>TRUE</constant> , o deshabilitado si es
  50                 <constant>FALSE</constant> . La clase del perfilador es el la
  51             clase de perfilador por defecto del adaptador,
  52                 <classname>Zend_Db_Profiler</classname> . </para>
  53
  54         <programlisting language="php"><![CDATA[
  55 $params['profiler'] = true;
  56 $db = Zend_Db::factory('PDO_MYSQL', $params);
  57 ]]></programlisting>
  58
  59         <para> Una instancia del objeto perfilador hace que el adaptador use ese
  60             objeto. El tipo del objeto debe ser
  61                 <classname>Zend_Db_Profiler</classname> o una subclase de este.
  62             Habilitar el perfilador se hace por separado. </para>
  63
  64         <programlisting language="php"><![CDATA[
  65 $profiler = MyProject_Db_Profiler();
  66 $profiler->setEnabled(true);
  67 $params['profiler'] = $profiler;
  68 $db = Zend_Db::factory('PDO_MYSQL', $params);
  69 ]]></programlisting>
  70
  71         <para> El argumento puede ser un array asociativo conteniendo algunas o
  72             todas las claves ' <property>enabled</property> ', '
  73                 <property>instance</property> ', y ' <property>class</property>
  74             '. Las claves ' <property>enabled</property> ' e '
  75                 <property>instance</property> ' corresponden a los tipos
  76             booleano y la instancia documentada previamente. La clave '
  77                 <property>class</property> ' es usada para nombrar la clase que
  78             usará el perfilador personalizado. La clase debe ser
  79                 <classname>Zend_Db_Profiler</classname> o una subclase. La clase
  80             es instanciada sin argumentos de constructor. La opción '
  81                 <property>class</property> ' es ignorada cuando la opción '
  82                 <property>instance</property> ' está dada. </para>
  83
  84         <programlisting language="php"><![CDATA[
  85 $params['profiler'] = array(
  86     'enabled' => true,
  87     'class'   => 'MyProject_Db_Profiler'
  88 );
  89 $db = Zend_Db::factory('PDO_MYSQL', $params);
  90 ]]></programlisting>
  91
  92         <para> Finalmente, el argumento puede ser un objeto de tipo
  93                 <classname>Zend_Config</classname> conteniendo las propiedades,
  94             que son tratadas como las claves de array descritas recién. Por
  95             ejemplo, un archivo " <filename>config.ini</filename> " puede
  96             contener los siguientes datos: </para>
  97
  98         <programlisting language="ini"><![CDATA[
  99 [main]
 100 db.profiler.class   = "MyProject_Db_Profiler"
 101 db.profiler.enabled = true
 102 ]]></programlisting>
 103
 104         <para> Esta configuración puede ser aplicada con el siguiente código
 105                 <acronym>PHP</acronym> : </para>
 106         <programlisting language="php"><![CDATA[
 107 $config = new Zend_Config_Ini('config.ini', 'main');
 108 $params['profiler'] = $config->db->profiler;
 109 $db = Zend_Db::factory('PDO_MYSQL', $params);
 110 ]]></programlisting>
 111         <para> La propiedad ' <methodname>instance</methodname> ' debe ser usada
 112             como el siguiente ejemplo: </para>
 113
 114         <programlisting language="php"><![CDATA[
 115 $profiler = new MyProject_Db_Profiler();
 116 $profiler->setEnabled(true);
 117 $configData = array(
 118     'instance' => $profiler
 119     );
 120 $config = new Zend_Config($configData);
 121 $params['profiler'] = $config;
 122 $db = Zend_Db::factory('PDO_MYSQL', $params);
 123 ]]></programlisting>
 124
 125     </sect2>
 126
 127     <sect2 id="zend.db.profiler.using">
 128
 129         <title>Usando el Perfilador</title>
 130
 131         <para> En este punto, obtenemos el perfilador usando el método
 132                 <methodname>getProfiler()</methodname> del adaptador: </para>
 133
 134         <programlisting language="php"><![CDATA[
 135 $profiler = $db->getProfiler();
 136 ]]></programlisting>
 137
 138         <para> Este retorna una instancia del objeto
 139                 <classname>Zend_Db_Profiler</classname> . Con esta instancia, el
 140             desarrollador puede examinar las consultar usando una variedad de
 141             métodos: </para>
 142
 143         <itemizedlist>
 144             <listitem>
 145                 <para>
 146                     <methodname>getTotalNumQueries()</methodname> retorna el
 147                     número total de consultas que han sido perfiladas. </para>
 148             </listitem>
 149             <listitem>
 150                 <para>
 151                     <methodname>getTotalElapsedSecs()</methodname> retorna el
 152                     número total de segundos transcurridos en todas las
 153                     consultas perfiladas. </para>
 154             </listitem>
 155             <listitem>
 156                 <para>
 157                     <methodname>getQueryProfiles()</methodname> retorna un array
 158                     con todos los perfiles de consultas. </para>
 159             </listitem>
 160             <listitem>
 161                 <para>
 162                     <methodname>getLastQueryProfile()</methodname> retorna el
 163                     último perfil (más reciente) de consulta, independientemente
 164                     de si la consulta ha terminado o no (si no lo ha hecho, la
 165                     hora de finalización será <constant>NULL</constant>). </para>
 166             </listitem>
 167             <listitem>
 168                 <para>
 169                     <methodname>clear()</methodname> limpia los perfiles de
 170                     consulta de la pila. </para>
 171             </listitem>
 172         </itemizedlist>
 173
 174         <para> El valor de retorno de
 175                 <methodname>getLastQueryProfile()</methodname> y elementos
 176             individuales de <methodname>getQueryProfiles()</methodname> son
 177                 <classname>Zend_Db_Profiler_Query</classname> objetos, que
 178             proporcionan la capacidad para inspeccionar cada una de las
 179             consultas: </para>
 180
 181         <itemizedlist>
 182             <listitem>
 183                 <para>
 184                     <methodname>getQuery()</methodname> retorna el texto SQL de
 185                     la consulta. El texto <acronym>SQL</acronym> de una
 186                     declaración preparada con parámetros es el texto al tiempo
 187                     en que la consulta fué preparada, por lo que contiene
 188                     marcadores de posición, no los valores utilizados cuando la
 189                     declaración se ejecuta. </para>
 190             </listitem>
 191             <listitem>
 192                 <para>
 193                     <methodname>getQueryParams()</methodname> retorna un array
 194                     de los valores de los parámetros usados cuando se ejecuta
 195                     una consulta preparada. Este incluye ambos parámetros y
 196                     argumentos vinculados al método
 197                         <methodname>execute()</methodname> de la declaración.
 198                     Las claves del array son las posiciones (basado en 1) o
 199                     indices de parámetros nombrados (string). </para>
 200             </listitem>
 201             <listitem>
 202                 <para>
 203                     <methodname>getElapsedSecs()</methodname> returna el número
 204                     de segundos que tuvo la consulta al correr. </para>
 205             </listitem>
 206         </itemizedlist>
 207
 208         <para> La información que <classname>Zend_Db_Profiler</classname> provee
 209             es útil para perfilar cuellos de botella en aplicaciones, y para
 210             depurar consultas que han sido ejecutadas. Por instancia, para ver
 211             la consulta exacta que tuvo la última ejecución: </para>
 212
 213         <programlisting language="php"><![CDATA[
 214 $query = $profiler->getLastQueryProfile();
 215
 216 echo $query->getQuery();
 217 ]]></programlisting>
 218
 219         <para>Tal vez una página se genera lentamente; use el perfilador para
 220             determinar primero el número total de segundos de todas las
 221             consultas, y luego recorrer paso a paso a través de las consultas
 222             para encontrar la más lenta:</para>
 223
 224         <programlisting language="php"><![CDATA[
 225 $totalTime    = $profiler->getTotalElapsedSecs();
 226 $queryCount   = $profiler->getTotalNumQueries();
 227 $longestTime  = 0;
 228 $longestQuery = null;
 229
 230 foreach ($profiler->getQueryProfiles() as $query) {
 231     if ($query->getElapsedSecs() > $longestTime) {
 232         $longestTime  = $query->getElapsedSecs();
 233         $longestQuery = $query->getQuery();
 234     }
 235 }
 236
 237 echo 'Ejecutadas ' . $queryCount . ' consultas en ' . $totalTime .
 238      ' segundos' . "\n";
 239 echo 'Promedio de tiempo de consulta: ' . $totalTime / $queryCount .
 240      ' segundos' . "\n";
 241 echo 'Consultas por segundo: ' . $queryCount / $totalTime . "\n";
 242 echo 'Tardanza de la consulta más lenta: ' . $longestTime . "\n";
 243 echo "Consulta más lenta: \n" . $longestQuery . "\n";
 244 ]]></programlisting>
 245
 246     </sect2>
 247
 248     <sect2 id="zend.db.profiler.advanced">
 249
 250         <title>Uso avanzado del Perfilador</title>
 251
 252         <para> Además de la inspección de consultas, el perfilador también le
 253             permite al desarrollador filtrar que consultas serán perfiladas. El
 254             siguiente método opera en una instancia de
 255                 <classname>Zend_Db_Profiler</classname> : </para>
 256
 257         <sect3 id="zend.db.profiler.advanced.filtertime">
 258             <title>Filtrar por tiempo transcurrido en consulta</title>
 259
 260             <para>
 261                 <methodname>setFilterElapsedSecs()</methodname> le permite al
 262                 desarrolador establecer un tiempo mínimo antes de que una
 263                 consulta se perfile. Para remover el filtro, pase un valor
 264                     <constant>NULL</constant> al método. </para>
 265
 266             <programlisting language="php"><![CDATA[
 267 // Solo perfilar consultas que tardan más de 5 segundos:
 268 $profiler->setFilterElapsedSecs(5);
 269
 270 // Perfilar todas las consultas sin importar el tiempo:
 271 $profiler->setFilterElapsedSecs(null);
 272 ]]></programlisting>
 273         </sect3>
 274
 275         <sect3 id="zend.db.profiler.advanced.filtertype">
 276             <title>Filtrar por tipo de consulta</title>
 277
 278             <para>
 279                 <methodname>setFilterQueryType()</methodname> le permite al
 280                 desarrollador establecer que tipo de consulta serán perfiladas;
 281                 para perfilar multiples tipos, use un "OR" lógico. Los tipos de
 282                 consulta se definen como las siguientes constantes de
 283                     <classname>Zend_Db_Profiler</classname> : </para>
 284
 285             <itemizedlist>
 286                 <listitem>
 287                     <para>
 288                         <constant>Zend_Db_Profiler::CONNECT</constant> :
 289                         operaciones de conexión o selección de base de datos.
 290                     </para>
 291                 </listitem>
 292                 <listitem>
 293                     <para>
 294                         <constant>Zend_Db_Profiler::QUERY</constant> : consultas
 295                         generales a la base de datos que no calzan con otros
 296                         tipos. </para>
 297                 </listitem>
 298                 <listitem>
 299                     <para>
 300                         <constant>Zend_Db_Profiler::INSERT</constant> :
 301                         cualquier consulta que agrega filas a la base de datos,
 302                         generalmente un <acronym>SQL</acronym> INSERT. </para>
 303                 </listitem>
 304                 <listitem>
 305                     <para>
 306                         <constant>Zend_Db_Profiler::UPDATE</constant> :
 307                         cualquier consulta que actualice registros existentes,
 308                         usualmente un <acronym>SQL</acronym> UPDATE. </para>
 309                 </listitem>
 310                 <listitem>
 311                     <para>
 312                         <constant>Zend_Db_Profiler::DELETE</constant> :
 313                         cualquier consulta que elimine datos existentes,
 314                         usualmente un <acronym>SQL</acronym> DELETE. </para>
 315                 </listitem>
 316                 <listitem>
 317                     <para>
 318                         <constant>Zend_Db_Profiler::SELECT</constant> :
 319                         cualquier consulta que retorne datos existentes,
 320                         usualmente un <acronym>SQL</acronym> SELECT. </para>
 321                 </listitem>
 322                 <listitem>
 323                     <para>
 324                         <constant>Zend_Db_Profiler::TRANSACTION</constant> :
 325                         cualquier operación transaccional, tal como iniciar una
 326                         transacción, confirmar, o revertir. </para>
 327                 </listitem>
 328             </itemizedlist>
 329
 330             <para> Asi como con <methodname>setFilterElapsedSecs()</methodname>
 331                 , puedes remover cualquier filtro existente pasando un
 332                     <constant>NULL</constant> como único argumento. </para>
 333
 334             <programlisting language="php"><![CDATA[
 335 // Perfilar solo consultas SELECT
 336 $profiler->setFilterQueryType(Zend_Db_Profiler::SELECT);
 337
 338 // Perfila consultas SELECT, INSERT, y UPDATE
 339 $profiler->setFilterQueryType(Zend_Db_Profiler::SELECT |
 340                               Zend_Db_Profiler::INSERT |
 341                               Zend_Db_Profiler::UPDATE);
 342
 343 // Perfilar consultas DELETE
 344 $profiler->setFilterQueryType(Zend_Db_Profiler::DELETE);
 345
 346 // Remover todos los filtros
 347 $profiler->setFilterQueryType(null);
 348 ]]></programlisting>
 349
 350         </sect3>
 351
 352         <sect3 id="zend.db.profiler.advanced.getbytype">
 353             <title>Obtener perfiles por tipo de consulta</title>
 354
 355             <para> Usando <methodname>setFilterQueryType()</methodname> puedes
 356                 reducir los perfiles generados. Sin embargo, a veces puede ser
 357                 más útil mantener todos los perfiles, pero ver sólo los que
 358                 necesita en un determinado momento. Otra característica de
 359                     <methodname>getQueryProfiles()</methodname> es que puede
 360                 este filtrado al-vuelo, pasando un tipo de consulta(o una
 361                 combinación lógica de tipos de consulta) en el primer; vea <xref
 362                     linkend="zend.db.profiler.advanced.filtertype"/> para una
 363                 lista las constantes de tipo de consulta. </para>
 364
 365             <programlisting language="php"><![CDATA[
 366 // Obtiene solo perfiles de consultas SELECT
 367 $profiles = $profiler->getQueryProfiles(Zend_Db_Profiler::SELECT);
 368
 369 // Obtiene los perfiles de consultas SELECT, INSERT, y UPDATE
 370 $profiles = $profiler->getQueryProfiles(Zend_Db_Profiler::SELECT |
 371                                         Zend_Db_Profiler::INSERT |
 372                                         Zend_Db_Profiler::UPDATE);
 373
 374 // Obtiene solo perfiles de consultas DELETE
 375 $profiles = $profiler->getQueryProfiles(Zend_Db_Profiler::DELETE);
 376 ]]></programlisting>
 377
 378         </sect3>
 379
 380     </sect2>
 381
 382     <sect2 id="zend.db.profiler.profilers">
 383         <title>Perfiladores Especializados</title>
 384
 385         <para> Un Perfilador Especializado es un objeto que hereda de
 386                 <classname>Zend_Db_Profiler</classname> . Los Perfiladores
 387             Especializados tratan la información de perfilado de maneras más
 388             especificas. </para>
 389
 390         <xi:include href="Zend_Db_Profiler-Firebug.xml"/>
 391
 392     </sect2>
 393 </sect1>