Présentation
Zend_Log
Programmer's Reference Guide

Rédacteurs (Writers)

Un rédacteur est un objet qui hérite de Zend_Log_Writer_Abstract. La responsabilité d'un rédacteur est d'enregistrer des données de log dans un stockage particulier.

Écrire vers un flux (stream)

Zend_Log_Writer_Stream envoie des données de log à un » flux de PHP.

Pour écrire des données de log dans le buffer d'affichage de PHP, il faut utiliser l'URL php://output. Alternativement, vous pouvez préférer envoyer des données de log directement à un flux comme STDERR (php://stderr).

  1. $redacteur = new Zend_Log_Writer_Stream('php://output');
  2. $logger = new Zend_Log($redacteur);
  3.  
  4. $logger->info("Message d'information");

Pour écrire des données dans un fichier, employer un des » Filesystem URLs:

  1. $redacteur = new Zend_Log_Writer_Stream('/chemin/vers/fichierdelog');
  2. $logger = new Zend_Log($redacteur);
  3.  
  4. $logger->info("Message d'information");
Par défaut, le flux s'ouvre en mode d'ajout ("a"). Pour l'ouvrir avec un mode différent, le constructeur de Zend_Log_Writer_Stream accepte un deuxième paramètre facultatif pour le mode.

Le constructeur de Zend_Log_Writer_Stream accepte également une ressource existante de flux :

  1. $flux = @fopen('/chemin/vers/fichierdelog', 'a', false);
  2. if (! $flux) {
  3.     throw new Exception('Impossible d\'ouvrir le flux');
  4. }
  5.  
  6. $redacteur = new Zend_Log_Writer_Stream($flux);
  7. $logger = new Zend_Log($redacteur);
  8.  
  9. $logger->info("Message d'information");
Vous ne pouvez pas indiquer le mode pour des ressources existantes de flux. Le faire entraînera une Zend_Log_Exception.

Écrire dans des bases de données

Zend_Log_Writer_Db écrit les informations de log dans une table de base de données en utilisant Zend_Db. Le constructeur de Zend_Log_Writer_Db reçoit une instance de Zend_Db_Adapter, un nom de table, et un plan de correspondance entre les colonnes de la base de données et les données élémentaires d'événement :

  1. $parametres = array ('host'     => '127.0.0.1',
  2.                  'username' => 'malory',
  3.                  'password' => '******',
  4.                  'dbname'   => 'camelot');
  5. $db = Zend_Db::factory('PDO_MYSQL', $parametres);
  6.  
  7. $planDeCorrespondance = array('niveau' => 'priority', 'msg' => 'message');
  8. $redacteur = new Zend_Log_Writer_Db($db,
  9.                                     'nom_de_la_table_de_log',
  10.                                     $planDeCorrespondance);
  11.  
  12. $logger = new Zend_Log($redacteur);
  13.  
  14. $logger->info("Message d'information");
L'exemple ci-dessus écrit une ligne unique de données de log dans la table appelée nom_de_la_table_de_log. La colonne de base de données appelée niveau reçoit le niveau de priorité et la colonne appelée msg reçoit le message de log.

Écrire vers Firebug

Zend_Log_Writer_Firebug envoie des données d'historisation vers la » console Firebug.

zend.wildfire.firebug.console.png

Toutes les données sont envoyées via le composant Zend_Wildfire_Channel_HttpHeaders qui utilise les en-têtes HTTP pour s'assurer que le contenu de la page n'est pas perturbé. Déboguer les requêtes AJAX qui requière du JSON "propre" ou un réponse XML est possible avec cette approche.

Éléments requis :

Example #1 Journaliser avec Zend_Controller_Front

  1. // Placez ceci dans votre fichier d'amorçage
  2. // avant de distribuer votre contrôleur frontal
  3. $writer = new Zend_Log_Writer_Firebug();
  4. $logger = new Zend_Log($writer);
  5.  
  6. // Utiliser ceci dans vos fichiers de modèles, vues et contrôleurs
  7. $logger->log('Ceci est un message de log !', Zend_Log::INFO);

Example #2 Journaliser sans Zend_Controller_Front

  1. $writer = new Zend_Log_Writer_Firebug();
  2. $logger = new Zend_Log($writer);
  3.  
  4. $request = new Zend_Controller_Request_Http();
  5. $response = new Zend_Controller_Response_Http();
  6. $channel = Zend_Wildfire_Channel_HttpHeaders::getInstance();
  7. $channel->setRequest($request);
  8. $channel->setResponse($response);
  9.  
  10. // Démarrer l'output buffering
  12.  
  13. // Maintenant vous pouvez appeler le logguer
  14. $logger->log('Ceci est un message de log !', Zend_Log::INFO);
  15.  
  16. // Envoi des données d'historisation vers le navigateur
  17. $channel->flush();
  18. $response->sendHeaders();

Paramétrer les styles pour les priorités

Les priorités incorporées et celles définies par l'utilisateur peuvent être stylisées avec la méthode setPriorityStyle().

  1. $logger->addPriority('FOO', 8);
  2. $writer->setPriorityStyle(8, 'TRACE');
  3. $logger->foo('Foo Message');

Le style par défaut pour les priorités définies par l'utilisateur peut être paramétrer avec la méthode setDefaultPriorityStyle().

  1. $writer->setDefaultPriorityStyle('TRACE');

Les styles supportés sont les suivants :

Styles d'historisation de Firebug
Style Description
LOG Affiche un message d'historisation basique
INFO Affiche un message d'historisation de type information
WARN Affiche un message d'historisation de type avertissement
ERROR Affiche un message d'historisation de type erreur (celui-ci incrémente le compteur d'erreur de Firebug)
TRACE Affiche un message d'historisation avec une trace extensible
EXCEPTION Affiche un message d'historisation de type erreur avec une trace extensible
TABLE Affiche un message d'historisation avec une table extensible

Préparer les données pour l'historisation

Toute variable PHP peut être journalisée avec les priorités incorporées, un formatage spécial est requis si vous utilisez des styles d'historisation un peu plus spécialisé.

Les styles LOG, INFO, WARN, ERROR et TRACE ne requièrent pas de formatage spécial.

Historisation des exceptions

Pour journaliser une Zend_Exception, fournissez simplement l'objet exception au logguer. Il n'y a pas d'importance sur la priorité ou le style que vous avez fourni puisque l'exception est automatiquement reconnue.

  1. $exception = new Zend_Exception('Test d\'exception');
  2. $logger->err($exception);

Historisation sous forme de tableau

Vous pouvez aussi journaliser des données en les formatant comme un tableau. Les colonnes sont automatiquement reconnues et la première ligne de données devient automatiquement la ligne d'en-têtes.

  1. $writer->setPriorityStyle(8, 'TABLE');
  2. $logger->addPriority('TABLE', 8);
  3.  
  4. $table = array('Ligne de résumé pour la table',
  5.                array(
  6.                    array('Colonne 1', 'Colonne 2'),
  7.                    array('Ligne 1 c 1',' Ligne 1 c 2'),
  8.                    array('Ligne 2 c 1',' Ligne 2 c 2')
  9.                )
  10.               );
  11. $logger->table($table);

Écrire vers un émail

Zend_Log_Writer_Mail va écrire les entrées du log dans un message émail en utilisant Zend_Mail. Le constructeur de Zend_Log_Writer_Mail requière un objet Zend_Mail et optionnellement un objet Zend_Layout.

Le cas d'utilisation principal de Zend_Log_Writer_Mail est la notification les développeurs, les administrateurs ou toute personne concernée, d'une erreur qui peut survenir dans des scripts. Zend_Log_Writer_Mail a été crée avec l'idée que si quelque chose ne tourne pas rond, une intervention humaine est nécessaire.

Voici un exemple d'utilisation basique :

  1. $mail = new Zend_Mail();
  2. $mail->setFrom('errors@example.org')
  3.      ->addTo('project_developers@example.org');
  4.  
  5. $writer = new Zend_Log_Writer_Mail($mail);
  6.  
  7. // Ecrit le sujet. Un résumé des erreurs est ajouté à la suite
  8. $writer->setSubjectPrependText('Errors with script foo.php');
  9.  
  10. // Limite uniquement au niveau Warning ou supérieur
  11. $writer->addFilter(Zend_Log::WARN);
  12.  
  13. $log = new Zend_Log();
  14. $log->addWriter($writer);
  15.  
  16. // Essai
  17. $log->error('unable to connect to database');
  18.  
  19. // A la fermeture, Zend_Mail::send() est inviqué et concernera
  20. // tous les logs passés dans le filtre.

Zend_Log_Writer_Mail utilisera un corps de message en texte plein (plain text) par défaut.

Le filtre est géré. Par exemple si le filtre est réglé sur Warnings, et que 2 évènements warnings et 5 évènements erreurs se produisent, alors 7 évènements seront envoyés.

Utilisation avec Zend_Layout

Une instance de Zend_Layout peut être utilisée pour générer du HTML qui fera partie de l'émail multipart. Si Zend_Layout est utilisé, Zend_Log_Writer_Mail considérera que le corps HTML du message sera la valeur du rendu de Zend_Layout.

En utilisant Zend_Log_Writer_Mail avec un objet Zend_Layout vous pouvez utiliser un formateur personnalisé grâce à setLayoutFormatter(). Si aucun formateur spécifique Zend_Layout n'est indiqué, le formateur en cours d'utilisation sera appelé. Voici un exemple :

  1. $mail = new Zend_Mail();
  2. $mail->setFrom('errors@example.org')
  3.      ->addTo('project_developers@example.org');
  4. // Nous ne spécifions pas le sujet du message dans l'objet Zend_Mail !
  5.  
  6. // Utilisons un simple objet Zend_Layout
  7. $layout = new Zend_Layout();
  8.  
  9. // Créons un formateur à base de listes
  10. $layoutFormatter = new Zend_Log_Formatter_Simple(
  11.     '<li>' . Zend_Log_Formatter_Simple::DEFAULT_FORMAT . '</li>'
  12. );
  13.  
  14. $writer = new Zend_Log_Writer_Mail($mail, $layout);
  15.  
  16. // Appliquons le formateur sur le rendu de Zend_Layout.
  17. $writer->setLayoutFormatter($layoutFormatter);
  18. $writer->setSubjectPrependText('Errors with script foo.php');
  19. $writer->addFilter(Zend_Log::WARN);
  20.  
  21. $log = new Zend_Log();
  22. $log->addWriter($writer);
  23.  
  24. // essai
  25. $log->error('unable to connect to database');
  26.  
  27. // A la fermeture, Zend_Mail::send() est inviqué et concernera
  28. // tous les logs passés dans le filtre.
  29. // l'email contiendra une partie "plain text", et une partie HTML

Ligne du sujet dynamique

La méthode setSubjectPrependText() est utilisée à la place de Zend_Mail::setSubject() pour que la ligne de sujet dans l'émail soit générée dynamiquement avant l'envoi de l'émail. Par exemple, si le texte indiqué est "Erreurs depuis ce script", le sujet de l'émail généré par Zend_Log_Writer_Mail avec 2 warnings et 5 errors sera alors "Erreurs depuis ce script (warn = 2; error = 5)". Si le sujet n'est pas indiqué via Zend_Log_Writer_Mail, la ligne de sujet de Zend_Mail, si il y en a une, sera utilisée.

Attention

Envoyer des rapports d'erreurs par emails peut être dangereux. Si votre système de surveillance d'erreurs n'est pas correct ou a un problème, vous risquez de vous retrouver inondé de tonnes d'emails en provenance de votre application.

A l'heure actuelle, il n'existe dans Zend_Log_Writer_Mail aucun système de limitation ou de contrôle du nombre ou de la fréquence d'envoi des emails. Si vous nécessitez un tel système, vous devrez l'implémenter vous-même.

Encore une fois, l'unique but de Zend_Log_Writer_Mail est la notification d'un humain au sujet d'une erreur. Si ce système est clairement contrôlé, alors il peut devenir un avantage très appréciable.

Ecrire dans lee journal du système

Zend_Log_Writer_Syslog écrit les rapports de log dans le journal système (syslog). En interne, il utilise les fonctions PHP openlog(), closelog(), et syslog().

Un cas d'utilisation intéressant de Zend_Log_Writer_Syslog est le cluster de machines. La fonctionnalité de journal système permet de faire en sorte que chaque machine enregistre dans un fichier de journal centralisé, ce qui simplifie l'administration.

Par défaut, tous les messages gérés sont préfixés par "Zend_Log". Si vous souhaitez changer ce nom, utilisez le constructeur ou l'accesseur:

  1. // A l'instanciation
  2. $writer = new Zend_Log_Writer_Syslog(array('application' => 'FooBar'));
  3.  
  4. // Plus tard:
  5. $writer->setApplicationName('BarBaz');

Le journal système vous aidera aussi à identifier les messages par types d'application ("facility"), les programmes de journalisation système vont générer des fichiers journaux différents en fonction des types d'application, ce qui là encore, peut aider dans l'administration.

Pour spécifier le type d'application, utilisez le constructeur ou l'accesseur. Cette option peut être l'une des constantes utilisées par openlog(), définies dans la page » du manuel de openlog().

  1. // A l'instanciation
  2. $writer = new Zend_Log_Writer_Syslog(array('facility' => LOG_AUTH));
  3.  
  4. // Plus tard
  5. $writer->setFacility(LOG_USER);

En utilisant l'objet de log, continuez d'utiliser les constantes de Zend_Log, elles vont être converties en leurs valeurs par syslog().

Ecrire vers le moniteur Zend Server

Zend_Log_Writer_ZendMonitor vous permet de journaliser des évènements via l'API de Zend Server. Vous pouvez alors aggréger des messages de journal pour l'application et tout son environnement, ceci vers un seul endroit. En interne, cet objet utilise simplement la fonction monitor_custom_event() issue de Zend Monitor.

Une caractéristique particulière de l'API Monitor est que vous pouvez spécifier n'importe quelle information dans le journal. Par exemple, journaliser une exception est possible en journalisant tout l'objet Exception d'un coup et pas juste son message. L'objet sera alors visible et analysable via le moniteur d'évènement de Zend Server.

Note: Zend Monitor doit être installé et activé
 Pour utiliser cet objet d'écriture, Zend Monitor doit petre installé et activé. Si ce n'est pas le cas, alors l'objet d'écriture agira de manière transparente et ne fera rien du tout.

Instancier l'objet d'écriture ZendMonitor est très simple:

  1. $writer = new Zend_Log_Writer_ZendMonitor();
  2. $log    = new Zend_Log($writer);

Ensuite, journalisez vos évènements comme d'habitude:

  1. $log->info('Voici un message');

Vous pouvez ajouter des informations à journaliser, passez les comme second paramètre:

  1. $log->info('Exception rencontrée', $e);

Ce deuxième paramètre peut être de type scalaire, objet, ou tableau; si vous souhaitez passer plusieurs informations d'un seul coup, utilisez un tableau.

  1. $log->info('Exception rencontrée', array(
  2.     'request'   => $request,
  3.     'exception' => $e,
  4. ));

Au sein de Zend Server, votre évènement est enregistré comme un "évènement personnalisé" (custom event). Depuis l'onglet "Monitor", sélectionnez le sous menu "Evènements"(Events), et utilisez ensuite le filtre "Personnalisé"(Custom).

zend.log.writers.zendmonitor-events.png

Evènements dans le récapitulatif Zend Server Monitor

Sur cette image, les deux premiers évènements listés sont des évènements personnalisés enregistré via l'objet d'écriture ZendMonitor. Cliquez alors sur un évènement pour voir toutes ses informations.

zend.log.writers.zendmonitor-event.png

Détails de l'évènement dans Zend Server Monitor

Cliquer sur le sous menu "Personnalisé"(Custom) montre les détails, c'est à dire ce que vous avez passé comme deuxième argument à la méthode de journalisation. Cet information est enregistrée sous la clé info; et vous pouvez voir que l'objet de requête a été enregistré dans cet exemple.

Note: Intégration avec Zend_Application
 Par défaut, les commandes zf.sh et zf.bat ajoute une configuration pour la ressource 'log' deZend_Application , elle inclut la configuration pour l'objet d'écriture du journal ZendMonitor. Aussi, le ErrorController utilise ce journal pour journaliser les exceptions de l'application.
Comme dit précedemment, si l'API de Zend Monitor API n'est pas détectée sur votre installation de PHP, alors le journal ne fera rien du tout.

Déraciner les rédacteurs

Le Zend_Log_Writer_Null est une souche qui écrit des données de log nulle part. Il est utile pour neutraliser le log ou déraciner le log pendant les essais :

  1. $redacteur = new Zend_Log_Writer_Null;
  2. $logger = new Zend_Log($redacteur);
  3.  
  4. // va nulle part
  5. $logger->info("Message d'information");

Tester avec un simulacre

Le Zend_Log_Writer_Mock est un rédacteur très simple qui enregistre les données brutes qu'il reçoit dans un tableau exposé comme propriété publique.

  1. $simulacre = new Zend_Log_Writer_Mock;
  2. $logger = new Zend_Log($simulacre);
  3.  
  4. $logger->info("Message d'information");
  5.  
  6. var_dump($mock->events[0]);
  7.  
  8. // Array
  9. // (
  10. //    [timestamp] => 2007-04-06T07:16:37-07:00
  11. //    [message] => Message d'information
  12. //    [priority] => 6
  13. //    [priorityName] => INFO
  14. // )

Pour effacer les événements notés dans le simulacre, il faut simplement réaliser $simulacre->events = array().

Additionner les rédacteurs

Il n'y a aucun objet composite de rédacteurs. Cependant, une instance d'enregistreur peut écrire vers tout nombre de rédacteurs. Pour faire ceci, employer la méthode addWriter() :

  1. $redacteur1 =
  2.     new Zend_Log_Writer_Stream('/chemin/vers/premier/fichierdelog');
  3. $redacteur2 =
  4.     new Zend_Log_Writer_Stream('/chemin/vers/second/fichierdelog');
  5.  
  6. $logger = new Zend_Log();
  7. $logger->addWriter($redacteur1);
  8. $logger->addWriter($redacteur2);
  9.  
  10. // va dans les 2 rédacteurs
  11. $logger->info("Message d'information");

Présentation
Zend_Log
Programmer's Reference Guide