Log

1Présentation

Il est absolument nécessaire de pouvoir suivre l'exécution du code d'une application. Pendant le développement, ou quand on doit faire du débuggage, on veut savoir quelles sont les fonctions qui sont exécutées et dans quel ordre. Pour une application en production, on veut tracer toutes les erreurs, pour pouvoir les traiter spécifiquement.

Temma offre un mécanisme de logging basé sur l'objet \Temma\Base\Log.

2Log simple

La manière la plus simple d'écrire un message de log est d'appeler la méthode statique l(), en lui donnant en paramètre le message à écrire dans le fichier de log. Le message peut soit être une chaîne de caractères (qui sera affichée telle quelle), ou bien n'importe quelle donnée PHP (qui sera alors sérialisée avec la fonction print_r).

Voici quelques exemples :

\Temma\Base\Log::l("Message qui sera écrit systématiquement");
\Temma\Base\Log::l(['zone' => 'internal', 'idx' => 3]);

Ligne 1 : Le message textuel apparaîtra forcément dans le fichier de log.
Ligne 2 : Les données fournies en paramètre seront aussi forcément écrites dans le fichier de log, après avoir été converties dans une représentation textuelle.

Pour faciliter les appels à l'objet de log, on peut créer un alias :

use \Temma\Base\Log as TµLog;

TµLog::l("Message qui sera écrit systématiquement");

3Log avancé

Pour l'utiliser, il suffit d'appeler la méthode statique log(), en lui fournissant 3 paramètres (les deux premiers sont optionnels) :

Une classe de log, c'est-à-dire un label qui permettra au système de connaître le seuil de criticité au-delà duquel le message apparaîtra.
Un niveau de criticité, sous forme de chaîne de caractères courte, qui sert à indiquer s'il s'agit d'un simple message de débuggage, ou d'une information remontant une erreur critique.
Le texte du message de log. Cela peut être une chaîne de caractère (qui sera affichée telle quelle), ou bien n'importe quelle donnée PHP (qui sera alors sérialisée avec la fonction print_r).

Voici la liste des niveaux de criticités gérés par \Temma\Base\Log :

DEBUG : message de débuggage (criticité la plus faible)
INFO : message d'information (niveau par défaut des messages dont la criticité n'est pas précisée)
NOTE : notification ; message normal mais significatif (seuil par défaut)
WARN : message d'alerte ; l'application ne fonctionne pas normalement mais elle peut continuer à fonctionner
ERROR : message d'erreur ; l'application ne fonctionne pas normalement et elle doit s'arrêter
CRIT : message d'erreur critique ; l'application risque d'endommager son environnement (criticité la plus élevée)

Pour qu'un message soit écrit dans le fichier de log, il faut que son niveau de criticité soit supérieur ou égal au seuil prévu pour sa classe de log. Les classes de logs sont définies dans le fichiers de configuration etc/temma.php (voir Configuration).
Un message de log dont le niveau de criticité n'est pas défini est vu comme un message d'information (INFO).
Si la classe d'un message n'est pas définie, on lui affecte une classe par défaut, dont le seuil d'apparition est NOTE.

Voici quelques exemples :

use \Temma\Base\Log as TµLog;

TµLog::log("Message de log utilisant les seuils par défaut.");
TµLog::log('NOTE', "Notice liée à la classe par défaut.");
TµLog::log('myapp', 'DEBUG', "Ceci est un message de débug.");
TµLog::log('data', 'INFO', ['zone' => 'internal', 'idx' => 3]);

Ligne 1 : On crée un alias pour faciliter l'appel à l'objet de log.
Ligne 3 : Ce message a une criticité par défaut (INFO), et une classe par défaut (default, dont le seuil est NOTE). La criticité étant moins importante que le seuil, le message n'apparaîtra pas.
Ligne 4 : Ce message a la criticité NOTE, et une classe par défaut (default, dont le seuil est NOTE). La criticité étant égale au seuil, le message apparaîtra.
Ligne 5 : Ce message a la criticité DEBUG (la moins importante), et la classe myapp. Si le seuil de cette classe est défini à DEBUG, le message apparaîtra.
Ligne 6 : Ce message a la criticité INFO, et la classe data. Si le seuil de cette classe est défini à INFO ou à DEBUG, le message apparaîtra. Le message étant un tableau associatif, le système de log le fera apparaître après conversion en texte.

4Contrôle du log

Il est possible de modifier le comportement du log, en appelant des méthodes statiques de l'objet \Temma\Base\Log :

disable() pour désactiver le log.
enable() pour réactiver le log.
logToStdOut() pour activer l'écriture du log sur la sortie standard. Elle peut prendre un paramètre boolean optionnel (true pour activer, false pour désactiver).
logToStdErr() pour activer l'écriture du log sur la sortie d'erreur. Elle peut prendre un paramètre boolean optionnel (true pour activer, false pour désactiver).
setLogFile($path) pour redéfinir le chemin vers le fichier de log.

En temps normal, il n'y a pas besoin de faire appel à ces méthodes, le système de log étant initialisé par le framework.