src/site/asciidoc/manual/jmx.adoc - logging-log4j2 - Git at Google

 ////
     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 <remkop@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]
	////
	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 <remkop@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]