JBoss log4j configuration

This tutorial has been written for older versions of the application server (JBoss AS 4/5/6). A more recent tutorial about Log4j has been written here: Using Log4J with WildFly and JBoss EAP

JBoss AS uses log4j as logging framework. This tutorial will show how to configure log4j service in your jBoss application server and also how to create a custom configuration which can be deployed along with your application.

Log4j is a flexible open source project from Apache. Using Log4j, we can replace the debugging print line statements with configurable logging statements.The advantage in using Log4j is, if you do not want to print the debugging print lines in production application, you can easily switch them off using Log4j configuration file.

At first let’s see where Log4j configuration file is located:

  • In the releases 4.x and 5.x it’s located here:JBoss_HOME\server\default\conf\jboss-log4j.xml
  • In the release JBoss AS 6.x it’s located in the deploy folder: JBOSS_HOME\server\default\deploy\jboss-logging.xml
    Let’s have a look at a minimal configuration:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE log4j:configuration SYSTEM "log4j.dtd">

<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/" debug="false">

    <appender name="FILE" class="org.jboss.logging.appender.DailyRollingFileAppender">
        <errorHandler class="org.jboss.logging.util.OnlyOnceErrorHandler"/>
        <param name="File" value="${jboss.server.log.dir}/server.log"/>
        <param name="Append" value="false"/>

        <param name="DatePattern" value="'.'yyyy-MM-dd"/>

        <layout class="org.apache.log4j.PatternLayout">
            <param name="ConversionPattern" value="%d %-5p [%c] %m%n"/>

    <appender name="CONSOLE" class="org.apache.log4j.ConsoleAppender">
        <errorHandler class="org.jboss.logging.util.OnlyOnceErrorHandler"/>
        <param name="Target" value="System.out"/>
        <param name="Threshold" value="INFO"/>

        <layout class="org.apache.log4j.PatternLayout">
            <param name="ConversionPattern" value="%d{ABSOLUTE} %-5p [%c{1}] %m%n"/>

    <category name="com.sample">
        <priority value="INFO"/>

        <appender-ref ref="CONSOLE"/>
        <appender-ref ref="FILE"/>


As you can see, the configuration file can be basically split in two areas:
Appender: this is the class file which directs the actual logging to a destination. It could be a simple Console appender which dumps the log messages to stdout (screen) or a file appender, which sends the log messages to a log file

Category: (formerly known as Logger) connects the classes from a package to one or more appenders.

In our example, we have defined 2 appenders: one which logs statements to the Server console (equivalent to the System.out) and another which uses a DailyRollingFileAppender to append logs to the file server.log.

We have also added a category definition (for the package com.sample) which specifies the minimum priority of messages that will be generated. The purpose of the categories is to limit the log messages produced by components to a level that makes sense. (Note In our example the message doesn’t show up on the console since the threshold on the console is INFO)

The last part of the configuration is the Root logger. All loggers which are not defined through a category, inherit from the Root logger which collects messages from both the CONSOLE appender and the FILE appender.

JBoss’s log4j specific configuration

Log4j configuration is handled by the MBean org.jboss.logging.Log4jService. You can configure it in the JBOSS_HOME/server/default/conf/jboss-service.xml file.

 <mbean code="org.jboss.logging.Log4jService"
 <attribute name="ConfigurationURL">resource:jboss-log4j.xml</attribute>
 <attribute name="Log4jQuietMode">true</attribute>
 <attribute name="RefreshPeriod">60</attribute>

Here, you can configure the log4j resource name (jboss-log4j.xml) and the RefreshPeriod, which states how frequently in seconds the ConfigurationURL is checked for changes.

Using log4j in your application

Once you have configured the main log4j configuration file you don’t need adding any library since log4j JBoss AS already ships with all the necessary libraries.
Just define a static org.apache.log4j.Logger instance and link it to your class. For example in an HelloWorld class you would log this way:

import org.apache.log4j.Logger

public class HelloWorld {
 static Logger logger = Logger.getLogger(HelloWorld.class);
 // ...

  public void doSomething() {
   logger.debug("This is a debug statement");

Creating a custom appender

The sample configuration can be furtherly expanded by defining new appenders or categories. For example, if you want to append your application specific logs to another file, you you can define a new File appender so that application logs don’t mix the server-related File appender.

 <appender name="CUSTOM"
  <errorHandler class="org.jboss.logging.util.OnlyOnceErrorHandler"/>
  <param name="File"        value="${jboss.server.home.dir}/log/custom.log"/>
  <param name="Append"      value="false"/>
  <param name="DatePattern" value="'.'yyyy-MM-dd"/>
  <layout class="org.apache.log4j.PatternLayout">
  <param name="ConversionPattern" value="%d %-5p [%c] %m%n"/>

This appender will be picked up by the Root category or by a custom defined category as in this sample:

<category name="com.sample">   <priority value="DEBUG" />   <appender-ref ref="CUSTOM"/> </category>

Here, all logs emitted by the package com.sample with a priority DEBUG or higher will use the CUSTOM appender.

Using a custom log4j configuration file

The above configuration requires that you adapt the JBoss log4j file to your needs. This is not usually the best option because you should rather provide a custom configuration along with your application.

If you have already tried to pack log4j configuration along with your application, you might be disappointed that it doesn’t emit any logging statement. Why ? since the log4j framework is already packed in the server lib and configuration you need to deploy your application in isolate classloader mode so that it doesn’t conflict with the server logging system.

Isolating your application requires a simple three step process:

1) Add a jboss-web.xml (Web application) or jboss-app.xml (Enterprise App) declaring claassloader isolation
2) Add the log4j.jar along with your application ( because it will not be loaded anymore from the server lib )
3) Add the log4j.xml (or log4j.properties) to your application

Let’s see how you need to pack your Web application in order to use a custom log4j configuration (ScreenShots from Eclipse)

jboss log4j tutorial logging configuration
As you can see we have packed the configuration file (jboss-log4j.xml) in the src folder, so that it will be moved to the WEB-INF/classes folder once we distribute the application.The file log4j.jar is added in the Web application library.

Finally we need to add in the WEB-INF folder the jboss-web.xml declaring the classloader isolation. Here’s an example:

  <class-loading java2ClassLoadingCompliance="false"> 

The same steps can be performed on an Enterprise Archive– the main difference will be that we need rather a jboss-app.xml file to declare classloader isolation. You also need to pack log4j.jar in the “lib” folder of your .ear and your configuration file in the root of your .ear.Here’s eclipse screenshot:

jboss log4j eclipse configuration
Here’s a sample jboss-app.xml file:


JBoss 5 Classloader issue
The AS5 deployers ignore the previous classloader configuration just defined. Instead, for a  scoped deployment, users will be required to create a META-INF/jboss-classloading.xml:

<classloading xmlns="urn:jboss:classloading:1.0" domain="simple-scoped" 

 parent-first="false" />