WinLog : une bibliothèque de génération de messages de trace

La capacité d'un programme à générer des messages de trace est une chose importante dans le cycle de vie d'une application. Cette capacité est utile lors du développement de l'application en phase de tests unitaires et surtout durant la phase des tests d'intégration et de validation. Elle permet aussi lorsqu'elle est déployée chez le client final de remonter les informations nécessaires pour le traitement d'un problème ou d'un bug.

Lors de la réalisation de mes différents projets, j'ai toujours été confronté au problème de la génération de messages de trace :

• Quel format de sortie utiliser ?
• Existe-t-il un composant que je pourrais réutiliser ?
• Est-ce que ce que je veux faire dans ce projet est compatible avec les fonctionnalités de ce composant existant ?

Ne trouvant pas de solution correspondant à mes besoins, je me suis lancé dans la réalisation d'une bibliothèque de génération des messages de trace.

Ce document a pour but de présenter l'implémentation d'une bibliothèque capable de générer des messages de trace de manière générique. Cette bibliothèque devrait être utilisée dès le début de la réalisation d'un projet. Ce document contient donc la spécification des fonctions et interfaces de cette bibliothèque ainsi que le code source permettant de la générer.

Version 1.2 du 13 juin 2011

• Les champs date et heure des messages peuvent être en heure UTC ou bien en heure locale. Ajout des fonctions WinLogSetUtcTime() et WinLogSetLocalTime().

Version 1.1 du 6 décembre 2010

• Le champ DateTime de la structure WinLogCallBack_Info_t est maintenant un long long (64 bits) et non plus un long (32 bits).
• Portage de la bibliothèque en 32 bits et en 64 bits.

Version 1.0 du 9 février 2009

• Première version.

WinLog permet de gérer des messages de trace avec la notion de niveau de fonctionnalités.

Il existe 33 niveaux différents qui vont du niveau 0 au niveau 32. Le niveau 0 est toujours affiché alors que les niveaux 1 à 32 peuvent être individuellement affichés ou non affichés.

Ces niveaux de fonctionnalités sont à la libre disposition du développeur afin de lui laisser la possibilité d'organiser ses messages de trace (par exemple les messages de trace de la bibliothèque de gestion des E/S, les messages de trace de gestion de l'interface utilisateur, les messages de trace de gestion des objets systèmes…).

Chaque message de trace généré possède un type fixé par le développeur de l'application qui utilise la bibliothèque WinLog. Les types existants sont les suivants :

• Info. Dans l'esprit de la bibliothèque, il s'agit d'un message de trace d'information pour, par exemple, indiquer le déroulement d'un processus.
• User. Dans l'esprit de la bibliothèque, il s'agit d'un message de trace utilisateur un petit peu plus important que le message précédent pour, par exemple, indiquer un point précis du déroulement d'un processus.
• Warning. Dans l'esprit de la bibliothèque, il s'agit d'un petit message de trace d'attention que le programme peut gérer tout seul. Par exemple, une mauvaise saisie de l'utilisateur.
• Error. Dans l'esprit de la bibliothèque, il s'agit d'un message de trace d'erreur un peu plus grave que le programme peut gérer probablement tout seul. Par exemple, un fichier de configuration inexistant.
• Fatal. Dans l'esprit de la bibliothèque, il s'agit d'un message de trace d'erreur grave que le programme ne sait peut-être pas gérer correctement. Par exemple, une erreur lors d'une allocation mémoire.
• Dump. Ce type est particulier, il ne correspond pas à une erreur, mais il est utilisé par exemple pour afficher le contenu d'une structure ou d'un bloc de mémoire à des fins d'analyse.

Le format des messages de trace est le suivant :

[<Identifiant>:<ProcessName>:<Type>:<UTC Date>:<Process ID>/<Thread ID>:<Level>] <Texte du message>

dans lequel on retrouve :

• Identifiant. Il s'agit d'un identifiant de messages de trace. Ce nombre est géré par la bibliothèque WinLog. Il vaut 0 pour le premier message de trace et est automatiquement incrémenté lors de la génération des messages de trace suivants. Ce nombre permet de voir si des messages de trace ont été perdus.
• ProcessName. Il s'agit du nom du processus qui génère le message de trace. Ce nom est défini par le développeur lors de l'initialisation de la bibliothèque WinLog.
• Type. Il s'agit du type du message de trace (Info, User, Warning, Error, Fatal, Dump). Ce type permet de catégoriser le message de trace en fonction de son niveau d'importance. Le type du message de trace est fixé par le développeur lors de l'écriture du code qui utilise la bibliothèque WinLog.
• UTC Date. Il s'agit de la date UTC de génération du message de trace. Le format utilisé est le format yyyy-mm-dd hh:mm:ss.
• Process ID. Il s'agit de l'identifiant du process qui génère le message de trace. Cette information est particulièrement importante dans le cas où plusieurs instances du programme sont exécutées simultanément.
• Thread ID. Il s'agit de l'identifiant du thread qui génère le message de trace. Cette information est particulièrement importante dans le cas des programmes multi threadés.
• Level. Il s'agit du niveau de fonctionnalité du message de trace. Cette information n'est pas disponible pour les messages de trace de niveau 0 qui sont toujours traités. Le niveau de fonctionnalité est fixé par le développeur lors de l'écriture du code qui utilise la bibliothèque WinLog.
• Texte du message. Il s'agit du message de trace lui-même. Le contenu de ce message de trace est fixé par le développeur lors de l'écriture du code qui utilise la bibliothèque WinLog.

Exemple de messages de trace :

[0:WinAgentLog:Info:2009-01-08 21:51:49:991/2188:00] Stopping the thread 2220 ...
[1:WinAgentLog:Info:2009-01-08 21:51:49:991/2188:00] Waiting for the end of a thread...
[2:WinAgentLog:Info:2009-01-08 21:51:49:991/2220:00] The service 'Phoenix Team WinAgentLog' is stopping
[3:WinAgentLog:Info:2009-01-08 21:51:50:991/2968:00] The thread CThreadEventLogReader is stopping EventLog location Application
[4:WinAgentLog:Info:2009-01-08 21:51:51:991/2972:00] The thread CThreadEventLogReader is stopping EventLog location Internet Explorer

L'environnement de développement et d'utilisation de la bibliothèque WinLog est l'environnement Microsoft. L'environnement de développement utilisé est Microsoft Visual Studio 2005 sur une machine Windows XP SP3. Lors de la réalisation de WinLog, plusieurs possibilités se sont offertes :

• La réalisation d'une bibliothèque statique.
• La réalisation d'une bibliothèque dynamique (ou DLL).
• La réalisation d'un composant COM.

Le choix pour une DLL a semblé assez naturel dans le sens où il permet le remplacement de la bibliothèque sans avoir besoin de recompiler l'application à condition que l'interface de la bibliothèque n'ait pas changé.

WinLog supporte les jeux de caractères Unicode et ANSI.

WinLog peut être appelée aussi bien depuis un programme C que d'un programme C++. Ce choix n'empêche absolument pas cette bibliothèque d'être écrite en C++ ou d'utiliser des composants C++.

Les messages de trace générés par WinLog peuvent être :

• Affichés sur la console de sortie (stdout).
• Enregistrés dans un fichier texte.
• Envoyés dans la fenêtre de débogage de l'environnement de développement.
• Envoyés dans le programme par une fonction de rappel (callback).
• Envoyés dans le programme par message Windows.
• Envoyés dans un tuyau nommé (pipe).
• Envoyés à destination d'un serveur Syslog en utilisant le protocole Syslog.

Le comportement de WinLog est modifié à l'aide de variables d'environnement afin de ne pas avoir besoin de recompiler l'application pour changer un des paramètres de la bibliothèque.

Les fichiers faisant partie de la bibliothèque WinLog sont :

• Le fichier d'en-tête WinLog.h. Ce fichier doit être inclus par tout module ou programme qui doit utiliser les fonctionnalités de la bibliothèque. Ce fichier est autosuffisant, il ne nécessite ni n'inclut d'autres fichiers include. Ce fichier n'est utile que lors de la phase de développement.
• Le fichier librairie WinLog.lib. Ce fichier définit les points d'entrée de la bibliothèque WinLog. Tout programme utilisant les fonctionnalités de la bibliothèque doit se lier avec. Ce fichier n'est utile que lors de la phase de développement.
• Le fichier DLL WinLog.dll. Ce fichier est la bibliothèque dynamique chargée par le système d'exploitation lors du lancement d'un programme utilisant les fonctionnalités de la bibliothèque WinLog. Ce fichier obligatoire pour pouvoir lancer un programme utilisant les fonctionnalités de la bibliothèque WinLog. Il doit être dans le répertoire du binaire qui utilise les fonctionnalités de WinLog ou bien encore dans un des répertoires définis par la variable d'environnement PATH.

Le fichier WinLog.h peut être téléchargé ici.

Le fichier WinLog.lib au format 32 bits peut être téléchargé ici.

Le fichier WinLog.dll au format 32 bits peut être téléchargé ici.

Le fichier WinLog.lib au format 64 bits peut être téléchargé ici.

Le fichier WinLog.dll au format 64 bits peut être téléchargé ici.

Le projet Visual Studio 2005 complet peut être téléchargé ici.

Les fichiers WinLog.dll et WinLog.lib ont été construits avec les caractéristiques de compilations suivantes :

• Environnement : 32 bits ou 64 bits (suivant la définition de la macro WIN64).
• Conventions d'appel : __cdecl.
• Mode : multithread.

Ce paragraphe présente les différents types de données spécifiques à la bibliothèque WinLog.

4-1-1. Le type WinLogRet_t▲

4-1-2. Le type WinLogType_t▲

4-1-3. Le type WinLogCallBack_Info_t▲

typedef struct
{    unsigned long       MesgIdentifier;
    const wchar_t   *   ProcessName;
    WinLogType_t        Type;
    unsigned long       Level;
    long long           DateTime;
    unsigned long       ProcessIdentifier;
    unsigned long       ThreadIdentifier;
    wchar_t         *   Header;
    wchar_t         *   Message;
} WinLogCallBack_Info_t;

4-1-4. Le type WinLogCallBack_t▲

typedef void (*WinLogCallBack_t)(WinLogCallBack_Info_t * CallbackInfo);

Les fonctions d'initialisation permettent comme leur nom l'indique de démarrer ou bien d'arrêter l'utilisation de la bibliothèque WinLog.

Ces fonctions permettent de spécifier le fonctionnement des modes de sortie des messages de trace. Les différents modes de sortie sont :

• Méthode File. Cette méthode permet d'écrire les messages de trace dans un fichier de sortie.
• Méthode Output. Cette méthode permet d'écrire les messages de trace dans le flux standard de la console (stdout).
• Méthode Debug. Cette méthode permet d'écrire les messages de trace dans la fenêtre de visualisation des messages du débogueur.
• Méthode Callback. Cette méthode permet d'envoyer les messages de trace dans une fonction de notification du processus (fonction de callback).
• Méthode PostSend Message. Cette méthode permet d'envoyer les messages de trace en utilisant les fonctions d'envoi de messages Windows (fonctions PostMessage ou SendMessage).
• Méthode Pipe. Cette méthode permet d'envoyer les messages de trace dans un pipe nommé.
• Méthode Syslog. Cette méthode permet d'envoyer les messages de trace dans un socket à destination d'un serveur Syslog.

4-4-1. Les fonctions de la méthode File▲

4-4-2. Les fonctions de la méthode Output▲

4-4-3. Les fonctions de la méthode Debug▲

4-4-4. Les fonctions de la méthode Callback▲

4-4-5. Les fonctions de la méthode PostSend Message▲

4-4-6. Les fonctions de la méthode Pipe▲

4-4-7. Les fonctions de la méthode Syslog▲

La bibliothèque WinLog définit un certain nombre de macros utilisables par le pré processeur afin de faciliter l'écriture des messages de trace. Ces macros sont :

• WINLOG_LEVEL_<nn> : Les différents niveaux de fonctionnalités possibles. Les valeurs que peut prendre nn vont de 00 à 32 pour spécifier chacun des 33 niveaux de fonctionnalité.
• INFO<n> : Ces macros permettent de générer un message de trace de type WinLog_Info et de niveau de fonctionnalité WINLOG_LEVEL_00. Les valeurs que peut prendre n vont de 1 à 5 pour indiquer le nombre de paramètres de la macro. Si le nombre de paramètres doit être plus grand que 5, il conviendra alors d'utiliser directement la fonction WinLog().
• USER<n> : Ces macros permettent de générer un message de trace de type WinLog_User et de niveau de fonctionnalité WINLOG_LEVEL_00. Les valeurs que peut prendre n vont de 1 à 5 pour indiquer le nombre de paramètres de la macro. Si le nombre de paramètres doit être plus grand que 5, il conviendra alors d'utiliser directement la fonction WinLog().
• WARNING<n> : Ces macros permettent de générer un message de trace de type WinLog_Warning et de niveau de fonctionnalité WINLOG_LEVEL_00. Les valeurs que peut prendre n vont de 1 à 5 pour indiquer le nombre de paramètres de la macro. Si le nombre de paramètres doit être plus grand que 5, il conviendra alors d'utiliser directement la fonction WinLog().
• ERROR<n> : Ces macros permettent de générer un message de trace de type WinLog_Error et de niveau de fonctionnalité WINLOG_LEVEL_00. Les valeurs que peut prendre n vont de 1 à 5 pour indiquer le nombre de paramètres de la macro. Si le nombre de paramètres doit être plus grand que 5, il conviendra alors d'utiliser directement la fonction WinLog().
• FATAL<n> : Ces macros permettent de générer un message de trace de type WinLog_Fatal et de niveau de fonctionnalité WINLOG_LEVEL_00. Les valeurs que peut prendre n vont de 1 à 5 pour indiquer le nombre de paramètres de la macro. Si le nombre de paramètres doit être plus grand que 5, il conviendra alors d'utiliser directement la fonction WinLog().
• DUMP2 : Cette macro permet de générer un message de trace de type WinLog_Dump et de niveau de fonctionnalité WINLOG_LEVEL_00. La taille de la structure ou du bloc de mémoire à afficher est calculée automatiquement par l'opérateur sizeof().
• DUMP3 : Cette macro permet de générer un message de trace de type WinLog_Dump et de niveau de fonctionnalité WINLOG_LEVEL_00. À la différence de DUMP2, cette macro ne calcule pas automatiquement la taille de la structure ou du bloc de mémoire. Il doit être fourni par le développeur.
• Les macros WinLog(), WinLogDump(), WinLogSyslogSetRemoteServer(), WinLogFileSetFolderName(), WinLogPipeSetName() sont des macros qui permettent de choisir automatiquement la version UNICODE ou ANSI de la fonction suivant que la macro UNICODE ou _UNICODE est définie ou non. Les mêmes conventions de nommage que Microsoft sont reprises pour ces fonctions (suffixe W pour les versions UNICODE ou A pour les versions ANSI).

Le fonctionnement de la bibliothèque WinLog peut être modifié en utilisant certaines variables d'environnement. Ces variables ajoutent une certaine souplesse d'utilisation en permettant d'activer ou de désactiver facilement et sans recompilation certaines fonctionnalités de la bibliothèque.

Les variables d'environnement gérées par la bibliothèque WinLog sont les suivantes :

• WINLOG_FEATURE_LEVEL : Cette variable d'environnement permet de spécifier les niveaux de fonctionnalité qui seront gérés par la bibliothèque. Par exemple, si la variable d'environnement WINLOG_FEATURE_LEVEL vaut 12, alors les niveaux de fonctionnalités affichés seront WINLOG_LEVEL_00, WINLOG_LEVEL_03 et WINLOG_LEVEL_04. Rappel, le niveau de fonctionnalité WINLOG_LEVEL_00 est toujours affiché.
• WINLOG_FILE_FOLDER : Cette variable d'environnement permet de spécifier le répertoire dans lequel est généré le fichier d'archivage des messages de trace. Si le chemin indiqué n'est pas valide, il est ignoré.
• WINLOG_FILE_SIZEMAX : Cette variable d'environnement permet de spécifier la taille du fichier d'archivage des messages de trace au-delà de laquelle une rotation des fichiers d'archivage est effectuée.
• WINLOG_FILE_HISTORYSIZE : Cette variable d'environnement permet de spécifier le nombre de fichiers d'historique à conserver lorsqu'une rotation des fichiers d'archivage est effectuée.
• WINLOG_FILE_ENABLED : Cette variable d'environnement permet de spécifier si la fonctionnalité d'écriture des messages de trace dans un fichier de sortie est activée ou non. Si la valeur de cette variable d'environnement vaut 0, la fonctionnalité est désactivée autrement, si la valeur de cette variable d'environnement est différente de 0, la fonctionnalité est activée.
• WINLOG_OUTPUT_ENABLED : Cette variable d'environnement permet de spécifier si la fonctionnalité d'écriture des messages de trace dans la console standard (flux stdout) est activée ou non. Si la valeur de cette variable d'environnement vaut 0, la fonctionnalité est désactivée autrement, si la valeur de cette variable d'environnement est différente de 0, la fonctionnalité est activée.
• WINLOG_PIPE_NAME : Cette variable d'environnement permet de spécifier le nom du pipe nommé à utiliser lorsque la fonctionnalité d'envoi des messages de trace dans un pipe nommé est activée. Si le nom de ce pipe n'est pas valide, il est ignoré.
• WINLOG_PIPE_ENABLED : Cette variable d'environnement permet de spécifier si la fonctionnalité d'écriture des messages de trace dans un pipe nommé est activée ou non. Si la valeur de cette variable d'environnement vaut 0, la fonctionnalité est désactivée autrement, si la valeur de cette variable d'environnement est différente de 0, la fonctionnalité est activée.
• WINLOG_SYSLOG_SERVER : Cette variable d'environnement permet de spécifier l'adresse IP du server Syslog vers qui envoyer les messages de trace au format Syslog.
• WINLOG_SYSLOG_PORT : Cette variable d'environnement permet de spécifier le port UDP du server Syslog vers qui envoyer les messages de trace au format Syslog.
• WINLOG_SYSLOG_FACILITY : Cette variable d'environnement permet de spécifier la facilité Syslog (de 0 à 23) à utiliser pour envoyer les messages de trace au format Syslog.
• WINLOG_SYSLOG_ENABLE : Cette variable d'environnement permet de spécifier si la fonctionnalité d'envoi des messages de trace à destination d'un serveur Syslog est activée ou non. Si la valeur de cette variable d'environnement vaut « 0 », la fonctionnalité est désactivée autrement, si la valeur de cette variable d'environnement est différente de « 0 », la fonctionnalité est activée.

Le fonctionnement par défaut de la bibliothèque WinLog est le suivant :

4-9-1. La méthode File▲

4-9-2. La méthode Output▲

4-9-3. La méthode Debug▲

4-9-4. La méthode Callback▲

4-9-5. La méthode PostSend Message▲

4-9-6. La méthode Pipe▲

4-9-7. La méthode Syslog▲

4-9-8. Le niveau de fonctionnalité▲