LOG4J2-1802: Convert JMX manual page to asciidoc

Project: http://git-wip-us.apache.org/repos/asf/logging-log4j2/repo
Commit: http://git-wip-us.apache.org/repos/asf/logging-log4j2/commit/a15df802
Tree: http://git-wip-us.apache.org/repos/asf/logging-log4j2/tree/a15df802
Diff: http://git-wip-us.apache.org/repos/asf/logging-log4j2/diff/a15df802

Branch: refs/heads/master
Commit: a15df802c4fd253e9cddac18e8674cddca806213
Parents: 86e8caa
Author: Matt Sicker <boa...@gmail.com>
Authored: Sun Apr 8 16:16:29 2018 -0500
Committer: Matt Sicker <boa...@gmail.com>
Committed: Sun Apr 8 20:08:49 2018 -0500

----------------------------------------------------------------------
 src/site/asciidoc/manual/jmx.adoc | 208 +++++++++++++++++++++++++++++++++
 src/site/xdoc/manual/jmx.xml.vm   | 189 ------------------------------
 2 files changed, 208 insertions(+), 189 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/a15df802/src/site/asciidoc/manual/jmx.adoc
----------------------------------------------------------------------
diff --git a/src/site/asciidoc/manual/jmx.adoc 
b/src/site/asciidoc/manual/jmx.adoc
new file mode 100644
index 0000000..057134f
--- /dev/null
+++ b/src/site/asciidoc/manual/jmx.adoc
@@ -0,0 +1,208 @@
+////
+    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
+
+        https://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.
+////
+= JMX
+Remko Popma <rem...@yahoo.com>
+
+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.
+
+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.
+
+[#Enabling_JMX]
+== Enabling JMX
+
+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.
+
+[#Local]
+== Local Monitoring and Management
+
+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
+https://docs.oracle.com/javase/7/docs/technotes/guides/management/jconsole.html[how
+to use JConsole].
+
+[#Remote]
+== Remote Monitoring and Management
+
+To enable monitoring and management from remote systems, set the
+following system property when starting the Java VM.
+
+`com.sun.management.jmxremote.port=portNum`
+
+In the property above, `portNum` is the port number through which you
+want to enable JMX RMI connections.
+
+For more details, see Oracle's documentation on
+https://docs.oracle.com/javase/7/docs/technotes/guides/management/agent.html#gdenl[Remote
+Monitoring and Management].
+
+[#RMI_GC]
+== RMI impact on Garbage Collection
+
+Be aware that RMI by default triggers a full GC every hour. See the
+https://docs.oracle.com/javase/7/docs/technotes/guides/rmi/sunrmiproperties.html[Oracle
+documentation] 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.
+
+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.
+
+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.
+
+[#Log4j_MBeans]
+== Log4j Instrumented Components
+
+The best way to find out which methods and attributes of the various
+Log4j components are accessible via JMX is to look at the
+link:../log4j-core/apidocs/org/apache/logging/log4j/core/jmx/package-summary.html[Javadoc]
+or by exploring directly in JConsole.
+
+The screenshot below shows the Log4j MBeans in JConsole.
+
+image:../images/jmx-jconsole-mbeans.png[JConsole screenshot of the
+MBeans tab]
+
+[#ClientGUI]
+== Client GUI
+
+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.
+
+=== Running the Client GUI as a JConsole Plug-in
+
+To run the Log4j JMX Client GUI as a JConsole Plug-in, start JConsole
+with the following command:
+
+`$JAVA_HOME/bin/jconsole -pluginpath 
/path/to/log4j-api-{Log4jReleaseVersion}.jar:/path/to/log4j-core-{Log4jReleaseVersion}.jar:/path/to/log4j-jmx-gui-{Log4jReleaseVersion}.jar`
+
+or on Windows:
+
+`%JAVA_HOME%\bin\jconsole -pluginpath 
\path\to\log4j-api-{Log4jReleaseVersion}.jar;\path\to\log4j-core-{Log4jReleaseVersion}.jar;\path\to\log4j-jmx-gui-{Log4jReleaseVersion}.jar`
+
+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.
+
+image:../images/jmx-jconsole-statuslogger.png[JConsole screenshot of the
+StatusLogger display]
+
+=== Remotely Editing the Log4j Configuration
+
+The client GUI also contains a simple editor that can be used to
+remotely change the Log4j configuration.
+
+The screenshot below shows the configuration edit panel in JConsole.
+
+image:../images/jmx-jconsole-editconfig.png[JConsole screenshot of the
+configuration file editor]
+
+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.
+
+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.
+
+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.
+
+[#ClientStandAlone]
+=== Running the Client GUI as a Stand-alone Application
+
+To run the Log4j JMX Client GUI as a stand-alone application, run the
+following command:
+
+`$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>`
+
+or on Windows:
+
+`%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>`
+
+Where `options` are one of the following:
+
+* `<host>:<port>`
+* `service:jmx:rmi:///jndi/rmi://<host>:<port>/jmxrmi`
+* `service:jmx:rmi://<host>:<port>/jndi/rmi://<host>:<port>/jmxrmi`
+
+The port number must be the same as the portNum specified when you
+started the application you want to monitor.
+
+For example, if you started your application with these options:
+
+....
+com.sun.management.jmxremote.port=33445
+com.sun.management.jmxremote.authenticate=false
+com.sun.management.jmxremote.ssl=false
+....
+
+*(Note that this disables _all_ security so this is not recommended for
+production environments. Oracle's documentation on
+https://docs.oracle.com/javase/7/docs/technotes/guides/management/agent.html#gdenl[Remote
+Monitoring and Management] provides details on how to configure JMX more
+securely with password authentication and SSL.)*
+
+Then you can run the client with this command:
+
+`$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`
+
+or on Windows:
+
+`%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`
+
+The screenshot below shows the StatusLogger panel of the client GUI when
+running as a stand-alone application.
+
+image:../images/jmx-standalone-statuslogger.png[JMX GUI screenshot of
+StatusLogger display]
+
+The screenshot below shows the configuration editor panel of the client
+GUI when running as a stand-alone application.
+
+image:../images/jmx-standalone-editconfig.png[JMX GUI screenshot of
+configuration editor]

http://git-wip-us.apache.org/repos/asf/logging-log4j2/blob/a15df802/src/site/xdoc/manual/jmx.xml.vm
----------------------------------------------------------------------
diff --git a/src/site/xdoc/manual/jmx.xml.vm b/src/site/xdoc/manual/jmx.xml.vm
deleted file mode 100644
index 89eef0e..0000000
--- a/src/site/xdoc/manual/jmx.xml.vm
+++ /dev/null
@@ -1,189 +0,0 @@
-<?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="rem...@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 &lt;options&gt;</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 &lt;options&gt;</code></p>
-               <p>Where <code>options</code> are one of the following:</p>
-               <ul>
-               <li><code>&lt;host&gt;:&lt;port&gt;</code></li>
-               
<li><code>service:jmx:rmi:///jndi/rmi://&lt;host&gt;:&lt;port&gt;/jmxrmi</code></li>
-               
<li><code>service:jmx:rmi://&lt;host&gt;:&lt;port&gt;/jndi/rmi://&lt;host&gt;:&lt;port&gt;/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>

Reply via email to