Trace et Log
/!\ CET ARTICLE EST EN COURS DE RÉDACTION /!\
Sommaire
Généralités
A partir de Thelia 1.5.2, les développeurs de plugins (et du cœur de Thelia) disposent d'un système de trace et de log qui remplace avantageusement les echo(), print() et autres print_r(). Ce système est largement inspiré de log4php, dont il reprend les principaux concepts.
Notez qu'il ne peut pas être utilisé dans vos templates HTML, mais uniquement dans le code PHP des plugins et du cœur de Thelia.
Ce système permet d'insérer à demeure dans le code des messages de plusieurs niveaux (6), qui peuvent être activés ou désactivés depuis le back-office de Thelia (Configuration -> Gestion des logs)
Logs et traces peuvent être dirigées vers une ou plusieurs destinations (fichier, console du navigateur, fenêtre popup, page HTML, etc.)
La classe Tlog est le point d'entrée du système de trace. Cette classe est incluse dans le moteur Thelia, il n'est pas nécessaire en général de l'inclure dans vos fichiers. Les fonctions de base sont accessibles via des méthodes statiques. La ligne ci-dessous permet par exemple de créer une trace de niveau DEBUG :
Tlog::debug("Ceci est une trace de debug. Objet:", $obj);
Les niveaux de trace
Tlog propose six niveaux de trace :
- TRACE: message plutôt de bas niveau (requêtes SQLs, contenus de variables, etc.)
- DEBUG: message plutôt fonctionnels, permettant de suivre le déroulement du code
- INFO: information
- WARNING: avertissement, sur un dysfonctionnement mineur.
- ERROR: erreurs non fatales
- FATAL: erreurs fatales
La classe Tlog propose une méthode statique pour chaque niveau de trace :
- Tlog::trace(...)
- Tlog::debug(...)
- Tlog::info(...)
- Tlog::warning(...)
- Tlog::error(...)
- Tlog::fatal(...)
Chaque méthode permet de passer un nombre de paramètres arbitraires. Les paramètres non scalaires (objets, tableaux, etc.) sont affichés à la manière de print_r().
Tlog::debug("Arguments: ", $args, ", requête:", $_REQUEST); Tlog::trace("Entrée boucle produit. Arguments: ", $args, ", requête:", $_REQUEST);
Dans l'exemple ci-dessus, avec la configuration de base, l'affichage obtenu sera :
122: DEBUG [boucles.php:boucleProduit()] {771} 2012-02-27 14:43:01: Entrée boucle produit. 123: TRACE [boucles.php:boucleProduit()] {772} 2012-02-27 14:43:01: Arguments: type="PRODUIT" id="84", requête:Array ( [url] => 84-base-pc-dsr-hb8000-500.html [fond] => produit [id_produit] => 84 [id_rubrique] => 47 )
Les traces sont activées par niveau, depuis le B.O. Thelia, ou avec les méthodes de configuration de la classe Tlog. L'activation d'un niveau rend visibles les traces de ce niveau et de tous les niveaux supérieurs. Par exemple, si le niveau DEBUG est activées, les traces de niveau DEBUG, INFO, WARNING, ERROR et FATAL seront visibles. Si le niveau ERROR est activé, seules les traces ERROR et FATAL seront visibles.
Configuration Programmatique
La classe Tlog propose un ensemble de méthodes permettant de configurer tous les aspects du système de log. C'est une façon pratique de conserver une trace de ce qui se passe dans un script appelé par cron, un plugin de paiement ou en général toute fonction qui ne doit pas utiliser la configuration commune définie dans le Back Office.
Ci-dessous un exemple de mise en œuvre:
// Se placer en mode Debug Tlog::instance()->set_niveau(Tlog::DEBUG); // Indiquer qu'on souhaite utiliser les destinations Fichier et Mail Tlog::instance()->set_destinations("TlogDestinationFichier;TlogDestinationMail"); // On limite les logs au fichier courant Tlog::instance()->set_files(basename(__FILE__)); // Pas de limitation sur IP Tlog::instance()->set_ip(''); // Définition du prefixe des logs Tlog::instance()->set_prefixe('[#NIVEAU #DATE #HEURE] '); // Indiquer le chemin du fichier de log, en configurant la destination TlogDestinationFichier Tlog::instance()->set_config( 'TlogDestinationFichier', TlogDestinationFichier::VAR_PATH_FICHIER, dirname(__FILE__)."/LOG.txt" );
Les destinations
Les destinations représentent les divers moyens de consigner et/ou de visualiser les logs. Chaque destination est configurable depuis le back-office (Configuration -> Gestion des logs)
Destinations de base
Les destinations suivantes sont automatiquement installées :
Fichier texte
Cette destination permet de consigner les logs dans un fichier texte sur votre serveur. Vous devez fournir un chemin d'accès absolu au fichier texte.
Le mode d'ouverture A (pour ajouter) ou E (pour écraser) permet de déterminer si vous souhaitez. En mode 'A', le fichier grossira indéfiniment. Veillez à le vider manuellement de temps en temps.
Console Javascript
Cette destination permet de consigner les logs dans la console Javascript de votre navigateur, si celui-ci implémente console.log().
Cette destination ne propose pas d'options de configuration.
Permet d'envoyer les log par e-mail à une ou plusieurs adresses. Attention, peut générer un fort traffic, ne pas utiliser sur une boutique en production.
Fenêtre Javascript
A Completer
Affichage direct dans la page, en texte brut
A Completer
Affichage direct dans la page, en HTML
A Completer
Créer vos propres destinations
Configuration générale
Les logs sont administrables depuis le Back Office de Thelia, Configuration -> Paramètres Système -> Gestion des logs