<?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>
        <author email="vy@apache.org">Volkan Yazıcı</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="https://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="https://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="https://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
        <code>org.apache.logging.log4j.core.jmx</code> package contents in the
        <code>log4j-core</code> artifact 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>
          <a href="https://github.com/apache/logging-log4j-jmx-gui">The Apache Log4j JMX GUI</a> is a basic client GUI that can be used to monitor the <code>StatusLogger</code> 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>
    </body>

</document>
