blob: 74fefb1d6033c2f348e9e6905e25348c0fb982f7 [file] [log] [blame]
<!DOCTYPE html>
<!--
| Generated by Apache Maven Doxia Site Renderer 1.9.1 from src/site/xdoc/manual/jmx.xml.vm at 2020-05-10
| 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 &#x2013; 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-05-10<span class="divider">|</span>
</li>
<li id="projectVersion">Version: 2.13.3</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="../security.html" title="Security"><span class="none"></span>Security</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-jpl/index.html" title="JDK Platform Logger"><span class="none"></span>JDK Platform Logger</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.3.jar:/path/to/log4j-core-2.13.3.jar:/path/to/log4j-jmx-gui-2.13.3.jar</p>
<p>or on Windows:</p>
<p>%JAVA_HOME%\bin\jconsole -pluginpath \path\to\log4j-api-2.13.3.jar;\path\to\log4j-core-2.13.3.jar;\path\to\log4j-jmx-gui-2.13.3.jar</p>
<p>If you execute the above command and connect to your application,
you will see an extra &quot;Log4j 2&quot; 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 &quot;Reconfigure from Location&quot; 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 &quot;Reconfigure with XML below&quot; 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.3.jar:/path/to/log4j-core-2.13.3.jar:/path/to/log4j-jmx-gui-2.13.3.jar org.apache.logging.log4j.jmx.gui.ClientGui &lt;options&gt;</p>
<p>or on Windows:</p>
<p>%JAVA_HOME%\bin\java -cp \path\to\log4j-api-2.13.3.jar;\path\to\log4j-core-2.13.3.jar;\path\to\log4j-jmx-gui-2.13.3.jar org.apache.logging.log4j.jmx.gui.ClientGui &lt;options&gt;</p>
<p>Where options are one of the following:</p>
<ul>
<li>&lt;host&gt;:&lt;port&gt;</li>
<li>service:jmx:rmi:///jndi/rmi://&lt;host&gt;:&lt;port&gt;/jmxrmi</li>
<li>service:jmx:rmi://&lt;host&gt;:&lt;port&gt;/jndi/rmi://&lt;host&gt;:&lt;port&gt;/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.3.jar:/path/to/log4j-core-2.13.3.jar:/path/to/log4j-jmx-gui-2.13.3.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.3.jar;\path\to\log4j-core-2.13.3.jar;\path\to\log4j-jmx-gui-2.13.3.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 &copy; 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>