Journalisation (Logging) et Débogage

Il existe quelques frameworks de journalisation disponibles pour Java. La journalisation est préférable à l’écriture sur la sortie standard (stdout) et la sortie d’erreur (stderr) avec System.out.println() pour un bon nombre de raisons:

  • Les messages logués (enregistrés) sont classés par nom de source. Cela rend plus facile à comprendre d’où ils proviennent.

  • Les messages logués ont un niveau de sévérité qui permet un filtrage simple (ex: masquer toutes les entrées sans importance).

  • Le frameworks de log disponible vous permet d’activer ou désactiver les message de certaines sources.

Sponge utilise org.slf4j.Logger, et non pas java.util.logging.Logger.

Obtenir un Logger

Le module Guice utilisé lors de l’initialisation des plugins a un Logger au champ d’action limité à votre plugin. Cela vous permet d’annoter un champ, une méthode ou un constructeur avec @Inject pour obtenir le « Logger » de votre plugin, qui est pré-configuré avec le bon ID de plugin.

Note

Voir Classe Principale du Plugin pour des informations sur la configuration de votre plugin ID.

Exemple - Field

import com.google.inject.Inject;
import org.slf4j.Logger;

@Inject
private Logger logger;

Exemple - Méthode

private Logger logger;

@Inject
private void setLogger(Logger logger) {
    this.logger = logger;
}

Exemple - Constructeur

// For the purpose of this example, "Banana" is the class name

private Logger logger;

@Inject
public Banana(Logger logger) {
    this.logger = logger;
}

Il est recommandé de définir votre Logger dans la classe principale de votre plugin, pour qu’elle soit instanciée avec l’injecteur Guice lorsque le plugin se lance.

Créer une méthode « Get » (voir Getter and Setter) pour votre Logger dans la même classe que celle où il a été défini serait l’idéal, bien que facultatif. Un exemple d’une méthode d’accesseur « Get » est illustré ci-dessous.

public Logger getLogger() {
    return logger;
}

Émition de Messages

Envoyer un message avec votre Logger est vraiment très simple.

Note

L’exemple suivant suppose que la méthode d’accesseur pour votre Logger est nommée “”getLogger()””, comme indiqué dans la section précédente. Cela peut différer pour vous selon ce que vous voulez retourner avec cet accesseur.

getLogger().info("String");
getLogger().debug("String");
getLogger().warn("String");
getLogger().error("String");

Cette String (chaîne de caractères) est le message que vous voulez envoyer. Par exemple:

getLogger().warn("This is a warning!");

Manipuler le Logging

Note

Ces techniques doivent seulement être utilisées dans de très rares cas, comme des défauts de logging mal choisis dans des bibliothèques. Ajoutez une option de configuration pour les désactiver si vous les utilisez.

Certains bibliothèques utilisent de mauvaises pratiques de logging, comme faire du logging à un niveau trop haut. Dans ces cas, vous avez trois choix :

  1. Demandez à l’auteur de la bibliothèque d’ajuster ses standards de logging, afin de corriger le problème à sa source.

  2. Recommandez à vos utilisateurs de configurer le logging en utilisant un fichier de configuration log4j2.xml. Fournissez aux utilisateurs les additions de configuration recommandées.

  3. Configurer le logging dans votre plugin vous-même :

    ((org.apache.logging.log4j.core.Logger) LogManager.getLogger("FtpLoggingFilter")).setLevel(Level.WARN);

    Cela configure le niveau de log du logger FtpLoggingFilter à WARN. Cela va cacher tous les messages qui utilisent un niveau de log plus bas comme INFO et DEBUG.

    Avertissement

    Cette solution assume que log4j2 est utilisé comme framework de logging par le serveur, cependant, cela peut ne pas être le cas pour toutes/les futures implémentations de SpongeAPI.

Si vous avez des questions à propos du logging, vous pouvez toujours nous demander sur IRC, Discord ou les Forums.