Author: ceki Date: Mon Nov 10 19:03:37 2008 New Revision: 1954 Added: logback/trunk/logback-site/src/site/pages/manual/jmxConfig.html - copied, changed from r1859, /logback/trunk/logback-site/src/site/pages/jmxConfig.html logback/trunk/logback-site/src/site/resources/manual/images/chapter9/ logback/trunk/logback-site/src/site/resources/manual/images/chapter9/jconsole15_jetty.gif (contents, props changed) logback/trunk/logback-site/src/site/resources/manual/images/chapter9/jconsole15_tomcat.gif (contents, props changed) logback/trunk/logback-site/src/site/resources/manual/images/chapter9/jmxConfigurator.gif (contents, props changed) logback/trunk/logback-site/src/site/resources/manual/images/chapter9/statusList.gif (contents, props changed) Removed: logback/trunk/logback-site/src/site/pages/jmxConfig.html Modified: logback/trunk/logback-site/src/site/pages/css/print.css logback/trunk/logback-site/src/site/pages/documentation.html logback/trunk/logback-site/src/site/pages/manual/architecture.html logback/trunk/logback-site/src/site/pages/manual/index_menu.js logback/trunk/logback-site/src/site/pages/news.html Log: - moved jmxConfig.html under manual/jmxConfig.html - updated chapter on JMX support - updated news.html - other minor changes in documentation Modified: logback/trunk/logback-site/src/site/pages/css/print.css ============================================================================== --- logback/trunk/logback-site/src/site/pages/css/print.css (original) +++ logback/trunk/logback-site/src/site/pages/css/print.css Mon Nov 10 19:03:37 2008 @@ -35,4 +35,17 @@ table.bodyTable th { vertical-align: text-top; text-align:center; -} \ No newline at end of file +} + + +.source { + background:#eee; + border-top: 1px solid #DDDDDD; + border-bottom: 1px solid #DDDDDD; + font-family: Courier, "MS Courier New", Prestige, Everson Monocourrier, monospace; + padding-bottom: 0.5ex; + padding-top: 0.5ex; + padding-left: 1ex; + white-space: pre; +} + Modified: logback/trunk/logback-site/src/site/pages/documentation.html ============================================================================== --- logback/trunk/logback-site/src/site/pages/documentation.html (original) +++ logback/trunk/logback-site/src/site/pages/documentation.html Mon Nov 10 19:03:37 2008 @@ -40,10 +40,7 @@ <li> <a href="joran.html">Using Joran in your applications</a> </li> - - <li> - <a href="jmxConfig.html">How to use the logback JMX Configurator</a> - </li> + <li> <a href="demo.html">Walk-through logback-demo webApp</a> </li> @@ -69,13 +66,21 @@ <h2>Articles and Presentations</h2> <ul> + <li><a + href="http://ekkes-corner.blogspot.com/2008/10/index-blogseries-logging-in-osgi.html">Logging + in OSGI Enterprise Applications</a>, by Ekkehard Gentz. + + </li> <li><a href="10reasons.ppt">Top 10 reasons for migrating to logback</a>, by Ceki Gülcü and Sébastien Pennec. </li> + + <li><a href="http://www.infoq.com/news/2007/08/logback">Logback: Evolving Java Logging</a> by Geoffrey Wiseman + </li> </ul> Modified: logback/trunk/logback-site/src/site/pages/manual/architecture.html ============================================================================== --- logback/trunk/logback-site/src/site/pages/manual/architecture.html (original) +++ logback/trunk/logback-site/src/site/pages/manual/architecture.html Mon Nov 10 19:03:37 2008 @@ -153,7 +153,9 @@ </p> <div class="definition"> - <div class="deftitle">Level Inheritance</div> + <div class="deftitle"><a name="effectiveLevel" + href="#effectiveLevel">Effective Level (Level Inheritance)</a></div> + <p>The effective level for a given logger <em>L</em>, is equal to the first non-null level in its hierarchy, starting at <em>L</em> itself and proceeding upwards in the hierarchy Modified: logback/trunk/logback-site/src/site/pages/manual/index_menu.js ============================================================================== --- logback/trunk/logback-site/src/site/pages/manual/index_menu.js (original) +++ logback/trunk/logback-site/src/site/pages/manual/index_menu.js Mon Nov 10 19:03:37 2008 @@ -8,4 +8,4 @@ document.write('<p class="menu"><a href="filters.html"><b>Ch6: Filter chains</b></a>'); document.write('<p class="menu"><a href="mdc.html"><b>Ch7: Mapped Diagnostic Contexts</b></a>'); document.write('<p class="menu"><a href="contextSelector.html"><b>Ch8: Context Selectors</b></a>'); - +document.write('<p class="menu"><a href="jmxConfig.html"><b>Ch9: JMX Configurator</b></a>'); Copied: logback/trunk/logback-site/src/site/pages/manual/jmxConfig.html (from r1859, /logback/trunk/logback-site/src/site/pages/jmxConfig.html) ============================================================================== --- /logback/trunk/logback-site/src/site/pages/jmxConfig.html (original) +++ logback/trunk/logback-site/src/site/pages/manual/jmxConfig.html Mon Nov 10 19:03:37 2008 @@ -3,187 +3,280 @@ <head> <meta http-equiv="content-type" content="text/html; charset=iso-8859-1" /> <title>JMX Configuration</title> -<link rel="stylesheet" type="text/css" media="screen" href="css/site.css" /> +<link rel="stylesheet" type="text/css" media="screen" href="../css/site.css" /> +<link rel="stylesheet" type="text/css" media="print" href="../css/print.css" /> + </head> <body> - <script> -prefix=''; -</script> - -<script src="templates/header.js"></script> -<div id="left"> - <script src="templates/left.js"></script> -</div> -<div id="content"> - - + <script> + prefix='../'; + </script> + <script src="../templates/header.js"></script> + <div id="left"> + <script src="../templates/left.js"></script> + </div> + <div id="right"> + <script src="index_menu.js"></script> + </div> + <div id="content"> <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>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>Configuring your server</h3> + <h3>Using the JMX Configurator</h3> + + + <p>If your server run on JDK 1.6 or later, then you can just + invoke <code>jconsole</code> application on the commmand 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>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><code>JMXConfigurator</code> is enabled by a single line in + your logback configuration file, as shown below: </p> + +<div class="source"><pre><configuration> + <b><jmxConfigurator /></b> + + <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></pre></div> - <h4>Configuring Tomcat</h4> + <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> - <p>Accessing JMX components with Tomcat requires to add the - following lines to the <em>$TOMCAT_HOME/bin/catalina.sh</em> - configuration file: - </p> + <img src="images/chapter9/jmxConfigurator.gif" alt="jmxConfigurator"/> + + <p>Thus, you can</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> + <ul> + <li>Reload logback configuration using the default configuration + file </li> - <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 &</pre></div> + <li>Reload the configuration with the specified URL</li> + <li>Reload the configuration with the specified file</li> - <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> + <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. Returned value can be + null.</li> + <li>Get the <a href="architecture.html#effectiveLevel">effective + level</a> of a specified logger</li> + </ul> - <p>Then, add the following lines to the - <em>$TOMCAT_HOME/bin/catalina.sh</em> configuration file: - </p> + <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 logbacks internal + state.</p> -<div class="source"><pre><!-- at the beginning of the file --> -CATALINA_OPTS="-Dcom.sun.management.jmxremote" -CATALINA_OPTS="$CATALINA_OPTS -Djavax.management.builder.initial=mx4j.server.MX4JMBeanServerBuilder" + <img src="images/chapter9/statusList.gif" alt="statusList.gif"/> -<!-- 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: + <!-- ============ JMX enabling your server ================== --> + + <h3> + <a name="jmxEnablingServer" href="#jmxEnablingServer">JMX enabling your + server</a> + </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 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 very briefly describe the required steps for + Tomcat and Jetty. </p> - -<div class="source"><pre><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 able to reach the JMX - components by pointing a browser to the following URL: - </p> -<div class="source"><pre>http://host_name:8082/</pre></div> + <!-- ================ Configuring Jetty ================== --> - <h4>Configuring Jetty</h4> + <h4>Enabling JMX in Jetty (tested under JDK 1.5 and JDK 1.6)</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>The following has been tested under JDK 1.5 and 1.6. Under 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, 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> -<div class="source"><pre><Call id="MBeanServer" class="java.lang.management.ManagementFactory" name="getPlatformMBeanServer"/> -<!-- initialize the Jetty MBean container --> + <p class="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> </p> + + <p>If you wish to access the MBeans exposed by Jetty with + jconsole, then you need start jetty with the + "com.sun.management.jmxremote" 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 set the "com.sun.management.jmxremote" system property via + the <code>MAVEN_OPTS</code> shell variable, as follows + </p> + + <p class="source"><b>MAVEN_OPTS="-Dcom.sun.management.jmxremote</b>" +mvn jetty:run</p> + + <p>You can then access via <code>jconsole</code>.</p> + + <img src="images/chapter9/jconsole15_jetty.gif" alt="jconsole15_jetty.gif"/> + + <h4>MX4J with Jetty (tested under JDK 1.5 and 1.6)</h4> + + <p>Assuming you have already downloaded <a + href="http://mx4j.sourceforge.net/">MX4J</a>, you then need to + modify the jetty configuration file by adding an instruction to + set the management port. + </p> + + <p class="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> - <Set name="managementPort">8082</Set> + <b><Set name="managementPort">8082</Set></b> <Call name="start" /> </New> </Arg> </Call> -</Get></pre></div> +</Get> + </p> + + <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> - <p>Once Jetty is started with this configuration, all available - components can be reviewed at this address: + <p class="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></p> + + <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> -<div class="source"><pre>http://host_name:8082/</pre></div> + <p class="source"><a href="http://localhost:8082/">http://localhost:8082/</a></p> - <h3>Using the JMX Configurator</h3> + <!-- ================ Tomcat ================== --> - <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: + <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> -<div class="source"><pre><configuration> + <p>Once started with these options, Tomcat's JMX compoenents can + be accessed with <code>jconsole</code> by issuing the following + command in a shell: + </p> + + <p class="source">jconsole</p> - <b><jmxConfigurator /></b> + <img src="images/chapter9/jconsole15_tomcat.gif" alt="jconsole15_tomcat.gif"/> - <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></pre></div> - - <p>Once the JMX Configurator is displayed on your screen, there - are several operations available. + <h4>MX4J with Tomcat</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> - <ul> - <li>Display the logback Status </li> + <p>Assuming you have already downloaded <a + href="http://mx4j.sourceforge.net/">MX4J</a>, placethe + <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> - <li>Reload the configuration using the same file that was previously - used. </li> + <p class="source"><!-- at the beginning of the file --> +CATALINA_OPTS="-Dcom.sun.management.jmxremote" - <li>Reload the configuration using a file whose path is passed - as a parameter.</li> +<!-- in the "Add on extra jar files to CLASSPATH" section --> +CLASSPATH="$CLASSPATH":"$CATALINA_HOME"/bin/mx4j-tools.jar</p> - <li>Reload the configuration using a file whose URL is passed as - a parameter.</li> + <p>Finally, declare a new <code>Connector</code> in the + <em>$TOMCAT_HOME/conf/server.xml</em> file: + </p> - <li>Get the level of a logger</li> - <li>Change the level setting of a specified logger.</li> - <li>Change a list of all declared loggers.</li> - <li>Change the level setting of a specified logger.</li> - </ul> - <p>In the last case, you must specify the name of the logger you - wish to alter, and its new level. - </p> + <p class="source"><Connector port="0" + handler.list="mx" + mx.enabled="true" + mx.httpHost="localhost" + mx.httpPort="8082" + protocol="AJP/1.3" /></p> + + <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>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> - - <p>Displaying logback status via JMX can help users check the - internal state of logback. It shows if anything has gone wrong, if - rollovers occured as expected, as well as other useful - information. It is also very useful when reloading a - configuration, since the user can immediately see if the - configuration file has been procsseds successfully. - </p> Modified: logback/trunk/logback-site/src/site/pages/news.html ============================================================================== --- logback/trunk/logback-site/src/site/pages/news.html (original) +++ logback/trunk/logback-site/src/site/pages/news.html Mon Nov 10 19:03:37 2008 @@ -27,25 +27,71 @@ <h3>28th of November 2008 - Release of version 0.9.12</h3> + <p>Fixed <a href="http://jira.qos.ch/browse/LBCORE-26">bug + LBCORE-26</a> reported by Tsutomu YANO and independently by + Hontvári József and Gamaliel + Amaudruz. <code>RollingFileAppender</code> when used in conjunction + with <code>DateBasedRollingPolicy</code> will rollover existing log + files at initialization if their timestamp warrants it. + </p> + + <p>Fixed <a + href="http://jira.qos.ch/browse/LBCLASSIC-83">LBCLASSIC-83</a>. It + is now possible to set the level of a logger to null, even if it was + previously set to a non-null level. Previously, a + <code>NullPointerException</code> would be thrown. + </p> + + <p>In reponse to <a + href="http://jira.qos.ch/browse/LBCLASSIC-61">LBCLASSIC-61</a>, <a + href="http://jira.qos.ch/browse/LBCLASSIC-33">LBCLASSIC-33</a>, <a + href="http://jira.qos.ch/browse/LBCLASSIC-14">LBCLASSIC-24</a> and + <a href="http://jira.qos.ch/browse/LBCLASSIC-24">LBCLASSIC-14</a> + JMXConfigurator has been redesigned. + </p> + + <p>Fixed improvement request <a + href="http://jira.qos.ch/browse/LBCLASSIC-59">LBCLASSIC-59</a> + relation to StatusListeners, originally submitted by Anton Tagunov. + </p> + + <p>In response to <a href="http://jira.qos.ch/browse/LBCLASSIC-54"> + LBCLASSIC-54</a> support for turbo filters has refactored. The + present code is safe under concurrent access while still offering + good performance. + </p> + <p>Fixed <a href="http://jira.qos.ch/browse/LBCORE-43">LBCORE-43</a> reported by Bruno Navert. Configuration files can now look up property files from classpath resources. </p> + + <!-- ======================== minor ================== --> + <p>Fixed <a href="http://jira.qos.ch/browse/LBCLASSIC-69">bug LBCLASSIC-69</a> reported by Anton Tagunov. The LevelToSyslogSeverity now correctly handles the TRACE level. </p> <p>Fixed <a href="http://jira.qos.ch/browse/LBCLASSIC-57">bug - LBCLASSIC-57</a> reported by Anton Tagunov. + LBCLASSIC-57</a> reported by Anton Tagunov. SyslogAppender could + overwhelm the Syslog server with very large messages. SyslogAppender + now limits its message size to 256K. </p> - <p>Fixed <a - href="http://jira.qos.ch/browse/LBCLASSIC-59">improvement request - LBCLASSIC-59</a> orignally made by Anton Tagunov. + + <p>Fixed issue <a + href="http://jira.qos.ch/browse/LBCLASSIC-49">LBCLASSIC-49</a> + reported by Oliver Lietz. The getLogger() method in + <code>LoggerContext</code> class will now throw an + <code>IllegalArgumentException</code> when invoked with a null + argument. </p> + + + <hr width="80%" align="center" /> <h3>28th of October 2008 - Release of version 0.9.11</h3> @@ -196,6 +242,7 @@ contributed by Ralph Goers in <a href="http://jira.qos.ch/browse/LBCLASSIC-53">LBCLASSIC-53</a>. </p> + <hr width="80%" align="center" /> Added: logback/trunk/logback-site/src/site/resources/manual/images/chapter9/jconsole15_jetty.gif ============================================================================== Binary file. No diff available. Added: logback/trunk/logback-site/src/site/resources/manual/images/chapter9/jconsole15_tomcat.gif ============================================================================== Binary file. No diff available. Added: logback/trunk/logback-site/src/site/resources/manual/images/chapter9/jmxConfigurator.gif ============================================================================== Binary file. No diff available. Added: logback/trunk/logback-site/src/site/resources/manual/images/chapter9/statusList.gif ============================================================================== Binary file. No diff available.