repo_zf1/documentation/manual/es/module_specs/Zend_Db_Profiler.xml

<?xml version="1.0" encoding="UTF-8"?>
    <!-- EN-Revision: 19484 -->
    <!-- Reviewed: no -->
<sect1 id="zend.db.profiler" xmlns:xi="http://www.w3.org/2001/XInclude">

    <title>Zend_Db_Profiler</title>

    <sect2 id="zend.db.profiler.introduction">

        <title>Introducción</title>

        <para>
            <classname>Zend_Db_Profiler</classname>
            puede ser habilitado para
            Perfilar las consultas. Los Perfiles incluyen la consulta
            procesada
            por el adaptador como el tiempo as transcurrido en la ejecución de
            las
            consultas, permitiendo inspeccionar las consultas realizadas win
            necesidad de agregar
            información de depuración extra en el código de
            las clases. El uso avanzado también
            permite que el desarrollador
            filtre las consultas que desea perfilar.
        </para>

        <para>Habilite el perfilador pasando una directiva al al constructor
            del adaptador, o
            pidiendole al adaptador permitirlo más adelante.</para>

        <programlisting language="php"><![CDATA[
$params = array(
    'host'     => '127.0.0.1',
    'username' => 'webuser',
    'password' => 'xxxxxxxx',
    'dbname'   => 'test'
    'profiler' => true  // enciende el perfilador
                        // establezca false para deshabilitar (está deshabilitado por defecto)
);

$db = Zend_Db::factory('PDO_MYSQL', $params);

// apagar el perfilador:
$db->getProfiler()->setEnabled(false);

// encender el perfilador:
$db->getProfiler()->setEnabled(true);
]]></programlisting>

        <para>
            El valor de la opción '
            <property>profiler</property>
            ' es
            flexible. Es interpretada de distintas formas dependiendo del tipo.
            Normalmente,
            debería usar un valor booleano simple, pero otros tipos
            le permiten personalizar el
            comportamiento del perfilador.
        </para>

        <para>
            Un argumento booleano establece el perfilador como habilitado si
            el valor es
            <constant>TRUE</constant>
            , o deshabilitado si es
            <constant>FALSE</constant>
            . La clase del perfilador es el la
            clase de perfilador por defecto del adaptador,
            <classname>Zend_Db_Profiler</classname>
            .

        </para>

        <programlisting language="php"><![CDATA[
$params['profiler'] = true;
$db = Zend_Db::factory('PDO_MYSQL', $params);
]]></programlisting>

        <para>
            Una instancia del objeto perfilador hace que el adaptador use ese
            objeto. El tipo del
            objeto debe ser
            <classname>Zend_Db_Profiler</classname>
            o una subclase de este.
            Habilitar el perfilador se hace por separado.
        </para>

        <programlisting language="php"><![CDATA[
$profiler = MyProject_Db_Profiler();
$profiler->setEnabled(true);
$params['profiler'] = $profiler;
$db = Zend_Db::factory('PDO_MYSQL', $params);
]]></programlisting>

        <para>
            El argumento puede ser un array asociativo conteniendo algunas o
            todas las claves '
            <property>enabled</property>
            ',
            '
            <property>instance</property>
            ', y
            '
            <property>class</property>
            '. Las claves
            '
            <property>enabled</property>
            ' e
            '
            <property>instance</property>
            ' corresponden a los tipos
            booleano y la instancia documentada previamente. La clave
            '
            <property>class</property>
            ' es usada para nombrar la clase
            que usará el perfilador personalizado. La clase debe ser
            <classname>Zend_Db_Profiler</classname>
            o una subclase. La clase
            es instanciada sin argumentos de constructor. La opción
            '
            <property>class</property>
            ' es ignorada cuando la opción
            '
            <property>instance</property>
            ' está dada.
        </para>

        <programlisting language="php"><![CDATA[
$params['profiler'] = array(
    'enabled' => true,
    'class'   => 'MyProject_Db_Profiler'
);
$db = Zend_Db::factory('PDO_MYSQL', $params);
]]></programlisting>

        <para>
            Finalmente, el argumento puede ser un objeto de tipo
            <classname>Zend_Config</classname>
            conteniendo las
            propiedades, que son tratadas como las claves de array descritas
            recién.
            Por ejemplo, un archivo "
            <filename>config.ini</filename>
            " puede contener los
            siguientes datos:

        </para>

        <programlisting language="ini"><![CDATA[
[main]
db.profiler.class   = "MyProject_Db_Profiler"
db.profiler.enabled = true
]]></programlisting>

        <para>
            Esta configuración puede ser aplicada con el siguiente
            código
            <acronym>PHP</acronym>
            :
        </para>
        <programlisting language="php"><![CDATA[
$config = new Zend_Config_Ini('config.ini', 'main');
$params['profiler'] = $config->db->profiler;
$db = Zend_Db::factory('PDO_MYSQL', $params);
]]></programlisting>
        <para>
            La propiedad '
            <methodname>instance</methodname>
            ' debe ser
            usada como el siguiente ejemplo:
        </para>

        <programlisting language="php"><![CDATA[
$profiler = new MyProject_Db_Profiler();
$profiler->setEnabled(true);
$configData = array(
    'instance' => $profiler
    );
$config = new Zend_Config($configData);
$params['profiler'] = $config;
$db = Zend_Db::factory('PDO_MYSQL', $params);
]]></programlisting>

    </sect2>

    <sect2 id="zend.db.profiler.using">

        <title>Usando el Perfilador</title>

        <para>
            En este punto, obtenemos el perfilador usando el método
            <methodname>getProfiler()</methodname>
            del adaptador:
        </para>

        <programlisting language="php"><![CDATA[
$profiler = $db->getProfiler();
]]></programlisting>

        <para>
            Este retorna una instancia del objeto
            <classname>Zend_Db_Profiler</classname>
            . Con esta instancia, el
            desarrollador puede examinar las consultar usando una variedad
            de
            métodos:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>getTotalNumQueries()</methodname>
                    retorna el
                    número total de consultas que han sido perfiladas.
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>getTotalElapsedSecs()</methodname>
                    retorna el
                    número total de segundos transcurridos en todas las
                    consultas
                    perfiladas.
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>getQueryProfiles()</methodname>
                    retorna un array
                    con todos los perfiles de consultas.
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>getLastQueryProfile()</methodname>
                    retorna el
                    último perfil (más reciente) de consulta, independientemente
                    de si la
                    consulta ha terminado o no (si no lo ha hecho, la
                    hora de finalización será
                    nula).
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>clear()</methodname>
                    limpia los perfiles de
                    consulta de la pila.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            El valor de retorno de
            <methodname>getLastQueryProfile()</methodname>
            y elementos
            individuales de
            <methodname>getQueryProfiles()</methodname>
            son
            <classname>Zend_Db_Profiler_Query</classname>
            objetos, que
            proporcionan la capacidad para inspeccionar cada una de las
            consultas:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>getQuery()</methodname>
                    retorna el texto SQL de
                    la consulta. El texto
                    <acronym>SQL</acronym>
                    de una declaración preparada con
                    parámetros es el texto al tiempo en que la
                    consulta fué
                    preparada, por lo que contiene marcadores de posición, no
                    los valores
                    utilizados cuando la declaración se ejecuta.
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>getQueryParams()</methodname>
                    retorna un array
                    de los valores de los parámetros usados cuando se ejecuta
                    una
                    consulta preparada. Este incluye ambos parámetros y
                    argumentos vinculados al
                    método
                    <methodname>execute()</methodname>
                    de la declaración.
                    Las claves del array son las posiciones (basado en 1) o
                    indices de parámetros nombrados (string).
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>getElapsedSecs()</methodname>
                    returna el número
                    de segundos que tuvo la consulta al correr.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            La información que
            <classname>Zend_Db_Profiler</classname>
            provee
            es útil para perfilar cuellos de botella en aplicaciones, y para
            depurar consultas
            que han sido ejecutadas. Por instancia, para ver
            la consulta exacta que tuvo la última
            ejecución:
        </para>

        <programlisting language="php"><![CDATA[
$query = $profiler->getLastQueryProfile();

echo $query->getQuery();
]]></programlisting>

        <para>Tal vez una página se genera lentamente; use el perfilador para
            determinar primero el
            número total de segundos de todas las
            consultas, y luego recorrer paso a paso a través de
            las consultas
            para encontrar la más lenta:</para>

        <programlisting language="php"><![CDATA[
$totalTime    = $profiler->getTotalElapsedSecs();
$queryCount   = $profiler->getTotalNumQueries();
$longestTime  = 0;
$longestQuery = null;

foreach ($profiler->getQueryProfiles() as $query) {
    if ($query->getElapsedSecs() > $longestTime) {
        $longestTime  = $query->getElapsedSecs();
        $longestQuery = $query->getQuery();
    }
}

echo 'Ejecutadas ' . $queryCount . ' consultas en ' . $totalTime .
     ' segundos' . "\n";
echo 'Promedio de tiempo de consulta: ' . $totalTime / $queryCount .
     ' segundos' . "\n";
echo 'Consultas por segundo: ' . $queryCount / $totalTime . "\n";
echo 'Tardanza de la consulta más lenta: ' . $longestTime . "\n";
echo "Consulta más lenta: \n" . $longestQuery . "\n";
]]></programlisting>

    </sect2>

    <sect2 id="zend.db.profiler.advanced">

        <title>Uso avanzado del Perfilador</title>

        <para>
            Además de la inspección de consultas, el perfilador también le
            permite al desarrollador
            filtrar que consultas serán perfiladas. El
            siguiente método opera en una instancia de
            <classname>Zend_Db_Profiler</classname>
            :
        </para>

        <sect3 id="zend.db.profiler.advanced.filtertime">
            <title>Filtrar por tiempo transcurrido en consulta</title>

            <para>
                <methodname>setFilterElapsedSecs()</methodname>
                le permite al
                desarrolador establecer un tiempo mínimo antes de que una
                consulta se
                perfile. Para remover el filtro, pase un valor
                <constant>NULL</constant>
                al método.
            </para>

            <programlisting language="php"><![CDATA[
// Solo perfilar consultas que tardan más de 5 segundos:
$profiler->setFilterElapsedSecs(5);

// Perfilar todas las consultas sin importar el tiempo:
$profiler->setFilterElapsedSecs(null);
]]></programlisting>
        </sect3>

        <sect3 id="zend.db.profiler.advanced.filtertype">
            <title>Filtrar por tipo de consulta</title>

            <para>
                <methodname>setFilterQueryType()</methodname>
                le permite al
                desarrollador establecer que tipo de consulta serán perfiladas;
                para
                perfilar multiples tipos, use un "OR" lógico. Los tipos de
                consulta se definen como
                las siguientes constantes de
                <classname>Zend_Db_Profiler</classname>
                :
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        <constant>Zend_Db_Profiler::CONNECT</constant>
                        :
                        operaciones de conexión o selección de base de datos.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <constant>Zend_Db_Profiler::QUERY</constant>
                        :
                        consultas generales a la base de datos que no calzan con
                        otros tipos.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <constant>Zend_Db_Profiler::INSERT</constant>
                        :
                        cualquier consulta que agrega filas a la base de datos,
                        generalmente un
                        <acronym>SQL</acronym>
                        INSERT.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <constant>Zend_Db_Profiler::UPDATE</constant>
                        :
                        cualquier consulta que actualice registros existentes,
                        usualmente un
                        <acronym>SQL</acronym>
                        UPDATE.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <constant>Zend_Db_Profiler::DELETE</constant>
                        :
                        cualquier consulta que elimine datos existentes,
                        usualmente un
                        <acronym>SQL</acronym>
                        DELETE.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <constant>Zend_Db_Profiler::SELECT</constant>
                        :
                        cualquier consulta que retorne datos existentes,
                        usualmente un
                        <acronym>SQL</acronym>
                        SELECT.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <constant>Zend_Db_Profiler::TRANSACTION</constant>
                        :
                        cualquier operación transaccional, tal como iniciar una
                        transacción,
                        confirmar, o revertir.
                    </para>
                </listitem>
            </itemizedlist>

            <para>
                Asi como con
                <methodname>setFilterElapsedSecs()</methodname>
                ,
                puedes remover cualquier filtro existente pasando un
                <constant>NULL</constant>
                como único argumento.
            </para>

            <programlisting language="php"><![CDATA[
// Perfilar solo consultas SELECT
$profiler->setFilterQueryType(Zend_Db_Profiler::SELECT);

// Perfila consultas SELECT, INSERT, y UPDATE
$profiler->setFilterQueryType(Zend_Db_Profiler::SELECT |
                              Zend_Db_Profiler::INSERT |
                              Zend_Db_Profiler::UPDATE);

// Perfilar consultas DELETE
$profiler->setFilterQueryType(Zend_Db_Profiler::DELETE);

// Remover todos los filtros
$profiler->setFilterQueryType(null);
]]></programlisting>

        </sect3>

        <sect3 id="zend.db.profiler.advanced.getbytype">
            <title>Obtener perfiles por tipo de consulta</title>

            <para>
                Usando
                <methodname>setFilterQueryType()</methodname>
                puedes
                reducir los perfiles generados. Sin embargo, a veces puede ser
                más útil
                mantener todos los perfiles, pero ver sólo los que
                necesita en un determinado
                momento. Otra característica de
                <methodname>getQueryProfiles()</methodname>
                es que puede
                este filtrado al-vuelo, pasando un tipo de consulta(o una
                combinación
                lógica de tipos de consulta) en el primer; vea
                <xref linkend="zend.db.profiler.advanced.filtertype"/>
                para una
                lista las constantes de tipo de consulta.
            </para>

            <programlisting language="php"><![CDATA[
// Obtiene solo perfiles de consultas SELECT
$profiles = $profiler->getQueryProfiles(Zend_Db_Profiler::SELECT);

// Obtiene los perfiles de consultas SELECT, INSERT, y UPDATE
$profiles = $profiler->getQueryProfiles(Zend_Db_Profiler::SELECT |
                                        Zend_Db_Profiler::INSERT |
                                        Zend_Db_Profiler::UPDATE);

// Obtiene solo perfiles de consultas DELETE
$profiles = $profiler->getQueryProfiles(Zend_Db_Profiler::DELETE);
]]></programlisting>

        </sect3>

    </sect2>

    <sect2 id="zend.db.profiler.profilers">
        <title>Perfiladores Especializados</title>

        <para>
            Un Perfilador Especializado es un objeto que hereda de
            <classname>Zend_Db_Profiler</classname>
            . Los Perfiladores
            Especializados tratan la información de perfilado de maneras más
            especificas.
        </para>

        <xi:include href="Zend_Db_Profiler-Firebug.xml"/>

    </sect2>
</sect1>