JMX Configurator

As of version 0.8, logback ships with a component that allows configuration via JMX. Basically, it lets you reload the current configuration, load a new one, list loggers and modify logger levels.

Configuring your server

The first step is to make sure that your application server will allow the JMX Configurator to publish itself. In this document, we'll cover the necessary steps in Tomcat and Jetty.

Configuring Tomcat

Accessing JMX components with Tomcat requires to add the following lines to the $TOMCAT_HOME/bin/catalina.sh configuration file:

CATALINA_OPTS="-Dcom.sun.management.jmxremote"
CATALINA_OPTS="$CATALINA_OPTS -Dcom.sun.management.jmxremote.ssl=false"
CATALINA_OPTS="$CATALINA_OPTS -Dcom.sun.management.jmxremote.authenticate=false"

Once started with these options, Tomcat's JMX compoenents can be accessed with JConsole by issuing the following command in a shell:

jconsole &

You might prefer to access your components via a web-based solution using MX4J. In that case, here are the required steps:

First, download MX4J. Place the mx4j-impl.jar file in the $TOMCAT_HOME/bin/ directory, and the mx4j-tools.jar in the $TOMCAT_HOME/common/lib/ directory.

Then, add the following lines to the $TOMCAT_HOME/bin/catalina.sh configuration file:

<!-- at the beginning of the file -->
CATALINA_OPTS="-Dcom.sun.management.jmxremote"
CATALINA_OPTS="$CATALINA_OPTS -Djavax.management.builder.initial=mx4j.server.MX4JMBeanServerBuilder"

<!-- in the "Add on extra jar files to CLASSPATH" section -->
CLASSPATH="$CLASSPATH":"$CATALINA_HOME"/bin/mx4j-impl.jar

Finally, declare a new Connector in the $TOMCAT_HOME/conf/server.xml file:

<Connector port="8050" 
  handler.list="mx"
  mx.enabled="true" 
  mx.httpHost="localhost" 
  mx.httpPort="8082" 
  protocol="AJP/1.3" />

Once Tomcat is started, you should be ableo to reach the JMX components by pointing a browser to the following URL:

http://host_name:8082/

Configuring Jetty

Configuring Jetty to publish JMX components requires a few modifications to the $JETTY_HOME/etc/jetty.xml configuration file. Here are the elements that need to be added:

<Call id="MBeanServer" class="java.lang.management.ManagementFactory" name="getPlatformMBeanServer"/>
<!-- initialize the Jetty MBean container -->
<Get id="Container" name="container">
  <Call name="addEventListener">
    <Arg>
      <New class="org.mortbay.management.MBeanContainer">
        <Arg><Ref id="MBeanServer"/></Arg>
        <Set name="managementPort">8082</Set>
        <Call name="start" />
      </New>
    </Arg>
  </Call>
</Get>

Once Jetty is started with this configuration, all available components can be reviewed at this address:

http://host_name:8082/

Using the JMX Configurator

The next step is to declare the JMX Configurator in the logback configuration file. This is done by adding a single element, as shown below:

<configuration>

  <jmxConfigurator />

  <appender name="console" class="ch.qos.logback.classic.ConsoleAppender">
    <layout class="ch.qos.logback.classic.PatternLayout">
      <Pattern>%date [%thread] %-5level %logger{25} - %msg%n</Pattern>
    </layout>
  </appender>

  <root>
    <level value="debug"/>
    <appender-ref ref="console" />
  </root>  
</configuration>

Once the JMX Configurator is displayed on your screen, there are several operations available.

Display the logback Statuses

Reload the configuration using the same file that was previously used.

Reload the configuration using a file whose path is passed as a parameter.

Reload the configuration using a file whose URL is passed as a parameter.

Get the level of a logger

Change the level setting of a specified logger.

Change a list of all declared loggers.

Change the level setting of a specified logger.

In the last case, you must specify the name of the logger you wish to alter, and its new level.

The level of a logger is a value that can be null, if no specific level has been configured for said logger. Its effective level, on the other hand, is given with respect to the parent loggers' levels. This value cannot be null, since all loggers are direct or indirect children of the root logger, whose level is always set. When trying to get the level or effective level of a logger, the name of the logger has to be passed as a parameter. Note that trying to get the level or effective level for a nonexistent logger will not return any result.

Displaying logback Statuses via JMX can help users check the internal state of logback. It shows if anything has gone wrong, if rollovers occured as expected, and many other useful informations. It is also very useful when reloading a configuration, since the user can immediately see if the configuration file was successfully processed.