Introduction à Log4j2 - Appenders, dispositions et filtres

1. Vue d'ensemble

La journalisation des événements est un aspect critique du développement logiciel. Bien qu'il existe de nombreux frameworks disponibles dans l'écosystème Java, Log4J est le plus populaire depuis des décennies, en raison de la flexibilité et de la simplicité qu'il offre.

Log4j 2 est une nouvelle version améliorée du framework Log4j classique.

Dans cet article, nous présenterons les ajouts, mises en page et filtres les plus courants via des exemples pratiques.

Dans Log4J2, un appender est simplement une destination pour les événements de journal; il peut être aussi simple qu'une console et peut être complexe comme n'importe quel SGBDR. Les mises en page déterminent la façon dont les journaux seront présentés et les filtres filtrent les données en fonction des différents critères.

2. Configuration

Afin de comprendre plusieurs composants de journalisation et leur configuration, configurons différents cas d'utilisation de test, chacun consistant en un fichier de configuration log4J2.xml et une classe de test JUnit 4 .

Deux dépendances maven sont communes à tous les exemples:

 org.apache.logging.log4j log4j-core 2.7   org.apache.logging.log4j log4j-core 2.7 test-jar test 

Outre le package principal log4j-core , nous devons inclure le 'test jar' appartenant au package pour accéder à une règle de contexte nécessaire pour tester des fichiers de configuration inhabituellement nommés.

3. Configuration par défaut

ConsoleAppender est la configuration par défaut du package principal Log4J 2 . Il enregistre les messages sur la console système selon un modèle simple:

Analysons les balises dans cette configuration XML simple:

  • Configuration : L'élément racine d'un fichier de configuration Log4J 2 et l' état de l' attribut est le niveau des événements Log4J internes que nous voulons consigner
  • Appenders : cet élément contient un ou plusieurs appenders. Ici, nous allons configurer un appender qui sort sur la console système à la sortie standard
  • Loggers : cet élément peut être constitué de plusieurs éléments Logger configurés . Avec la balise spéciale Root , vous pouvez configurer un enregistreur standard sans nom qui recevra tous les messages du journal de l'application. Chaque enregistreur peut être réglé sur un niveau de journal minimum
  • AppenderRef : cet élément définit une référence à un élément de la section Appenders . Par conséquent , l'attribut « ref » est lié à un appenders de nom attribut '

Le test unitaire correspondant sera tout aussi simple. Nous obtiendrons une référence Logger et imprimerons deux messages:

@Test public void givenLoggerWithDefaultConfig_whenLogToConsole_thanOK() throws Exception { Logger logger = LogManager.getLogger(getClass()); Exception e = new RuntimeException("This is only a test!"); logger.info("This is a simple message at INFO level. " + "It will be hidden."); logger.error("This is a simple message at ERROR level. " + "This is the minimum visible level.", e); } 

4. ConsoleAppender avec PatternLayout

Définissons un nouvel appender de console avec un modèle de couleur personnalisé dans un fichier XML séparé, et incluons-le dans notre configuration principale:

Ce fichier utilise des variables de modèle qui sont remplacées par Log4J 2 lors de l'exécution:

  • % style {…} {colorname} : Ceci imprimera le texte de la première paire de crochets ( ) dans une couleur donnée ( colorname ).
  • % highlight {…} {FATAL = colorname,…} : Ceci est similaire à la variable 'style'. Mais une couleur différente peut être donnée pour chaque niveau de journal.
  • % date {format} : ceci est remplacé par la date actuelle au format spécifié . Ici, nous utilisons le format DateHeure 'DEFAULT', ' aaaa -MM-jj HH: mm: ss, SSS' .
  • % -5level : imprime le niveau du message de journal dans l'alignement à droite.
  • % message : représente le message du journal brut

Mais il existe beaucoup plus de variables et de formatage dans PatternLayout . Vous pouvez les référer à la documentation officielle du Log4J 2.

Nous allons maintenant inclure l'appender de console défini dans notre configuration principale:

Le test unitaire:

@Test public void givenLoggerWithConsoleConfig_whenLogToConsoleInColors_thanOK() throws Exception { Logger logger = LogManager.getLogger("CONSOLE_PATTERN_APPENDER_MARKER"); logger.trace("This is a colored message at TRACE level."); ... } 

5. Appender de fichier asynchrone avec JSONLayout et BurstFilter

Parfois, il est utile d'écrire des messages de journal de manière asynchrone. Par exemple, si les performances de l'application ont priorité sur la disponibilité des journaux.

Dans de tels cas d'utilisation, nous pouvons utiliser un AsyncAppender.

Pour notre exemple, nous configurons un fichier journal JSON asynchrone . De plus, nous allons inclure un filtre en rafale qui limite la sortie du journal à un taux spécifié:

   ...          ...        

Remarquerez que:

  • Le JSONLayout est configuré de manière à écrire un événement de journal par ligne
  • Le BurstFilter supprimera tous les événements avec le niveau 'INFO' et plus s'il y en a plus de deux, mais à un maximum de 10 événements abandonnés
  • L' AsyncAppender est défini sur une mémoire tampon de 80 messages de journal; après cela, le tampon est vidé dans le fichier journal

Jetons un coup d'œil au test unitaire correspondant. Nous remplissons le tampon ajouté dans une boucle, laissez-le écrire sur le disque et inspectez le nombre de lignes du fichier journal:

@Test public void givenLoggerWithAsyncConfig_whenLogToJsonFile_thanOK() throws Exception { Logger logger = LogManager.getLogger("ASYNC_JSON_FILE_APPENDER"); final int count = 88; for (int i = 0; i  0 && logEventsCount <= count); }

6. RollingFile Appender et XMLLayout

Ensuite, nous allons créer un fichier journal glissant. Après une taille de fichier configurée, le fichier journal est compressé et pivoté.

Cette fois, nous utilisons une mise en page XML :

Notice that:

  • The RollingFile appender has a ‘filePattern' attribute, which is used to name rotated log files and can be configured with placeholder variables. In our example, it should contain a date and a counter before the file suffix.
  • The default configuration of XMLLayout will write single log event objects without the root element.
  • We're using a size based policy for rotating our log files.

Our unit test class will look like the one from the previous section:

@Test public void givenLoggerWithRollingFileConfig_whenLogToXMLFile_thanOK() throws Exception { Logger logger = LogManager.getLogger("XML_ROLLING_FILE_APPENDER"); final int count = 88; for (int i = 0; i < count; i++) { logger.info( "This is rolling file XML message #{} at INFO level.", i); } }

7. Syslog Appender

Let's say we need to send logged event's to a remote machine over the network. The simplest way to do that using Log4J2 would be using it's Syslog Appender:

   ...     ...        

The attributes in the Syslog tag:

  • name: defines the name of the appender, and must be unique. Since we can have multiple Syslog appenders for the same application and configuration
  • format: it can be either set to BSD or RFC5424, and the Syslog records would be formatted accordingly
  • host & port: the hostname and port of the remote Syslog server machine
  • protocol: whether to use TCP or UPD
  • facility: to which Syslog facility the event will be written
  • connectTimeoutMillis: time period of waiting for an established connection, defaults to zero
  • reconnectionDelayMillis: time to wait before re-attempting connection

8. FailoverAppender

Now there may be instances where one appender fails to process the log events and we do not want to lose the data. In such cases, the FailoverAppender comes handy.

For example, if the Syslog appender fails to send events to the remote machine, instead of losing that data we might fall back to FileAppender temporarily.

The FailoverAppender takes a primary appender and number of secondary appenders. In case the primary fails, it tries to process the log event with secondary ones in order until one succeeds or there aren't any secondaries to try:

Let's test it:

@Test public void givenLoggerWithFailoverConfig_whenLog_thanOK() throws Exception { Logger logger = LogManager.getLogger("FAIL_OVER_SYSLOG_APPENDER"); Exception e = new RuntimeException("This is only a test!"); logger.trace("This is a syslog message at TRACE level."); logger.debug("This is a syslog message at DEBUG level."); logger.info("This is a syslog message at INFO level. This is the minimum visible level."); logger.warn("This is a syslog message at WARN level."); logger.error("This is a syslog message at ERROR level.", e); logger.fatal("This is a syslog message at FATAL level."); }

9. JDBC Appender

L'appendeur JDBC envoie les événements du journal à un SGBDR, à l'aide de JDBC standard. La connexion peut être obtenue en utilisant n'importe quelle source de données JNDI ou n'importe quelle fabrique de connexions.

La configuration de base se compose d'un DataSource ou ConnectionFactory , ColumnConfigs et tableName:

Essayons maintenant:

@Test public void givenLoggerWithJdbcConfig_whenLogToDataSource_thanOK() throws Exception { Logger logger = LogManager.getLogger("JDBC_APPENDER"); final int count = 88; for (int i = 0; i < count; i++) { logger.info("This is JDBC message #{} at INFO level.", count); } Connection connection = ConnectionFactory.getConnection(); ResultSet resultSet = connection.createStatement() .executeQuery("SELECT COUNT(*) AS ROW_COUNT FROM logs"); int logCount = 0; if (resultSet.next()) { logCount = resultSet.getInt("ROW_COUNT"); } assertTrue(logCount == count); }

10. Conclusion

Cet article montre des exemples très simples de la façon dont vous pouvez utiliser différents ajouts, filtres et mises en page de journalisation avec Log4J2 et des moyens de les configurer.

Les exemples qui accompagnent l'article sont disponibles à l'adresse over sur GitHub.