Traitement du Log

Introduction

Ce document est à destination des programmeurs désirant utiliser ou désirant sous une forme plus avancé implémenter leur propre serveur de Log dans leur processus.

Le processus des logs de traitements, anciennement appelés traitements d’importations, a été revu et mutualisé afin de faciliter son implémentation, sa maintenance, et son contrôle.

Ces éléments sont pour aider le support, nos partenaires et éventuellement, nos clients eux-mêmes sur ce qui s'est passé.

Je vais donc détailler ici-bas la mise en œuvre de cette fonctionnalité, qui n’a pas changée dans le fond mais donc la portée a été accrue.

L'objectif est de pouvoir disposer d'un log permanent de traitement afin de permettre de restituer ce qui s'est passé au cours de l’exécution, y compris quand on lance d’autres traitements, comme par exemple, l’intégration des remises bancaires avec constitution.

Ceci est introduit par la possibilité de supporter le log par n traitement enfant, et ceci en cascade.

On appréciera le fait que comme le traitement du log se fait dans un contexte transactionnel séparé, celui-ci sera préservé même en cas de rollback.

De plus, pour un traitement d’importation, on pourra également consulter le log directement sur la session auquel il est associé, quand cela est possible.

Précisons également l'introduction des stratégies gérant le regroupement du log ainsi que le débogage des formats via un écran de paramétrage (pour plus d'informations, consulter l'annexe correspondante).

Mise en œuvre

La mise en œuvre est relativement simple et l’implémentation se résume actuellement à implémenter le contrat d’interface IProcessusLoggable, son affectation important automatiquement la majeure partie du code nécessaire), et respecter quelques règles.

Les cas sont les suivants :

• Dériver d’un processus parent qui supporte déjà l’interface (le plus simple) :
  • Surcharger éventuellement la règle de valeur initiale ValeurInitiale_estDebugLog afin d’activer (ou non) la fonctionnalité de débogage des formats. Normalement inutile.
  • Surcharger éventuellement la règle de valeur initiale ValeurInitiale_enableLog afin d’activer (ou non) la fonctionnalité.
  • Surcharger la méthode protégée GetLibelleSession afin de redéfinir le libellé du traitement.

• Implémenter judicieusement la fonctionnalité sur une classe parente :
  • On ajoute l’interface IProcessusLoggeable.
  • On crée la règle d’action Action_Initialisation en déclenchement en initialisation des attributs (code en annexe).
  • On crée la règle de valeur initiale ValeurInitiale_estDebugLogLog à False par défaut. Sert à activer la fonctionnalité de débogage des formats.
  • On modifie la méthode protégée surchargeable GetLibelleSession afin de définir un autre libellé de traitement par défaut.
  • Utiliser les fonctions mises à disposition comme le trio StartLog, ReleaseLog, ILogEvt_Finalisation sur une fonction Executer (Cf. exemple pour plus de détail).

• Implémenter la fonctionnalité directement sur notre classe :
  • Identique à précédemment.

Il ne restera généralement ensuite plus qu'à remplacer l'instruction ProgressMessage par ProgressAndLog pour chaque message.

A noter : Dans certains cas, il peut exister des attributs et/ou des méthodes à supprimer avant de poser l'interface, car conflit avec celle ci, comme, par exemple, ILogEvt_*...

Informations techniques avancées

Pour pouvoir bénéficier de ce mécanisme, des interfaces IProcessusLoggable (le client), IProcessusLog (le serveur) et ILog (le log pour le serveur) ont été créés afin de pouvoir bénéficier de cet apport fonctionnel.

De plus, l’interface ISessionImportation ajoute désormais le rôle LogTnx vers la classe ILog, afin de remplacer l'ancien attribut string idLogTnx qui n’y était pas indiqué mais exploité, mais ce n'était pas un méthode correcte.

Le nouveau processus TProcessusLog implémente IProcessusLog afin de fournir le serveur de service pour le support de la fonctionnalité pour tous les traitements qui en auraient besoin.

Actuellement les clients implémentant IProcessusLoggable au moment de la rédaction de cette article sont :

• TProcessusComptaDeclarationTVA.
• TProcessusEpuration.
• TProcessusGestionDesSectionsEtDestinations.
• TProcessusImport.
• TProcessusImportGen.
• TProcessusMAJPlanGroupe.
• TProcessusSelection.
• TProcessusSelectionVue.

Détail de l'implémentation du client initial par le programmeur

Cette fonctionnalité ayant été introduite par le support de IProcessusLoggable afin d'initier le log sur tous les traitements selon l'usage suivant :

• Action_Initialisation : Cette règle d'action sur initialisation des attributs, qui crée le serveur qui doit TOUJOURS exister.
• GetLibelleSession : Cette fonction publique surchargeable peut être modifiée afin d'obtenir un libellé de traitement unique.
• LogEvt_Finalisation : Cette fonction protégée est généralement appelée à la fin d'une fonction Executer pour actualiser les statistiques du nombre d'éléments traités via l'attribut logEvtNombreElements et du temps du traitement.
• LogEvt_FinalisationEx : Même chose que la fonction LogEvt_Finalisation, en permettant de remplacer le libellé par défaut des statistiques.
• ReleaseLog : Cette fonction protégée permettant de "fermer" et libérer le log doit être appelée dans le cas d'une fonction Executer par exemple. Retourne True si un log a été clos, excepté si cas d'un parent.
• StartLog : Cette fonction protégée permettant d'initialiser log doit être appelée dans le cas d'une fonction Executer par exemple. Retourne True si OK.
• ValeurInitiale_enableLog : Cette règle de valeur initiale est à surcharger au besoin afin indiquer si le traitement doit être loggé.
• Supplément importation : La méthode surchargeable TProcessusImport.CreerSessionImport assigne pour la session en prime la référence du log existant sur le serveur par l’intermédiaire de sa fonction ISetSessionRefLogTnx.

Au moment de la rédaction de cette article, l'affichage de la session d'importation des remises bancaires, des relevés divers, des relevés de notifications, des relevés de cartes et de coordonnées bancaires permet d'afficher ce log via un filtre directement sur la session pour des raisons de facilités.

Notons que si l'implémentation de cette méthodologie a été appliquée en partie aux moyens de paiement, à la L&D, à la trésorerie (...) elle n'a pas été approfondie, il faudra la développer pour en bénéficier totalement.

Détail du contrat d'interface IProcessusLoggable

L’interface IProcessusLoggable cliente dispose de méthodes de classe qui permettent de créer le log, d’actualiser la référence de session pour les importation, d'ajouter des entrées, et de clore le log selon les principes suivants :

• L’attribut estDebugLog, qui devra être initialisé au besoin.
• L’attribut enableLog, qui devra être initialisé au besoin.
• L’attribut libelleSession (et Caption) qui mémorise le libellé du traitement, initialisé par le serveur.
• L’attribut long logEvtNombreElements qui transmettra le nombre d’éléments traités. Il est à la charge du programmeur de l'alimenter avant d'appeler LogEvt_Finalisation.
• Le rôle ProcessusLog référençant le serveur du traitement.
• DetachLogTnx : Permet au processus appelant de détacher le log qu'il avait précédemment attaché via SetLogTnx. Retourne True si OK.
• GetLibelleSession : Fonction publique surchargeable appelée par le serveur lors du traitement afin d’obtenir le libellée applicatif.
• Log : Permet l'ajout d'un message au log avec son état, le serveur ajoutant également la date et heure.
• LogEvt_Finalisation : Fonction protégée qui informe le serveur de la clôture du traitement, afin d'actualiser les statistiques.
• LogEvt_FinalisationEx : Fonction protégée qui informe le serveur de la clôture du traitement avec un libellé de remplacement pour les statistiques, afin d'actualiser les statistiques.
• LogEvt_Initialisation : Fonction surchargeable appelée par le serveur pour finaliser l’initialisation du log événementiel lors du traitement de IStartLog.
• LogTime : Message que l'on envoie vers le log système du Framework.
• ProgressAndLog : Permet l'affichage et l'ajout d'un message au log avec son état, le serveur ajoutant également la date et heure.
• ReleaseLog : Cette fonction demande la clôture du log, qui, du coté serveur, se contentera de renseigner la date du fin de traitement sur le log et de supprimer la référence correspondante afin que l'on ne puisse plus faire d'ajout dessus.
• SetLogTnx : Permet l’attachement du processus appelant, via le serveur, qui, une fois réalisé, aura rattaché le log de l’appelant et désactivé enableLog en conséquence. Retourne OK si attachement effectuée.
• StartLog : La création du log, qui notera la date de création du log, avec démarrage du loggage événementiel XML. Retourne True si OK.

NOTE : La référence de l'objet appelant, la description (Caption) qui sera appliqué sur le log ainsi que le rôle matérialisé par l'attribut oidSessionImportation s'il existe, le serveur recevra en sortie l'identifiant du log nécessaire pour la suite du traitement.

Détail du contrat d'interface IProcessusLog

L’interface IProcessusLog permet au client de transmettre ou de recevoir des informations du serveur (pour information) :

• L’attribut privé estDebugLog, qui mémorise l'état pris sur le client ou le parent lors de IStartLog ou ISetLogTnx. La stratégie existante peut en forcer la valeur.
• L’attribut privé enableLog, qui mémorise l’état transmit par le client lors de IStartLog.
• L’attribut privé libelleSession qui mémorise le libellé du client lors du IStartLog.
• L'attribut public logEvtCleValeur qui restituera l'état statistique du traitement.
• L'attribut privé logEvtTempsDepart qui mémorise le démarrage du traitement lors du IStartLog.
• L'attribut privé strategieStockageLog' qui mémorise la stratégie de stockage du log à appliquer, permettant d'outrepasser le standard en forcant l'activation / désactivation.
• L'attribut privé strategieRegroupement' qui mémorise la stratégie de regroupement à appliquer pour les attachements, afin de les bloquer le cas échéant.
• IGetEstActifRegroupementOptionnel : Retourne au client si le mode regroupement de log optionnel est disponible, ce qui permet à celui-ci de ne pas faire l'attachement car c'est à ce stade sa décision.
• IGetOidLogTnx : La possibilité d’obtenir la référence du log actif (il est préférable d’utiliser cette possibilité uniquement si on ne peut pas faire autrement).
• IInitialise : Normalement appelée lors de StartLog, doit éventuellement être appelé par le client pour préparer les données si celui-ci n'utilise pas le couple StartLog/ReleaseLog.
• ILog : L’implémentation pour Log.
• ILogDirect : L’implémentation dépréciée pour Log.
• ILogEvt_Finalisation : La finalisation surchargeable du temps de traitement pour LogEvt_Finalisation et LogEvt_FinalisationEx.
• ILogTime : L’implémentation pour LogTime.
• IProgressAndLog : L’implémentation pour ProgressAndLog.
• IReleaseLog : L’implémentation pour ReleaseLog .
• ISetLogTnx : L’implémentation de SetLogTnx.
• ISetSessionRefLogTnx: L’implémentation permet au client d’assigner la référence du log actif du serveur sur la session fournie en paramètre.
• IStartLog : L’implémentation pour StartLog.

Détail de l'implémentation du processus TProcessusLog

Actuellement, le serveur est réalisé par le processus TProcessusLog avec les modalités complémentaires suivantes :

• Le rôle LogTnx qui conserve la référence du Log.
• L'implémentation de IInitialise qui recharge les paramètres via _RechargerParametres, réapplique les stratégies applicables, dans la mesure du possible. Retourne True si OK.
• L’implémentation de ILog mémorise les données via TLog.AddEntry quand le Log a été démarré ou assigné.
• L’implémentation de ILogDirect fait de même que ILog, hormis qu'il créera le log si nécessaire. Cette méthode Log doit être appelée de préférence quand le log a été initialisé, car sinon elle peut être à l'origine de contentions (deadlock). C'est pourquoi il faut mieux s'abstenir de l'utiliser, ou, du moins en limiter l’usage, dans ce cadre précis.
• L’implémentation de ILogEvt_Finalisation traite l’information logEvtNombreElements du client afin de finaliser le LogEvt.
• L’implémentation de IStartLog mémorise enableLog et estDebugLog du client via IInitialise, demande au client de fournir un libellé qui sera ensuite mémoriser simultanément sur le client et le serveur.
• L’implémentation de IReleaseLog achève le traitement du log, uniquement si enableLog vaut TRUE, ce qui n’est pas le cas lors d’un attachement. Retourne True si effectivement libéré.
• L’implémentation de ISetLogTnx vérifie que le rôle LogTnx existe bien sur la référence serveur du client transmit avant d’initialiser enableLog sur FALSE et de réassigner le rôle, mais uniquement si celle-ci n’est pas le serveur lui-même. De plus, si les stratégies le permettent et que le parent est en mode estDebugLog = True, la valeur sera appliquée au client existant. Retourne True si effectivement attaché.
• La méthode privée _GetParametreLog qui retourne le singleton de paramétrage du log, en le créant si nécessaire.
• La méthode privée _RechargerParametres qui recharge les paramètres du serveur, avec la recherche d'une exception qualifié lorsque que la gestion correspondante est active. Retourne False si erreur de lecture sur paramètres mais peut continuer.
• La règle Action_ValeurInitialDepuisParametres qui provoque le chargement initial des paramètres par l'appel de _RechargerParametres lors de l'initialisation des attributs.
• La régle ValeurInitiale_enableLog qui initialise enableLog sur False.
• La règle ValeurInitiale_estDebugLog qui initialise estDebugLog sur False.
• La régle ValeurInitiale_libelleSession qui initialise libelleSession à une valeur par défaut.

Annexes

Exemple de code pour la règle Action_Initialisation

//procedure Action_Initialisation:boolean;
//Traite les tâches d'initialisations du module, traité par le serveur
begin
  if Not Assigned(ProcessusLog) then
    ProcessusLog := TProcessusLog.Create;
 
  ProcessusLog.IInitialise(Self);
end;

Base du modèle appliqué au processus de base d'importation

Paramétrage des stratégies

Les stratégies définissent comment l'instance du serveur doit se comporter en fonction des situations paramétrées.

On peut accéder actuellement à l'écran de paramétrage via le menu de paramétrage des moyens de paiements : Paramètres -> Paramètres -> Paramètres Log.

Le paramétrage accepte la gestion des exceptions, qui, quand elle est activée, sera appliqué par le serveur afin de recherche une exception pour un traitement donné, qui peut fournir la stratégie selon ces règles :

• La classe et l'utilisateur loggé sont renseignés sur l'exception.
• Seule la classe est renseignée sur l'exception.
• Seul l'utilisateur loggé est renseigné sur l'exception.
• Le paramétrage global s'applique.

Ecran de paramètres Logs emp_parametreslog

On y accède via l'écran emp_parametreslog.

Stratégie de stockage des logs

Cette stratégie du serveur peut remplacer les choix par défaut (standard) appliqué au client :

• Désactivé : Désactive complètement le stockage et l'attachement du log par un parent du client et n'autorise pas celui-ci à activer le débogage du format.
• Standard : Respecte le choix du client.
• Activé : Force l'activation du log sur le client s'il le supporte.

Stratégie de regroupement du log

Disponible uniquement si la stratégie de stockage n'est pas désactivée.

Cette stratégie du serveur peut remplacer les choix par défaut (standard) appliqué au client :

• Désactivé : Désactive complètement le regroupement du log du client (log autonome).
• Standard : Applique le loggage standard du client, qui, s'il reçoit la demande d'attachement du log du parent, transmettra les informations sur ce log qui sera géré exclusivement par le parent.
• Complet : Accepte également le loggage étendue, identique à la stratégie standard, hormis que le client reçoit True s'il vérifie que le chaînage optionnel est autorisée. Permet ainsi au programmeur de conditionner l'attachement.

Stratégie de débogage des formats

Cette stratégie du serveur peut remplacer les choix par défaut (standard) appliqué au client :

• Désactivé : Désactive complètement le débogage des formats du client et n'autorise pas celui-ci à activer le débogage du format.
• Standard : Respecte le choix du client.
• Local : Force l'activation du débogage sur le client.
• Parent : Identique à standard, excepté si le client a été chaîné par un parent, auquel cas son choix prime.
• Complet : Force l'activation du débogage sur le client ainsi que sur ses enfants attachés par IStartLog'.

Ecran de consultation générique des logs emp_consultationlogsessionimport

On y accède via l'écran emp_consultationlogsessionimport. Il permet de lister l'ensemble des logs existants dans le système, et de les supprimer.

Un double clic sur la ligne d'un log nous amène à l'écran de consultation de celui-ci.

Exemple d'implémentation sur l'écran d'affichage de la session d'importation des relevés de coordonnées bancaires

Débogage des formats

Les nouveaux moteurs d'importation et de génération basés sur des formats peuvent retourner des informations supplémentaires dans le mémo du traitement, et dans le répertoire Log du container.

Le paramètre adéquat (ou un bout de code) permettra d'activer ce mode particulier à la demande pour la mise au point de vos formats, ce qui constitue un passage plus que recommandé afin de finaliser la mise au point des formats.

Voir aussi

• Guide de l'Utilisateur sur le log de traitement.
• Maîtrise du pattern d'importation.
• Paramétrage et traitement d'importation.

— Importation (patterns) — Développement DSM —