| <?xml version="1.0"?> |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| #set($dollar = '$') |
| <document xmlns="http://maven.apache.org/XDOC/2.0" |
| xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" |
| xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd"> |
| <properties> |
| <title>JMX</title> |
| <author email="remkop@yahoo.com">Remko Popma</author> |
| </properties> |
| |
| <body> |
| <section name="JMX"> |
| <p> |
| Log4j 2 has built-in support for JMX. |
| The StatusLogger, ContextSelector, and all LoggerContexts, |
| LoggerConfigs and Appenders are instrumented with MBeans and can |
| be remotely monitored and controlled. |
| </p> |
| <p>Also included is a simple client GUI that can be used to |
| monitor the StatusLogger output, as well as to remotely reconfigure |
| Log4j with a different configuration file, or to edit the |
| current configuration directly. |
| </p> |
| </section> |
| <section name="Enabling JMX"> |
| <a name="Enabling_JMX" /> |
| <p>JMX support is enabled by default. When Log4j initializes, |
| the StatusLogger, ContextSelector, and all LoggerContexts, |
| LoggerConfigs and Appenders are instrumented with MBeans. |
| To disable JMX completely, and prevent these MBeans from being created, |
| specify system property <tt>log4j2.disableJmx</tt> to <tt>true</tt> when you start |
| the Java VM. |
| </p> |
| <subsection name="Local Monitoring and Management"> |
| <a name="Local" /> |
| <p>To perform local monitoring you don't need to specify any system |
| properties. The JConsole tool that is included in the Java JDK can be |
| used to monitor your application. Start JConsole by typing |
| <code>${dollar}JAVA_HOME/bin/jconsole</code> in a command shell. |
| For more details, see Oracle's documentation on |
| <a href="http://docs.oracle.com/javase/7/docs/technotes/guides/management/jconsole.html">how to use JConsole</a>.</p> |
| </subsection> |
| <subsection name="Remote Monitoring and Management"> |
| <a name="Remote" /> |
| <p>To enable monitoring and management from remote systems, set the following system property when starting the Java VM. |
| </p><p> |
| <code>com.sun.management.jmxremote.port=portNum</code> |
| </p><p> |
| In the property above, <code>portNum</code> is the port number through |
| which you want to enable JMX RMI connections. |
| </p><p> |
| For more details, see Oracle's documentation on |
| <a href="http://docs.oracle.com/javase/7/docs/technotes/guides/management/agent.html#gdenl">Remote |
| Monitoring and Management</a>.</p> |
| </subsection> |
| <subsection name="RMI impact on Garbage Collection"> |
| <a name="RMI_GC" /> |
| <p> |
| Be aware that RMI by default triggers a full GC every hour. |
| See the <a href="http://docs.oracle.com/javase/7/docs/technotes/guides/rmi/sunrmiproperties.html">Oracle |
| documentation</a> for the <code>sun.rmi.dgc.server.gcInterval</code> and <code>sun.rmi.dgc.client.gcInterval</code> properties. |
| The default value of both properties is 3600000 milliseconds (one hour). Before Java 6, it was one minute. |
| </p><p> |
| The two sun.rmi arguments reflect whether your JVM is running in server or client mode. |
| If you want to modify the GC interval time it may be best to specify both properties to ensure the argument is picked up by the JVM. |
| </p><p> |
| An alternative may be to disable explicit calls to <code>System.gc()</code> altogether with |
| <code>-XX:+DisableExplicitGC</code>, or (if you are using the CMS or G1 collector) |
| add <code>-XX:+ExplicitGCInvokesConcurrent</code> to ensure the full GCs are done |
| concurrently in parallel with your application instead of forcing a stop-the-world collection. |
| </p> |
| </subsection> |
| </section> |
| <section name="Log4j Instrumented Components"> |
| <a name="Log4j_MBeans" /> |
| <p>The best way to find out which methods and attributes of the various |
| Log4j components are accessible via JMX is to look at the |
| <a href="../log4j-core/apidocs/org/apache/logging/log4j/core/jmx/package-summary.html" |
| >Javadoc</a> or by exploring directly in JConsole.</p> |
| <p>The screenshot below shows the Log4j MBeans in JConsole.</p> |
| <p><img src="../images/jmx-jconsole-mbeans.png" alt="JConsole screenshot of the MBeans tab" /></p> |
| </section> |
| <section name="Client GUI"> |
| <a name="ClientGUI" /> |
| <p>Log4j includes a basic client GUI that can be used to |
| monitor the StatusLogger output and to remotely modify the Log4j |
| configuration. The client GUI can be run as a stand-alone application |
| or as a JConsole plug-in.</p> |
| <subsection name="Running the Client GUI as a JConsole Plug-in"> |
| <p>To run the Log4j JMX Client GUI as a JConsole Plug-in, |
| start JConsole with the following command: |
| </p> |
| <p><code>${dollar}JAVA_HOME/bin/jconsole -pluginpath /path/to/log4j-api-${Log4jReleaseVersion}.jar:/path/to/log4j-core-${Log4jReleaseVersion}.jar:/path/to/log4j-jmx-gui-${Log4jReleaseVersion}.jar</code></p> |
| <p>or on Windows:</p> |
| <p><code>%JAVA_HOME%\bin\jconsole -pluginpath \path\to\log4j-api-${Log4jReleaseVersion}.jar;\path\to\log4j-core-${Log4jReleaseVersion}.jar;\path\to\log4j-jmx-gui-${Log4jReleaseVersion}.jar</code></p> |
| <p>If you execute the above command and connect to your application, |
| you will see an extra "Log4j 2" tab in the JConsole window. |
| This tab contains the client GUI, with the StatusLogger selected. |
| The screenshot below shows the StatusLogger panel in JConsole. |
| </p> |
| <p><img src="../images/jmx-jconsole-statuslogger.png" alt="JConsole screenshot of the StatusLogger display" /></p> |
| </subsection> |
| <subsection name="Remotely Editing the Log4j Configuration"> |
| <p>The client GUI also contains a simple editor that can be used |
| to remotely change the Log4j configuration. |
| </p><p> |
| The screenshot below shows the configuration edit panel in JConsole. |
| </p> |
| <p><img src="../images/jmx-jconsole-editconfig.png" alt="JConsole screenshot of the configuration file editor" /></p> |
| <p>The configuration edit panel provides two ways to modify |
| the Log4j configuration: specifying a different configuration location |
| URI, or modifying the configuration XML directly in the editor panel.</p> |
| <p>If you specify a different configuration location URI and |
| click the "Reconfigure from Location" button, the specified file |
| or resource must exist and be readable by the application, |
| or an error will occur and the configuration will not change. |
| If an error occurred while processing the contents of the specified resource, |
| Log4j will keep its original configuration, but the editor panel |
| will show the contents of the file you specified. </p> |
| <p> |
| The text area showing the contents of the configuration file is |
| editable, and you can directly modify the configuration in this |
| editor panel. Clicking the "Reconfigure with XML below" button will |
| send the configuration text to the remote application where it |
| will be used to reconfigure Log4j on the fly. |
| This will not overwrite any configuration file. |
| Reconfiguring with text from the editor happens in memory only and |
| the text is not permanently stored anywhere. |
| </p> |
| </subsection> |
| <subsection name="Running the Client GUI as a Stand-alone Application"> |
| <a name="ClientStandAlone" /> |
| <p>To run the Log4j JMX Client GUI as a stand-alone application, |
| run the following command: |
| </p> |
| <p><code>${dollar}JAVA_HOME/bin/java -cp /path/to/log4j-api-${Log4jReleaseVersion}.jar:/path/to/log4j-core-${Log4jReleaseVersion}.jar:/path/to/log4j-jmx-gui-${Log4jReleaseVersion}.jar org.apache.logging.log4j.jmx.gui.ClientGui <options></code></p> |
| <p>or on Windows:</p> |
| <p><code>%JAVA_HOME%\bin\java -cp \path\to\log4j-api-${Log4jReleaseVersion}.jar;\path\to\log4j-core-${Log4jReleaseVersion}.jar;\path\to\log4j-jmx-gui-${Log4jReleaseVersion}.jar org.apache.logging.log4j.jmx.gui.ClientGui <options></code></p> |
| <p>Where <code>options</code> are one of the following:</p> |
| <ul> |
| <li><code><host>:<port></code></li> |
| <li><code>service:jmx:rmi:///jndi/rmi://<host>:<port>/jmxrmi</code></li> |
| <li><code>service:jmx:rmi://<host>:<port>/jndi/rmi://<host>:<port>/jmxrmi</code></li> |
| </ul> |
| <p>The port number must be the same as the portNum specified when |
| you started the application you want to monitor. |
| </p> |
| <p>For example, if you started your application with these options:</p> |
| <pre>com.sun.management.jmxremote.port=33445 |
| com.sun.management.jmxremote.authenticate=false |
| com.sun.management.jmxremote.ssl=false</pre> |
| <p><b>(Note that this disables <em>all</em> security so this is not recommended |
| for production environments. |
| Oracle's documentation on |
| <a href="http://docs.oracle.com/javase/7/docs/technotes/guides/management/agent.html#gdenl">Remote |
| Monitoring and Management</a> provides details on how to configure |
| JMX more securely with password authentication and SSL.)</b></p> |
| <p>Then you can run the client with this command:</p> |
| <p><code>${dollar}JAVA_HOME/bin/java -cp /path/to/log4j-api-${Log4jReleaseVersion}.jar:/path/to/log4j-core-${Log4jReleaseVersion}.jar:/path/to/log4j-jmx-gui-${Log4jReleaseVersion}.jar org.apache.logging.log4j.jmx.gui.ClientGui localhost:33445</code></p> |
| <p>or on Windows:</p> |
| <p><code>%JAVA_HOME%\bin\java -cp \path\to\log4j-api-${Log4jReleaseVersion}.jar;\path\to\log4j-core-${Log4jReleaseVersion}.jar;\path\to\log4j-jmx-gui-${Log4jReleaseVersion}.jar org.apache.logging.log4j.jmx.gui.ClientGui localhost:33445</code></p> |
| <p>The screenshot below shows the StatusLogger panel of the client |
| GUI when running as a stand-alone application.</p> |
| <p><img src="../images/jmx-standalone-statuslogger.png" alt="JMX GUI screenshot of StatusLogger display" /></p> |
| <p>The screenshot below shows the configuration editor panel of the |
| client GUI when running as a stand-alone application.</p> |
| <p><img src="../images/jmx-standalone-editconfig.png" alt="JMX GUI screenshot of configuration editor" /></p> |
| |
| </subsection> |
| </section> |
| |
| </body> |
| </document> |
