Trace et Log

De TheliaDoc
Aller à : navigation, rechercher

/!\ CET ARTICLE EST EN COURS DE RÉDACTION /!\

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.

Erreur lors de la création de la miniature : Impossible d'enregistrer la vignette sur la destination

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().

Erreur lors de la création de la miniature : Impossible d'enregistrer la vignette sur la destination

Cette destination ne propose pas d'options de configuration.

E-mail

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

Erreur lors de la création de la miniature : Impossible d'enregistrer la vignette sur la destination