| <!DOCTYPE html> |
| <!-- |
| | Generated by Apache Maven Doxia Site Renderer 1.9.1 from src/site/xdoc/manual/jmx.xml.vm at 2020-02-25 |
| | Rendered using Apache Maven Fluido Skin 1.8 |
| --> |
| <html xmlns="http://www.w3.org/1999/xhtml" lang="en"> |
| <head> |
| <meta charset="UTF-8" /> |
| <meta name="viewport" content="width=device-width, initial-scale=1" /> |
| <meta name="generator" content="Apache Maven Doxia Site Renderer 1.9.1" /> |
| <meta name="author" content="Remko Popma" /> |
| <title>Log4j – JMX</title> |
| <link rel="stylesheet" href="../css/apache-maven-fluido-1.8.min.css" /> |
| <link rel="stylesheet" href="../css/site.css" /> |
| <link rel="stylesheet" href="../css/print.css" media="print" /> |
| <script src="../js/apache-maven-fluido-1.8.min.js"></script> |
| </head> |
| <body class="topBarDisabled"> |
| <div class="container-fluid"> |
| <header> |
| <div id="banner"> |
| <div class="pull-left"><a href="http://logging.apache.org" id="bannerLeft"><img src="../images/ls-logo.jpg" alt=""/></a></div> |
| <div class="pull-right"><a href="http://logging.apache.org/log4j/2.x" id="bannerRight"><img src="../images/logo.png" alt=""/></a></div> |
| <div class="clear"><hr/></div> |
| </div> |
| |
| <div id="breadcrumbs"> |
| <ul class="breadcrumb"> |
| <li id="publishDate">Last Published: 2020-02-25<span class="divider">|</span> |
| </li> |
| <li id="projectVersion">Version: 2.13.1</li> |
| <li class="pull-right"><span class="divider">|</span> |
| <a href="https://github.com/apache/logging-log4j2" class="externalLink" title="GitHub">GitHub</a></li> |
| <li class="pull-right"><span class="divider">|</span> |
| <a href="https://analysis.apache.org/dashboard/index/org.apache.logging.log4j:log4j" class="externalLink" title="Sonar">Sonar</a></li> |
| <li class="pull-right"><span class="divider">|</span> |
| <a href="../../../" title="Logging Services">Logging Services</a></li> |
| <li class="pull-right"><span class="divider">|</span> |
| <a href="https://www.apache.org/" class="externalLink" title="Apache">Apache</a></li> |
| <li class="pull-right"><a href="https://cwiki.apache.org/confluence/display/LOGGING/Log4j" class="externalLink" title="Logging Wiki">Logging Wiki</a></li> |
| </ul> |
| </div> |
| </header> |
| <div class="row-fluid"> |
| <header id="leftColumn" class="span2"> |
| <nav class="well sidebar-nav"> |
| <ul class="nav nav-list"> |
| <li class="nav-header"><img class="imageLink" src="../img/glyphicons/home.png" alt="Apache Log4j™ 2" border="0"/> Apache Log4j™ 2</li> |
| <li><a href="../index.html" title="About"><span class="none"></span>About</a></li> |
| <li><a href="../download.html" title="Download"><span class="none"></span>Download</a></li> |
| <li><a href="../javadoc.html" title="Javadoc"><span class="icon-chevron-right"></span>Javadoc</a></li> |
| <li><a href="../maven-artifacts.html" title="Maven, Ivy, Gradle Artifacts"><span class="icon-chevron-right"></span>Maven, Ivy, Gradle Artifacts</a></li> |
| <li><a href="../runtime-dependencies.html" title="Runtime Dependencies"><span class="none"></span>Runtime Dependencies</a></li> |
| <li><a href="../changelog.html" title="Changelog"><span class="none"></span>Changelog</a></li> |
| <li><a href="../faq.html" title="FAQ"><span class="none"></span>FAQ</a></li> |
| <li><a href="../performance.html" title="Performance"><span class="icon-chevron-right"></span>Performance</a></li> |
| <li><a href="../articles.html" title="Articles and Tutorials"><span class="none"></span>Articles and Tutorials</a></li> |
| <li><a href="../support.html" title="Support"><span class="none"></span>Support</a></li> |
| <li><a href="../thanks.html" title="Thanks"><span class="none"></span>Thanks</a></li> |
| <li class="nav-header"><img class="imageLink" src="../img/glyphicons/pencil.png" alt="For Contributors" border="0"/> For Contributors</li> |
| <li><a href="../build.html" title="Building Log4j from Source"><span class="none"></span>Building Log4j from Source</a></li> |
| <li><a href="../guidelines.html" title="Guidelines"><span class="none"></span>Guidelines</a></li> |
| <li><a href="../javastyle.html" title="Style Guide"><span class="none"></span>Style Guide</a></li> |
| <li class="nav-header"><img class="imageLink" src="../img/glyphicons/book.png" alt="Manual" border="0"/> Manual</li> |
| <li><a href="../manual/index.html" title="Introduction"><span class="none"></span>Introduction</a></li> |
| <li><a href="../manual/architecture.html" title="Architecture"><span class="none"></span>Architecture</a></li> |
| <li><a href="../manual/compatibility.html" title="Log4j 1.x Compatibility"><span class="none"></span>Log4j 1.x Compatibility</a></li> |
| <li><a href="../manual/migration.html" title="Log4j 1.x Migration"><span class="none"></span>Log4j 1.x Migration</a></li> |
| <li><a href="../manual/api.html" title="Java API"><span class="icon-chevron-right"></span>Java API</a></li> |
| <li><a href="../manual/scala-api.html" title="Scala API"><span class="none"></span>Scala API</a></li> |
| <li><a href="../manual/configuration.html" title="Configuration"><span class="icon-chevron-right"></span>Configuration</a></li> |
| <li><a href="../manual/usage.html" title="Usage"><span class="icon-chevron-right"></span>Usage</a></li> |
| <li><a href="../manual/webapp.html" title="Web Applications and JSPs"><span class="icon-chevron-right"></span>Web Applications and JSPs</a></li> |
| <li><a href="../manual/lookups.html" title="Lookups"><span class="icon-chevron-right"></span>Lookups</a></li> |
| <li><a href="../manual/appenders.html" title="Appenders"><span class="icon-chevron-right"></span>Appenders</a></li> |
| <li><a href="../manual/layouts.html" title="Layouts"><span class="icon-chevron-right"></span>Layouts</a></li> |
| <li><a href="../manual/filters.html" title="Filters"><span class="icon-chevron-right"></span>Filters</a></li> |
| <li><a href="../manual/async.html" title="Async Loggers"><span class="icon-chevron-right"></span>Async Loggers</a></li> |
| <li><a href="../manual/garbagefree.html" title="Garbage-free Logging"><span class="icon-chevron-right"></span>Garbage-free Logging</a></li> |
| <li class="active"><a href="#"><span class="none"></span>JMX</a></li> |
| <li><a href="../manual/logsep.html" title="Logging Separation"><span class="none"></span>Logging Separation</a></li> |
| <li><a href="../manual/extending.html" title="Extending Log4j"><span class="icon-chevron-right"></span>Extending Log4j</a></li> |
| <li><a href="../manual/plugins.html" title="Plugins"><span class="icon-chevron-right"></span>Plugins</a></li> |
| <li><a href="../manual/customconfig.html" title="Programmatic Log4j Configuration"><span class="icon-chevron-right"></span>Programmatic Log4j Configuration</a></li> |
| <li><a href="../manual/customloglevels.html" title="Custom Log Levels"><span class="icon-chevron-right"></span>Custom Log Levels</a></li> |
| <li class="nav-header"><img class="imageLink" src="../img/glyphicons/tag.png" alt="Related Projects" border="0"/> Related Projects</li> |
| <li><a href="http://logging.apache.org/log4j/scala/index.html" class="externalLink" title="Log4j-Scala"><span class="none"></span>Log4j-Scala</a></li> |
| <li class="nav-header"><img class="imageLink" src="../img/glyphicons/link.png" alt="Legacy Sites" border="0"/> Legacy Sites</li> |
| <li><a href="http://logging.apache.org/log4j/1.2/" class="externalLink" title="Log4j 1.2 - End of Life"><span class="none"></span>Log4j 1.2 - End of Life</a></li> |
| <li><a href="http://logging.apache.org/log4j/log4j-2.3/" class="externalLink" title="Log4j 2.3 - Java 6"><span class="none"></span>Log4j 2.3 - Java 6</a></li> |
| <li><a href="http://logging.apache.org/log4j/log4j-2.12.1" class="externalLink" title="Log4j 2.12.1 - Java 7"><span class="none"></span>Log4j 2.12.1 - Java 7</a></li> |
| <li class="nav-header"><img class="imageLink" src="../img/glyphicons/cog.png" alt="Components" border="0"/> Components</li> |
| <li><a href="../log4j-api/index.html" title="API"><span class="none"></span>API</a></li> |
| <li><a href="../log4j-core/index.html" title="Implementation"><span class="none"></span>Implementation</a></li> |
| <li><a href="../log4j-jcl/index.html" title="Commons Logging Bridge"><span class="none"></span>Commons Logging Bridge</a></li> |
| <li><a href="../log4j-1.2-api/index.html" title="Log4j 1.2 API"><span class="none"></span>Log4j 1.2 API</a></li> |
| <li><a href="../log4j-slf4j-impl/index.html" title="SLF4J Binding"><span class="none"></span>SLF4J Binding</a></li> |
| <li><a href="../log4j-jul/index.html" title="JUL Adapter"><span class="none"></span>JUL Adapter</a></li> |
| <li><a href="../log4j-to-slf4j/index.html" title="Log4j 2 to SLF4J Adapter"><span class="none"></span>Log4j 2 to SLF4J Adapter</a></li> |
| <li><a href="../log4j-flume-ng/index.html" title="Apache Flume Appender"><span class="none"></span>Apache Flume Appender</a></li> |
| <li><a href="../log4j-taglib/index.html" title="Log4j Tag Library"><span class="none"></span>Log4j Tag Library</a></li> |
| <li><a href="../log4j-jmx-gui/index.html" title="Log4j JMX GUI"><span class="none"></span>Log4j JMX GUI</a></li> |
| <li><a href="../log4j-web/index.html" title="Log4j Web Application Support"><span class="none"></span>Log4j Web Application Support</a></li> |
| <li><a href="../log4j-appserver/index.html" title="Log4j Application Server Integration"><span class="none"></span>Log4j Application Server Integration</a></li> |
| <li><a href="../log4j-couchdb/index.html" title="Log4j CouchDB appender"><span class="none"></span>Log4j CouchDB appender</a></li> |
| <li><a href="../log4j-mongodb2/index.html" title="Log4j MongoDB2 appender"><span class="none"></span>Log4j MongoDB2 appender</a></li> |
| <li><a href="../log4j-mongodb3/index.html" title="Log4j MongoDB3 appender"><span class="none"></span>Log4j MongoDB3 appender</a></li> |
| <li><a href="../log4j-cassandra/index.html" title="Log4j Cassandra appender"><span class="none"></span>Log4j Cassandra appender</a></li> |
| <li><a href="../log4j-iostreams/index.html" title="Log4j IO Streams"><span class="none"></span>Log4j IO Streams</a></li> |
| <li><a href="../log4j-liquibase/index.html" title="Log4j Liquibase Binding"><span class="none"></span>Log4j Liquibase Binding</a></li> |
| <li><a href="../log4j-docker/index.html" title="Log4j Docker Support"><span class="none"></span>Log4j Docker Support</a></li> |
| <li><a href="../log4j-spring-cloud-config/log4j-spring-cloud-config-client/index.html" title="Log4j Spring Cloud Config Client"><span class="none"></span>Log4j Spring Cloud Config Client</a></li> |
| <li class="nav-header"><img class="imageLink" src="../img/glyphicons/info.png" alt="Project Information" border="0"/> Project Information</li> |
| <li><a href="../dependency-convergence.html" title="Dependency Convergence"><span class="none"></span>Dependency Convergence</a></li> |
| <li><a href="../dependency-management.html" title="Dependency Management"><span class="none"></span>Dependency Management</a></li> |
| <li><a href="../team-list.html" title="Project Team"><span class="none"></span>Project Team</a></li> |
| <li><a href="../mail-lists.html" title="Mailing Lists"><span class="none"></span>Mailing Lists</a></li> |
| <li><a href="../issue-tracking.html" title="Issue Tracking"><span class="none"></span>Issue Tracking</a></li> |
| <li><a href="../license.html" title="Project License"><span class="none"></span>Project License</a></li> |
| <li><a href="../source-repository.html" title="Source Repository"><span class="none"></span>Source Repository</a></li> |
| <li><a href="../project-summary.html" title="Project Summary"><span class="none"></span>Project Summary</a></li> |
| <li class="nav-header"><img class="imageLink" src="../img/glyphicons/layers.png" alt="Project Reports" border="0"/> Project Reports</li> |
| <li><a href="../changes-report.html" title="Changes Report"><span class="none"></span>Changes Report</a></li> |
| <li><a href="../jira-report.html" title="JIRA Report"><span class="none"></span>JIRA Report</a></li> |
| <li><a href="../rat-report.html" title="RAT Report"><span class="none"></span>RAT Report</a></li> |
| </ul> |
| </nav> |
| <div class="well sidebar-nav"> |
| <hr /> |
| <div id="poweredBy"> |
| <div class="clear"></div> |
| <div class="clear"></div> |
| <div class="clear"></div> |
| <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"><img class="builtBy" alt="Built by Maven" src="../images/logos/maven-feather.png" /></a> |
| </div> |
| </div> |
| </header> |
| <main id="bodyColumn" class="span10" > |
| |
| |
| <section> |
| <h2><a name="JMX"></a>JMX</h2> |
| |
| <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> |
| <h2><a name="Enabling_JMX"></a>Enabling JMX</h2> |
| <a name="Enabling_JMX"></a> |
| |
| <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 log4j2.disableJmx to true when you start |
| the Java VM. |
| </p> |
| <section> |
| <h3><a name="Local_Monitoring_and_Management"></a>Local Monitoring and Management</h3> |
| <a name="Local"></a> |
| |
| <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 |
| $JAVA_HOME/bin/jconsole in a command shell. |
| For more details, see Oracle's documentation on |
| <a class="externalLink" href="http://docs.oracle.com/javase/7/docs/technotes/guides/management/jconsole.html">how to use JConsole</a>.</p> |
| </section> |
| <section> |
| <h3><a name="Remote_Monitoring_and_Management"></a>Remote Monitoring and Management</h3> |
| <a name="Remote"></a> |
| |
| <p>To enable monitoring and management from remote systems, set the following system property when starting the Java VM. |
| </p> |
| <p> |
| com.sun.management.jmxremote.port=portNum |
| </p> |
| <p> |
| In the property above, portNum is the port number through |
| which you want to enable JMX RMI connections. |
| </p> |
| <p> |
| For more details, see Oracle's documentation on |
| <a class="externalLink" href="http://docs.oracle.com/javase/7/docs/technotes/guides/management/agent.html#gdenl">Remote |
| Monitoring and Management</a>.</p> |
| </section> |
| <section> |
| <h3><a name="RMI_impact_on_Garbage_Collection"></a>RMI impact on Garbage Collection</h3> |
| <a name="RMI_GC"></a> |
| |
| <p> |
| Be aware that RMI by default triggers a full GC every hour. |
| See the <a class="externalLink" href="http://docs.oracle.com/javase/7/docs/technotes/guides/rmi/sunrmiproperties.html">Oracle |
| documentation</a> for the sun.rmi.dgc.server.gcInterval and sun.rmi.dgc.client.gcInterval 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 System.gc() altogether with |
| -XX:+DisableExplicitGC, or (if you are using the CMS or G1 collector) |
| add -XX:+ExplicitGCInvokesConcurrent to ensure the full GCs are done |
| concurrently in parallel with your application instead of forcing a stop-the-world collection. |
| </p> |
| </section> |
| </section> |
| <section> |
| <h2><a name="Log4j_Instrumented_Components"></a>Log4j Instrumented Components</h2> |
| <a name="Log4j_MBeans"></a> |
| |
| <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> |
| <h2><a name="Client_GUI"></a>Client GUI</h2> |
| <a name="ClientGUI"></a> |
| |
| <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> |
| <section> |
| <h3><a name="Running_the_Client_GUI_as_a_JConsole_Plug-in"></a>Running the Client GUI as a JConsole Plug-in</h3> |
| |
| <p>To run the Log4j JMX Client GUI as a JConsole Plug-in, |
| start JConsole with the following command: |
| </p> |
| |
| <p>$JAVA_HOME/bin/jconsole -pluginpath /path/to/log4j-api-2.13.1.jar:/path/to/log4j-core-2.13.1.jar:/path/to/log4j-jmx-gui-2.13.1.jar</p> |
| |
| <p>or on Windows:</p> |
| |
| <p>%JAVA_HOME%\bin\jconsole -pluginpath \path\to\log4j-api-2.13.1.jar;\path\to\log4j-core-2.13.1.jar;\path\to\log4j-jmx-gui-2.13.1.jar</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> |
| </section> |
| <section> |
| <h3><a name="Remotely_Editing_the_Log4j_Configuration"></a>Remotely Editing the Log4j Configuration</h3> |
| |
| <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> |
| </section> |
| <section> |
| <h3><a name="Running_the_Client_GUI_as_a_Stand-alone_Application"></a>Running the Client GUI as a Stand-alone Application</h3> |
| <a name="ClientStandAlone"></a> |
| |
| <p>To run the Log4j JMX Client GUI as a stand-alone application, |
| run the following command: |
| </p> |
| |
| <p>$JAVA_HOME/bin/java -cp /path/to/log4j-api-2.13.1.jar:/path/to/log4j-core-2.13.1.jar:/path/to/log4j-jmx-gui-2.13.1.jar org.apache.logging.log4j.jmx.gui.ClientGui <options></p> |
| |
| <p>or on Windows:</p> |
| |
| <p>%JAVA_HOME%\bin\java -cp \path\to\log4j-api-2.13.1.jar;\path\to\log4j-core-2.13.1.jar;\path\to\log4j-jmx-gui-2.13.1.jar org.apache.logging.log4j.jmx.gui.ClientGui <options></p> |
| |
| <p>Where options are one of the following:</p> |
| |
| <ul> |
| |
| <li><host>:<port></li> |
| |
| <li>service:jmx:rmi:///jndi/rmi://<host>:<port>/jmxrmi</li> |
| |
| <li>service:jmx:rmi://<host>:<port>/jndi/rmi://<host>:<port>/jmxrmi</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> |
| |
| <div> |
| <pre>com.sun.management.jmxremote.port=33445 |
| com.sun.management.jmxremote.authenticate=false |
| com.sun.management.jmxremote.ssl=false</pre></div> |
| |
| <p><b>(Note that this disables <i>all</i> security so this is not recommended |
| for production environments. |
| Oracle's documentation on |
| <a class="externalLink" 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>$JAVA_HOME/bin/java -cp /path/to/log4j-api-2.13.1.jar:/path/to/log4j-core-2.13.1.jar:/path/to/log4j-jmx-gui-2.13.1.jar org.apache.logging.log4j.jmx.gui.ClientGui localhost:33445</p> |
| |
| <p>or on Windows:</p> |
| |
| <p>%JAVA_HOME%\bin\java -cp \path\to\log4j-api-2.13.1.jar;\path\to\log4j-core-2.13.1.jar;\path\to\log4j-jmx-gui-2.13.1.jar org.apache.logging.log4j.jmx.gui.ClientGui localhost:33445</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> |
| |
| </section> |
| </section> |
| |
| |
| |
| </main> |
| </div> |
| </div> |
| <hr/> |
| <footer> |
| <div class="container-fluid"> |
| <div class="row-fluid"> |
| <p align="center">Copyright © 1999-2020 <a class="external" href="http://www.apache.org">The Apache Software Foundation</a>. All Rights Reserved.<br> |
| Apache Logging, Apache Log4j, Log4j, Apache, the Apache feather logo, and the Apache Logging project logo are trademarks of The Apache Software Foundation.</p> |
| </div> |
| </div> |
| </footer> |
| </body> |
| </html> |