Documentation:Doc Outils Log User

Objectif

GFLOG est un outil qui permet aux programmeurs de générer un ensemble de rapport de log pour leurs code en C++.
GFLOG est un composant du projet GAMEFORGE et propose des éléments d'audite et de débogage.

Il est important de pouvoir localiser une erreur ou un dysfonctionnement dans le code d'une application. Avec l'outil GFLOG, vous pouvez activer ou modifier les logs sans avoir à recompiler l'ensemble de l'application.
Ainsi GFLog propose non seulement des éléments de débogage mais aussi une journalisation des évenements
Basé sur une notion de loggers hiérarchiques, il est possible de sélectionner le niveau de message qui sera inscrit dans le rapport de log.

GFLOG a été créé dans le but précis de simplifier le developpement et le débogage des applications du projet.

Présentation

Ce document a pour but de décrire l'architecture de l'outil GFLog. Il est composé de 3 éléments principaux : les loggers, les filtres et les flux de sortie.

• Logger : Définissent le type de message.
• Filtre : Niveau et éléments de sortie du message
• Formatage des flux de sortie : Formattage du message.

Ces trois composant regroupés permettent d'afficher les rapports de log suivant le type, le niveau et le formatage choisi.

1. Logger

Les loggers sont des noeuds constitués et nommés de façon hiérarchique. Les parents sont séparés des enfants par un point (".").

Par exemple gameforge.common est le parent de gameforge.common.log. Identique pour gameforge qui est parent de gameforge.client et un ancêtre de gameforge.client.engine Ceci est une façon de nommer une hierarchisation des loggers.

Un père reçoit également les messages de ses enfants.

Pour les loggers suivant : gameforge.client et gameforge.serveur. Les loggers gameforge.client et gameforge.serveur recevront leurs messages respectifs tandis que le logger gameforge recevra les messages de gameforge.client et de gameforge.serveur en plus de ses propres messages.

Le logger Root reside au plus haut niveau de la hiérarchie. Il a deux spécificités :

• Il n'a pas de nom
• Il existe toujours

La création de ce logger s'effectue en appellant la foncton gameforge::commun::log::Logger::getRootLogger() et les autres noeuds par gameforge::commun::log::Logger::getLogger("gameforge.test")

1. filtre

Les filtres définissent le niveau ainsi l'activation ou la désactivation des logs.

Des niveaux peuvent être assignés aux loggers. Les niveaux sont des types enum défini dans la classe Logger.hh sous le nom de TraceLevel'. Les niveaux suivants sont définis par ordre de priorité croissante :

• DEBUG
• INFO
• WARN
• ERROR
• FATAL

1. sortie

GFLOG vous permet actuellement d'envoyer le message vers trois destinations à la fois. Un logger peut donc avoir plusieurs destinations de sortie.

• sortie STDER

Ecriture vers la console en utilisant le flux de sortie STD::CERR

• sortie STDOUT

Ecriture vers la console en utilisant le flux de sortie STD::COUT

• sortie FSTREAM (fichier)

Les messages sont écrit dans un fichier.

Si le fichier existe déjà, il sera renommé en log1, log2, log3, etc.

En fonction de la taille du fichier (paramétrable), celui-ci peut être soit continué soit tronqué.

1. formatage de sortie

Il ya actuellement deux types de formatage :

• Simple affichage du message

Le message est affiché simplement

• En utilisant des tags (Pattern)

Les tags utilisés permet à l'utilisateur d'indiquer le format de message parmis des modèles de conversion semblables à ceux de la fonction printf du langage C.

%yyyy        => ANNEE
%mo          => MOIS
%dd          => JOUR
%hh          => HEURE
%mi          => MINUTE
%ss          => SECONDE
%ff          => MILLIEME DE SECONDE
%unique      => NUMERO UNIQUE
%file        => NOM DU FICHIER
%line        => NUMERO DE LIGNE
%type        => TYPE DE MESSAGE
%t           => NUMERO DU THREAD
%message     => MESSAGE

Mise en place

L'utilisation de GFLOG est configurable de façon manuelle. Par contre, il peut s'avérer pratique de le configurer en utilisant des fichiers de configuration. Actuellement, le fichier de configuration est écrit en XML.

GFLOG possède deux configurateurs distincts :

• Configurator
• XMLConfigurator

1. Configuration basique

Exemple de code d'initialisation des loggers

#ifdef HAVE_CONFIG_H
# include "config.h"
#endif
 
#include <string>
#include <iostream>
 
#include "gameforge/commun/log/Logger.hh"
 
using namespace std;
using namespace gameforge::commun::log;
 
int main(void)
{
  try
  {
    LoggerPtr root = Logger::getRootLogger();
    LoggerPtr logger = Logger::getLogger("gameforge.test");
 
    GFINFO(logger, "Entering in code");
    return 0;
  }
  catch(...)
  {
    return 1;
  }
}

1. Configuration par fichier XML

L'avantage d'utiliser ce mode de configuration est que les modifications sont effectuées de manière dynamique.

Fichier XML

<?xml version="1.0" encoding="ISO-8859-1"?>
 
<log>
 
  <!--
    Definition des flux de sortie
  -->
  <output id="f" type="file">
    <propertie name="Blablabla-%yyyy%mo%dd-%hh%mi%ss-%unique"/>
    <propertie format="%file (%line) : %type %hh:%mi:%ss:%ff [%t] - %message"/>
    <propertie maxsize="200k" />
  </output>
 
  <output id="c" type="stdout">
    <propertie format="%file (%line) : %type %hh:%mi:%ss:%ff [%t] - %message"/>
  </output>
 
  <output id="e" type="stderr">
    <propertie format="%file (%line) : %type %hh:%mi:%ss:%ff [%t] - %message"/>
  </output>
 
  <!--
    Definition des règle de filtrage
  -->
  <node name=".">
    <filter level="debug" output="e" />
    <filter level="error" output="c" /> 
  </node>
 
  <node name="gameforge.client">
    <filter level="debug" output="c" />
  </node>
 
  <node name="gameforge.server">
    <filter level="error" output="f" />
  </node>
 
  <node name="gameforge.commun.msg">
    <filter status="false" />
  </node>
 
</log>

Exemple de code avec fichier de configuration XML

#ifdef HAVE_CONFIG_H
# include "config.h"
#endif
 
#include <string>
#include <iostream>
 
#include "gameforge/commun/log/Logger.hh"
#include "gameforge/commun/log/Configurator.hh"
 
using namespace std;
using namespace gameforge::commun::log;
 
int main(void)
{
  try
  {
    Configurator::getInstance()->fromFile("commun/tests/log/config.xml", 5);
    LoggerPtr lc = Logger::getLogger("gameforge.client");
    LoggerPtr ls = Logger::getLogger("gameforge.server");
    LoggerPtr root = Logger::getRootLogger();
    
    GFDEBUG(lc, "Entering in code");
    GFERROR(root, "Pouet pouet 1");
    GFDEBUG(root, "Pouet pouet 2");
    GFERROR(ls, "Pouet pouet 3");
    GFDEBUG(ls, "Pouet pouet 4");
 
    Configurator::getInstance()->destroy();
 
    return 0;
  }
  catch(exception &e)
  {
    cerr << e.what() << endl;
    return 1;
  }
}