repo_zf1/documentation/manual/fr/module_specs/Zend_Log-Overview.xml

<!-- EN-Revision: 13840 -->
<sect1 id="zend.log.overview">
    <title>Présentation</title>

    <para><classname>Zend_Log</classname> est un composant destiné à tous les usages du log. Il supporte l'écriture multiple
    centralisée, formate les messages envoyés vers les logs, et les filtre. Ces fonctions sont divisées en objets
    suivants : <itemizedlist>
            <listitem>
                <para>Un enregistreur (instance de <classname>Zend_Log</classname>) est l'objet que votre application emploie le
                plus. Vous pouvez avoir autant d'objets d'enregistreur que vous voulez ; ils n'agissent pas l'un sur
                l'autre. Un objet enregistreur doit contenir au moins un rédacteur (Writer), et peut facultativement
                contenir un ou plusieurs filtres.</para>
            </listitem>

            <listitem>
                <para>Un rédacteur [ou Writer] (hérite de <classname>Zend_Log_Writer_Abstract</classname>) est responsable de la
                sauvegarde des données dans le stockage.</para>
            </listitem>

            <listitem>
                <para>Un filtre (implémente <classname>Zend_Log_Filter_Interface</classname>) bloque des données de log ne devant
                pas être écrites. Un filtre peut être appliqué à un rédacteur en particulier, ou à tous les rédacteurs.
                Dans l'un ou l'autre cas, les filtres peuvent être enchaînés.</para>
            </listitem>

            <listitem>
                <para>Un formateur (implémente <classname>Zend_Log_Formatter_Interface</classname>) peut formater les données de
                log avant qu'elles soient écrites par un rédacteur. Chaque rédacteur a exactement un formateur.</para>
            </listitem>
        </itemizedlist></para>

    <sect2 id="zend.log.overview.creating-a-logger">
        <title>Créer un log</title>

        <para>Pour commencer à enregistrer, instanciez un rédacteur et passez le à une instance d'un enregistreur :
        <programlisting role="php"><![CDATA[
$logger = new Zend_Log();
$redacteur = new Zend_Log_Writer_Stream('php://output');

$logger->addWriter($redacteur);
]]></programlisting> Il est important de noter que l'enregistreur doit avoir au moins un
        rédacteur. Vous pouvez ajouter tout nombre de rédacteurs en utilisant la méthode
        <code>addWriter()</code>.</para>

        <para>Alternativement, vous pouvez passer un rédacteur directement au constructeur de l'enregistreur :
        <programlisting role="php"><![CDATA[
$logger = new Zend_Log(new Zend_Log_Writer_Stream('php://output'));
]]></programlisting>
        L'enregistreur est maintenant prêt à être utilisé.</para>
    </sect2>

    <sect2 id="zend.log.overview.logging-messages">
        <title>Messages de logs</title>

        <para>Pour enregistrer un message, appelez la méthode <code>log()</code> de l'instance de l'enregistreur et
        passez lui le message avec son niveau de priorité. <programlisting role="php"><![CDATA[
$logger->log("Message d'information", Zend_Log::INFO);
]]></programlisting>
        Le premier paramètre de la méthode <code>log()</code> est une chaîne <code>message</code> et le deuxième
        paramètre est une <code>priority</code> fourni en nombre entier. La priorité doit être l'une des priorités
        identifiées par l'instance de l'enregistreur. Ceci est expliqué dans la prochaine section.</para>

        <para>Un raccourci est également disponible. Au lieu d'appeler la méthode <code>log()</code>, vous pouvez
        appeler une méthode par le même nom que la priorité : <programlisting role="php"><![CDATA[
$logger->log("Message d'information", Zend_Log::INFO);
$logger->info("Message d'information");

$logger->log("Message d'urgence", Zend_Log::EMERG);
$logger->emerg("Message d'urgence");
]]></programlisting></para>
    </sect2>

    <sect2 id="zend.log.overview.destroying-a-logger">
        <title>Détruire un log</title>

        <para>Si l'objet enregistreur n'est plus nécessaire, vous devez affectez la valeur <code>null</code> à la
        variable le contenant pour le détruire. Ceci appellera automatiquement la méthode <code>shutdown()</code> de
        chaque rédacteur avant que l'objet enregistreur ne soit détruit : <programlisting role="php"><![CDATA[
$logger = null;
]]></programlisting>
        Explicitement détruire le log de cette façon est facultatif et est exécuté automatiquement à la fermeture de
        PHP.</para>
    </sect2>

    <sect2 id="zend.log.overview.builtin-priorities">
        <title>Utiliser les priorités intégrées</title>

        <para>La classe de <classname>Zend_Log</classname> définit les priorités suivantes : <programlisting role="php"><![CDATA[
EMERG   = 0;  // Urgence : le système est inutilisable
ALERT   = 1;  // Alerte: une mesure corrective
              // doit être prise immédiatement
CRIT    = 2;  // Critique : états critiques
ERR     = 3;  // Erreur: états d'erreur
WARN    = 4;  // Avertissement: états d'avertissement
NOTICE  = 5;  // Notice: normal mais état significatif
INFO    = 6;  // Information: messages d'informations
DEBUG   = 7;  // Debug: messages de déboguages
]]></programlisting> Ces priorités sont toujours disponibles, et une méthode de convenance de même nom est
        disponible pour chacun.</para>

        <para>Les priorités ne sont pas arbitraires. Elles viennent du protocole BSD <code>syslog</code>, qui est décrit
        dans la <ulink url="http://tools.ietf.org/html/rfc3164">RFC-3164</ulink>. Les noms et les niveaux de priorité
        correspondants sont également compatibles avec un autre système de log de PHP, <ulink
        url="http://pear.php.net/package/log">PEAR Log</ulink>, ce qui favorise l'interopérabilité entre lui et
        <classname>Zend_Log</classname>.</para>

        <para>Les numéros de priorité descendent par ordre d'importance. <code>EMERG</code> (0) est la priorité la plus
        importante. <code>DEBUG</code> (7) est la priorité la moins importante des priorités intégrées. Vous pouvez
        définir des priorités d'importance inférieure que <code>DEBUG</code>. En choisissant la priorité pour votre
        message de log, faîtes attention à cette hiérarchie prioritaire et choisissez convenablement.</para>
    </sect2>

    <sect2 id="zend.log.overview.user-defined-priorities">
        <title>Ajouter ses propres priorités</title>

        <para>Des priorités définies par l'utilisateur peuvent être ajoutées en cours d'exécution en utilisant la
        méthode de <code>addPriority()</code> de l'enregistreur : <programlisting role="php"><![CDATA[
$logger->addPriority('ESSAI', 8);
]]></programlisting>
        L'extrait ci-dessus crée une nouvelle priorité, <code>ESSAI</code>, dont la valeur est <code>8</code>. La
        nouvelle priorité est alors disponible pour l'enregistreur : <programlisting role="php"><![CDATA[
$logger->log("Message d'essai", 8);
$logger->essai("Message d'essai");
]]></programlisting> Les nouvelles priorités ne peuvent pas surcharger celles
        existantes.</para>
    </sect2>

    <sect2 id="zend.log.overview.understanding-fields">
        <title>Comprendre les événements de logs</title>

        <para>Quand vous appelez la méthode <code>log()</code> ou l'un de ses raccourcis, un événement de log est créé.
        C'est simplement un tableau associatif avec des données décrivant l'événement qui est envoyé aux rédacteurs. Les
        clés suivantes sont toujours créées dans ce tableau : <code>timestamp</code>, <code>message</code>,
        <code>priority</code>, et <code>priorityName</code>.</para>

        <para>La création du tableau <code>event</code> est complètement transparente. Cependant, la connaissance du
        tableau d'événement est exigée pour ajouter un élément qui n'existerait pas dans le réglage par défaut
        ci-dessus.</para>

        <para>Pour ajouter un nouvel élément à chaque futur événement, appeler la méthode <code>setEventItem()</code> en
        donnant une clé et une valeur : <programlisting role="php"><![CDATA[
$logger->setEventItem('pid', getmypid());
]]></programlisting>
        L'exemple ci-dessus place un nouvel élément nommé <code>pid</code> et lui donne comme valeur le PID du processus
        courant. Une fois qu'un nouvel élément a été placé, il est disponible automatiquement pour tous les rédacteurs
        avec toutes les autres données d'événement pendant l'enregistrement. Un élément peut être surchargé à tout
        moment en appelant une nouvelle fois la méthode <code>setEventItem()</code>.</para>

        <para>Le réglage d'un nouvel élément d'événement avec <code>setEventItem()</code> entraîne que le nouvel élément
        sera envoyé à tous les rédacteurs de l'enregistreur. Cependant, ceci ne garantit pas que les rédacteurs
        utilisent réellement l'élément. C'est parce que les rédacteurs ne sauront pas quoi faire avec lui à moins qu'un
        objet formateur soit informé du nouvel élément. Veuillez vous reporter à la section sur des formateurs pour en
        apprendre davantage.</para>
    </sect2>
</sect1>