/usr/share/doc/liblogback-java/manual/jmxConfig.html is in liblogback-java-doc 1:1.1.3-2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
<link rel="stylesheet" type="text/css" href="../css/common.css" />
<link rel="stylesheet" type="text/css" href="../css/screen.css" media="screen" />
<link rel="stylesheet" type="text/css" href="../css/_print.css" media="print" />
<link rel="stylesheet" type="text/css" href="../css/prettify.css" media="screen" />
<title>Chapter 10: JMX Configuration</title>
</head>
<body onload="prettyPrint(); decorate();">
<script type="text/javascript">prefix='../';</script>
<script type="text/javascript" src="../js/prettify.js"></script>
<script type="text/javascript" src="../templates/header.js"></script>
<script type="text/javascript" src="../js/jquery-min.js"></script>
<script type="text/javascript" src="../js/decorator.js"></script>
<div id="left">
<noscript>Please turn on Javascript to view this menu</noscript>
<script src="../templates/left.js" type="text/javascript"></script>
</div>
<div id="right">
<script src="menu.js" type="text/javascript"></script>
</div>
<div id="content">
<h1>Chapter 10: JMX Configurator</h1>
<p>As its name indicates, <code>JMXConfigurator</code> allows
configuration of logback via JMX. In a nutshell, it lets you
reconfigure logback from the default configuration file, from a
designated file or URL, list loggers and modify logger levels.
</p>
<h3>Using the JMX Configurator</h3>
<p>If your server run on JDK 1.6 or later, then you can just
invoke the <code>jconsole</code> application on the command line and
then connect to your server's MBeanServer. If you are running an
older JVM, then you should read the section on <a
href="#jmxEnablingServer">JMX enabling your server</a>.
</p>
<p><code>JMXConfigurator</code> is enabled by a single line in
your logback configuration file, as shown below:
</p>
<pre class="prettyprint source"><configuration>
<b><jmxConfigurator /></b>
<appender name="console" class="ch.qos.logback.core.ConsoleAppender">
<layout class="ch.qos.logback.classic.PatternLayout">
<Pattern>%date [%thread] %-5level %logger{25} - %msg%n</Pattern>
</layout>
</appender>
<root level="debug">
<appender-ref ref="console" />
</root>
</configuration></pre>
<p>After you connect to your server with <em>jconsole</em>, on the
MBeans panel, under "ch.qos.logback.classic.jmx.Configurator"
folder you should see several operations to choose from, as shown
in the figure below:
</p>
<h3 class="doAnchor" name="jmxConfigurator">Screen-shot of
<code>JMXConfigurator</code> viewed in <code>jconsole</code></h3>
<img src="images/chapters/jmxConfigurator/jmxConfigurator.gif" alt="jmxConfigurator"/>
<p>Thus, you can</p>
<ul>
<li>Reload logback configuration using the default configuration
file.</li>
<li>Reload the configuration with the specified URL.</li>
<li>Reload the configuration with the specified file.</li>
<li>Set the level of a specified logger. To set to null, pass
the string "null" as value.</li>
<li>Get the level of a specified logger. The returned value can be
null.</li>
<li>Get the <a href="architecture.html#effectiveLevel">effective
level</a> of a specified logger.</li>
</ul>
<p><code>JMXConfigurator</code> exposes the list of existing
loggers and a status list as attributes.</p>
<p>The status list can help you diagnose logback's internal
state.</p>
<img src="images/chapters/jmxConfigurator/statusList.gif" alt="statusList.gif"/>
<h3 class="doAnchor" name="leak">Avoiding memory leaks</h3>
<p>If your application is deployed in a web-server or an
application server, the registration of an
<code>JMXConfigurator</code> instance creates a reference from the
system class loader into your application which will prevent it
from being garbage collected when it is stopped or re-deployed,
resulting in a severe memory leak.</p>
<p>Thus, unless your application is a standalone Java application,
you MUST unregister the <code>JMXConfigurator</code> instance from
the JVM's Mbeans server. Invoking the <code>reset</code>() method
of the appropriate <code>LoggerContext</code> will automatically
unregister any JMXConfigurator instance. A good place to reset the
logger context is in the <code>contextDestroyed</code>()
method of a
<code>javax.servlet.ServletContextListener</code>. Here is sample
code:</p>
<pre class="prettyprint source">import javax.servlet.ServletContextEvent;
import javax.servlet.ServletContextListener;
import org.slf4j.LoggerFactory;
import ch.qos.logback.classic.LoggerContext;
public class MyContextListener implements ServletContextListener {
public void contextDestroyed(ServletContextEvent sce) {
<b>LoggerContext lc = (LoggerContext) LoggerFactory.getILoggerFactory();</b>
<b>lc.stop();</b>
}
public void contextInitialized(ServletContextEvent sce) {
}
} </pre>
<!-- ============ Multiple web-applications ================== -->
<h2 class="doAnchor" name="multiple"><code>JMXConfigurator</code>
with multiple web-applications</h2>
<p>If you deploy multiple web-applications in the same server,
and if you have not overridden the default <a
href="contextSelector.html">context selector</a>, and if you
have placed a copy of <em>logback-*.jar</em> and
<em>slf4j-api.jar</em> under the <em>WEB-INF/lib</em> folder of
each web-application, then by default each <code>JMXConfigurator</code>
instance will be registered under the same name, that is,
"ch.qos.logback.classic:Name=default,Type=ch.qos.logback.classic.jmx.JMXConfigurator". In
other words, by default the various <code>JMXConfigurator</code>
instances associated with the logger contexts in each of your
web-applications will collide.
</p>
<p>To avoid such undesirable collisions, you simply <a
href="configuration.html#contextName">set the name of your
application's logging context</a> and <code>JMXConfigurator</code>
will automatically use the name you have set.
</p>
<p>For example, if you deploy two web-applications named "Koala"
and "Wombat", then you would write in Koala's logback
configuration
</p>
<pre class="prettyprint source"><configuration>
<b><contextName>Koala</contextName></b>
<jmxConfigurator/>
...
<configuration></pre>
<p>and in Wombat logback configuration file, you would write:</p>
<pre class="prettyprint source"><configuration>
<b><contextName>Wombat</contextName></b>x
<jmxConfigurator/>
...
<configuration></pre>
<p>In jconsole's MBeans panel, you would see two distinct
<code>JMXConfigurator</code> instances:</p>
<img src="images/chapters/jmxConfigurator/multiple.gif" alt="multiple.gif"/>
<p>You may fully control the name under which JMXConfigurator is
registered with an MBeans server with the help of the "objectName"
attribute of the <code><jmxConfigurator></code> element.</p>
<!-- ============ JMX enabling your server ================== -->
<h3 class="doAnchor" name="jmxEnablingServer">JMX enabling your
server</h3>
<p>If your server runs with JDK 1.6 or later, your server should
be JMX enabled by default.</p>
<p>For older JVMs, we suggest that you refer to the JMX-related
documentation of your web-server. Such documentation is available
for both <a
href="http://tomcat.apache.org/tomcat-6.0-doc/monitoring.html">Tomcat</a>
and <a
href="http://docs.codehaus.org/display/JETTY/JMX">Jetty</a>. In
this document, we briefly describe the required configuration
steps for Tomcat and Jetty.
</p>
<!-- ================ Configuring Jetty ================== -->
<h4>Enabling JMX in Jetty (tested under JDK 1.5 and JDK 1.6)</h4>
<p>The following has been tested under JDK 1.5 and 1.6. Under JDK
1.6 and later, your server is JMX enabled by default and you can,
but do not need to, follow the steps discussed below. Under JDK
1.5, adding JMX support in Jetty requires a number of additions to
the <em>$JETTY_HOME/etc/jetty.xml</em> configuration file. Here
are the elements that need to be added:
</p>
<pre class="prettyprint source"><Call id="MBeanServer" class="java.lang.management.ManagementFactory"
name="getPlatformMBeanServer"/>
<Get id="Container" name="container">
<Call name="addEventListener">
<Arg>
<New class="org.mortbay.management.MBeanContainer">
<Arg><Ref id="MBeanServer"/></Arg>
<Call name="start" />
</New>
</Arg>
</Call>
</Get> </pre>
<p>If you wish to access the MBeans exposed by Jetty via the
<code>jconsole</code> application, then you need to start Jetty after
having set the "com.sun.management.jmxremote" Java system
property.
</p>
<p>For a standalone version of Jetty, this translates to: </p>
<p class="source">java <b>-Dcom.sun.management.jmxremote</b> -jar start.jar [config files]</p>
<p>And if you wish to launch Jetty as a Maven plugin, then you
need to set the "com.sun.management.jmxremote" system property via
the <code>MAVEN_OPTS</code> shell variable:
</p>
<p class="source"><b>MAVEN_OPTS="-Dcom.sun.management.jmxremote</b>"
mvn jetty:run</p>
<p>You can then access the MBeans exposed by Jetty as well as
logback's <code>JMXConfigurator</code> via
<code>jconsole</code>.</p>
<img src="images/chapters/jmxConfigurator/jconsole15_jetty.gif" alt="jconsole15_jetty.gif"/>
<p>After you are connected, you should be able to access
<code>JMXXConfigurator</code> as shown in the <a
href="#jmxConfigurator">screenshot</a> above.</p>
<h4>MX4J with Jetty (tested under JDK 1.5 and 1.6)</h4>
<p>If you wish to access <code>JMXConfigurator</code> via MX4J's
HTTP interface and assuming you have already downloaded <a
href="http://mx4j.sourceforge.net/">MX4J</a>, you then need to
modify the Jetty configuration file discussed previously by adding
an instruction to set the management port.
</p>
<pre class="prettyprint source"><Call id="MBeanServer"
class="java.lang.management.ManagementFactory"
name="getPlatformMBeanServer"/>
<Get id="Container" name="container">
<Call name="addEventListener">
<Arg>
<New class="org.mortbay.management.MBeanContainer">
<Arg><Ref id="MBeanServer"/></Arg>
<b><Set name="managementPort">8082</Set></b>
<Call name="start" />
</New>
</Arg>
</Call>
</Get>
</pre>
<p>Moreover, <em>mx4j-tools.jar</em> needs to be added to Jetty's
class path.
</p>
<p>If you are running Jetty as a Maven plug-in, then you need to add
<em>mx4j-tools</em> as a dependency.</p>
<pre class="prettyprint source"><plugin>
<groupId>org.mortbay.jetty</groupId>
<artifactId>maven-jetty-plugin</artifactId>
<configuration>
<jettyConfig>path/to/jetty.xml</jettyConfig>
...
</configuration>
<b><dependencies>
<dependency>
<groupId>mx4j</groupId>
<artifactId>mx4j-tools</artifactId>
<version>3.0.1</version>
</dependency>
</dependencies></b>
</plugin></pre>
<p>After Jetty is started with the above configuration,
<code>JMXConfigurator</code> will be available at the following
URL (search for "ch.qos.logback.classic"):
</p>
<p class="source"><a href="http://localhost:8082/">http://localhost:8082/</a></p>
<p>Below is a screen shot view of the MX4J interface.</p>
<img src="images/chapters/jmxConfigurator/mx4j_jetty.gif" alt="mx4j_jetty.gif"/>
<!-- ================ Tomcat ================== -->
<h4>Configuring JMX for Tomcat (tested under JDK 1.5 and 1.6)</h4>
<p>If you are using JDK 1.6 and later, your server is already JMX
enabled by default and you can, but do not need to, follow the
steps discussed below. Under JDK 1.5, Tomcat requires the addition
of the following lines to the
<em>$TOMCAT_HOME/bin/catalina.bat/sh</em> shell script:
</p>
<p class="source">CATALINA_OPTS="-Dcom.sun.management.jmxremote"</p>
<p>Once started with these options, MBeans exposed by Tomcat as
well logback's <code>JMXConfigurator</code> can be accessed with
<code>jconsole</code> by issuing the following command in a shell:
</p>
<p class="source">jconsole</p>
<img src="images/chapters/jmxConfigurator/jconsole15_tomcat.gif" alt="jconsole15_tomcat.gif"/>
<p>After you are connected, you should be able to access
<code>JMXXConfigurator</code> as shown in the <a
href="#jmxConfigurator">screenshot</a> above.</p>
<h4>MX4J with Tomcat (tested under JDK 1.5 and 1.6)</h4>
<p>You might prefer to access JMX components via a web-based
interface provided by MX4J. In that case, here are the required
steps:
</p>
<p>Assuming you have already downloaded <a
href="http://mx4j.sourceforge.net/">MX4J</a>, place the
<em>mx4j-tools.jar</em> file under the <em>$TOMCAT_HOME/bin/</em>
directory. Then, add the following lines to the
<em>$TOMCAT_HOME/bin/catalina.sh</em> configuration file:
</p>
<p class="source"><!-- at the beginning of the file -->
CATALINA_OPTS="-Dcom.sun.management.jmxremote"
<!-- in the "Add on extra jar files to CLASSPATH" section -->
CLASSPATH="$CLASSPATH":"$CATALINA_HOME"/bin/mx4j-tools.jar</p>
<p>Finally, declare a new <code>Connector</code> in the
<em>$TOMCAT_HOME/conf/server.xml</em> file:
</p>
<pre class="prettyprint source"><Connector port="0"
handler.list="mx"
mx.enabled="true"
mx.httpHost="localhost"
mx.httpPort="8082"
protocol="AJP/1.3" /></pre>
<p>Once Tomcat is started, you should be able to find
JMXConfigurator by pointing your browser at the following URL
(search for "ch.qos.logback.classic"):
</p>
<p class="source"><a href="http://localhost:8082">http://localhost:8082/</a></p>
<p>Below is a screen shot view of the MX4J interface.</p>
<img src="images/chapters/jmxConfigurator/mx4j_tomcat.gif" alt="mx4j_tomcat.gif"/>
<script src="../templates/footer.js" type="text/javascript"></script>
</div>
</body>
</html>
|