Author: Bob Jacobsen
Keywords: JMRI log4j logging log

# JMRI: Comment faire pour utiliser le Rapport

Cette page fournit un peu d'information sur la façon dont JMRI enregistre les erreur, l'état et les informations de débogage.

Pour d'autres détails internes sur JMRI , s'il vous plaît voir les pages techniques.

JMRI utilise le paquet Jakarta Log4J pour gérer les enregistrements depuis les classes individuelles. spécifiquement, depuis l'été 2015, nous utilisons la version 1.2.15; ce n'est pas la plus récente! nous l'utilisons via le système: SLF4J. ( Pour les librairies qui utilisent le systèm" java.util.loggind, exemple: jmDNS, nous utilisons ausssi l'adaptateur jul-to-slf4j )

### Niveaux d'Enregistrement

Cette combinaisons fournit plusieurs niveaux d'enegistrement

Niveau | Fragment Code | Utilisation
--- | --- | ---
ERREUR | log.error(..) | Indique que l'opération désirée n'a pas réussi et et devrait expliquer pourquoi. ERROR est destinée à être utilisé uniquement pour les graves problèmes qui demandent plus d'attention à chaque fois qu'ils surviennent, typiquement indication d'une possible faute dans JMRI lui-même.
ATTENTION | log.warn(..) | Le programme fonctionne toujours, en quelque sorte, mais quelque chose a mal fonctionné; souvent utilisé pour dire "Cette opération peut ne pas avoir fait tout ce que vous vouliez". Utilisez WARN lorsque la cause du problème est une entrée utilisateur incorrecte.
INFO | log.info(..) | Routines messages que vous voulez voir en fonctionnement normal. Gardez les à un minimum s'il vous plaît, il ne devrait pas y en avoir après que le programme a démarré.
DEBOGAGE | log.debug(..) | Messages détaillés, Utilisés seulement pout le débogage. Il y en a beaucoup , et les activer tous peut ralentir le programme de manière significative.
TRACE | log.debug(..) | Messages très détaillés, plus encore que DEBUG, utilisé pour le débogage volumineux (exemple: tous les caractères dans une transmissions) qui devrait normalement être désactivé, même lors du débogage. Typiquement seulement allumé pour une classe à la fois en raison de problèmes de volume et de performance.

### Configuration

Par convention, les applications JMRI attendront pour initialiser Log4J utilisant le fichier de contrôle de connexion: "default.lcf" JMRI qui contient une version du fichier defaut.lcf avec de nombreux commentaires. ( Ce fichier doit être impérativement dans le "Répertoire Program", qui peut être trouvé en sélectionnant l'élémment "Emplacement" dans le menu Aide principal ) Le reste de cette section décrit le contenu d'un fichier de contrôle de connexion utilisant le contenu du fichier default.lcf comme exemple.

La ligne:

     log4j.rootCategory= INFO, A1, T, R

contrôle où va la sortie connexion. Plus tard dans le fichier, il y a des indices A1, T et R définis qui écrivent les messages vers:

- A1 - la console sur l'ordinateur local, réellement stdout/stderr, qui est aussi disponible via l'élément Console du menu Aide JMRI.
- R - un simple fichier. Par défaut, il est appelé "session.log". Celui-ci démarre à chaque fois que JMRI est relancé
- T - un jeu de fichiers tournants. Le fichier actuel est appelé "messages.log". Quand il atteint 2 MB, il tourne pour un nouveau fichier. Les deux versions les plus anciennes sont gardées Notez que cela se poursuit à travers le redémarrage du programme, de sorte que vous pouvez voir tous les messages enregistrés au début ou à la fin du programme.

Les fichiers sont stockés dans un répertoire spécifié par les paramètres de jmri.log.path qui est pointé par défaut vers le sous répertoire log dans le répertoire preferences

Le fichier "default.lcf" détermine aussi le format de la sortie par le réglage des paramètres du "circuit".

    log4j.appender.R.layout=org.apache.log4j.PatternLayout

    log4j.appender.R.layout.ConversionPattern=%d{ISO8601} %-37.37c{2} %-5p - %m [%t]%n

Un exemple de ce format par défaut:

    2015-10-28 20:31:52,307 jmri.jmrit.powerpanel.PowerPane  WARN - No power manager instance found, panel not active [AWT-EventQueue-0]

Les colonnes sont:

- `2015-10-28 20:31:52,307` - Heure locale à laquelle le message a été enregistré
- `jmri.jmrit.powerpanel.PowerPane` - l'emplacement dans le code ( nom de la classe ) qui a émit le message.
- `WARN` - sévérité du message
- `No power manager instance found, panel not active` - le message lui-même.
- `[AWT-EventQueue-0]` - nom de la tâche qui a émit le message.

### Codage

Pour enregistrer des messages à partir d'une classe nommée MyClass, ajoutez à la fin du fichier de classe .java:

            private static final Logger log = LoggerFactory.getLogger(MyClass.class);

et ajoutez des importations pour org.slf4j.Logger et org.slf4j.LoggerFactory dans votre section importation:

`import org.slf4j.Logger;
import org.slf4j.LoggerFactory;` Il est également OK de combiner ceux-ci suivant cette forme :

        private static final org.slf4j.Logger log = org.slf4j.LoggerFactory.getLogger(MyClass.class);

(Si l'enregistrement est retiré (par exemple commenté), il est OK pour commenter la définition de l'enregistrement de sorte qu'il peut être facilement rajouté plus tard. )

Pour chaque message à enregistrer, inserez une ligne comme;

            log.debug("message");

Les messages qui ne sont pas juste une chaîne explicites doivent utiliser cette forme à la place des variables:

            log.debug("Found {}", numberEntries);

Les opérations de chaîne pour construire le message réel d'erreur (dans ce cas, la combinaison "Found" et l'argument numberEntries) ne sont fait que si le message va être stocké dans les journaux, ce qui permet d'économiser beaucoup de temps lors de l'exécution normale (non-debug ) .

Si c'est informatiquement coûteux de passer un paramètre dans le journal, utilisez le formulaire ci-dessous pour que le programme ne perde pas de temps en calcul de paramètres (dans ce cas, appeler numberEntries () pour obtenir une valeur pour passer à l'appel de fonction):

            if (log.isDebugEnabled()) {
                log.debug("Found {}", numberEntries());
            }

Les exceptions devraient être enregistrées comme:

            log.error("my local text"+exception.getLocalizedMessage(), exception);

pour inclure la description lisible de l'utilisateur depuis l'exception elle-même, ainsi que toutes ses informations de retraçage.

DEBUG | log.debug(..) | Messages détaillés, utilisé dans le débogage
INFO | log.info(..) | Messages de routine que vous pouvez voir en fonctionnement normal
WARN | log.warn(..) | Le programme est encore en exploitation, en quelque sorte, mais quelque chose doit être examiné
ERROR | log.error(..) | Indique que l'opération souhaitée ne va pas se produire, et explique pourquoi