<?xml version="1.0"?>
<document>

  <properties>
    <author email="ceki at qos ddoott ch ">Ceki Gulcu</author>
    <author email="sebastien at qos ddoott ch ">Sebastien Pennec</author>
    <title>JMX Configurator</title>
  </properties>
  
	<body>

    <h2>JMX Configurator</h2>
    
		<p>
			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.
		</p>
		
		<h3>Configuring your server</h3>
		<p>
			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.
		</p>
		
		<h4>Configuring Tomcat</h4>
		<p>
			Accessing JMX components with Tomcat requires to add the following lines
			to the <em>$TOMCAT_HOME/bin/catalina.sh</em> configuration file:
		</p>
		
<div class="source"><pre>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"</pre></div>

		<p>
			Once started with these options, Tomcat's JMX compoenents can be accessed
			with JConsole by issuing the following command in a shell:
		</p>
<div class="source"><pre>jconsole &amp;</pre></div>

		<p>
			You might prefer to access your components via a web-based solution using MX4J. 
			In that case, here are the required steps:
		</p>
		
		<p>
			First, <a href="http://mx4j.sourceforge.net/">download MX4J</a>. 
			Place the <em>mx4j-impl.jar</em> file in
			the <em>$TOMCAT_HOME/bin/</em> directory, and the <em>mx4j-tools.jar</em>
			in the <em>$TOMCAT_HOME/common/lib/</em> directory.
		</p>
		
		<p>Then, add the following lines to the
		<em>$TOMCAT_HOME/bin/catalina.sh</em> configuration file:
		</p>

<div class="source"><pre>&lt;!-- at the beginning of the file -->
CATALINA_OPTS="-Dcom.sun.management.jmxremote"
CATALINA_OPTS="$CATALINA_OPTS -Djavax.management.builder.initial=mx4j.server.MX4JMBeanServerBuilder"

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

		<p>
			Finally, declare a new <code>Connector</code> in the
			<em>$TOMCAT_HOME/conf/server.xml</em> file:
		</p>
		
<div class="source"><pre>&lt;Connector port="8050" 
  handler.list="mx"
  mx.enabled="true" 
  mx.httpHost="localhost" 
  mx.httpPort="8082" 
  protocol="AJP/1.3" /></pre></div>
  
  	<p>
  		Once Tomcat is started, you should be ableo to reach the JMX components by
  		pointing a browser to the following URL:
  	</p>

<div class="source"><pre>http://host_name:8082/</pre></div>

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

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

		<p>
			Once Jetty is started with this configuration, all available components can be reviewed
			at this address:
		</p>
<div class="source"><pre>http://host_name:8082/</pre></div>


		<h3>Using the JMX Configurator</h3>
		
		<p>
			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:
		</p>

<div class="source"><pre>&lt;configuration>

  <b>&lt;jmxConfigurator /></b>

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

  &lt;root>
    &lt;level value="debug"/>
    &lt;appender-ref ref="console" />
  &lt;/root>  
&lt;/configuration></pre></div>
		
		<p>
			Once the JMX Configurator is displayed on your screen, there are
			several operations available.
		</p>
		
		<ul>
			<p>Reload the configuration using the same file that was previously
			used.
			</p>
			<p>Reload the configuration using a file whose path is passed as
			a parameter.</p>
			<p>
				Reload the configuration using a file whose URL is passed as a
				parameter.
			</p>
			<p>
				Get the level of a logger
			</p>
			<p>
				Change the level setting of a specified logger.
			</p>
			<p>
				Change a list of all declared loggers.
			</p>
			<p>
				Change the level setting of a specified logger.
			</p>
		</ul>
		
		<p>
			In the last case, you must specify the name of the logger you wish to
			alter, and its new level.
		</p>
		<p>
			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.
		</p>
		

	</body>
</document>