The Log4j JMX GUI provides a Swing-based client for remotely editing the Log4j configuration and remotely monitoring StatusLogger output. It can be run as a standalone application or as a JConsole plugin.

Log4j 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. See the Log4j JMX support documentation on how to configure it.

Running the client as a JConsole plugin

To run the Log4j JMX GUI as a JConsole plugin, start JConsole with the following command:

$JAVA_HOME/bin/jconsole -pluginpath /path/to/log4j-api-2.21.1.jar:/path/to/log4j-core-2.21.1.jar:/path/to/log4j-jmx-gui-2.22.0.jar

or on Windows:

%JAVA_HOME%\bin\jconsole -pluginpath \path\to\log4j-api-2.21.1.jar;\path\to\log4j-core-2.21.1.jar;\path\to\log4j-jmx-gui-2.22.0.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.

jmx jconsole statuslogger

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.

jmx jconsole editconfig

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.

Running the client as a standalone application

To run the Log4j JMX GUI as a standalone application, run the following command:

$JAVA_HOME/bin/java -cp /path/to/log4j-api-2.21.1.jar:/path/to/log4j-core-2.21.1.jar:/path/to/log4j-jmx-gui-2.22.0.jar org.apache.logging.log4j.jmx.gui.ClientGui

or on Windows:

%JAVA_HOME%\bin\java -cp \path\to\log4j-api-2.21.1.jar;\path\to\log4j-core-2.21.1.jar;\path\to\log4j-jmx-gui-2.21.1.jar org.apache.logging.log4j.jmx.gui.ClientGui

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 (i.e., port) must be the same as the com.sun.management.jmxremote.port configured for 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 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-2.21.1.jar:/path/to/log4j-core-2.21.1.jar:/path/to/log4j-jmx-gui-2.22.0.jar org.apache.logging.log4j.jmx.gui.ClientGui localhost:33445

or on Windows:

%JAVA_HOME%\bin\java -cp \path\to\log4j-api-2.21.1.jar;\path\to\log4j-core-2.21.1.jar;\path\to\log4j-jmx-gui-2.21.1.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 standalone application.

jmx standalone statuslogger

The screenshot below shows the configuration editor panel of the client GUI when running as a standalone application.

jmx standalone editconfig

Development

Log4j JMX GUI uses GitHub for source code management.

The project requires a Java compiler matching the [17,18) range and targets Java 8.

You can build and verify sources using:

./mvnw verify

You can build and view the website as follows:

./mvnw -N site
python -m http.server -d target/site

Distribution

In accordance with the Apache Software Foundation’s release distribution policy and creation process, project artifacts are officially accessible from the following locations:

See the release instructions for details.

CycloneDX Software Bill of Materials (SBOM)

Starting with version 0.6.0, Log4j JMX GUI distributes CyclenoDX Software Bill of Materials (SBOM) along with each deployed artifact. This is streamlined by logging-parent, see its website for details.

Support

Please keep in mind that this project is intended for internal usage only. You can use GitHub Issues for feature requests and bug reports – not questions! See the Log4j support policy for details.

Security

If you have encountered an unlisted security vulnerability or other unexpected behaviour that has security impact, please report them privately to the Log4j security mailing list. See the Log4j Security page for further details.

Release Notes

2.22.0

Release date

2023-11-15

This release contains minor improvements.

Added

  • Started generating CycloneDX SBOM with the recent update of logging-parent to version 10.4.0

  • Publish the website

Changed

  • Add OSGi and JPMS descriptors

  • Update log4j-core to version 2.21.1

  • Update logging-parent to version 10.4.0

Fixed

  • Restore the original Maven groupId: org.apache.logging.log4j

2.21.0

Release date

2023-09-15

This marks the first release where the Log4j JMX GUI is released separately from the Log4j itself.

Added

  • Project is moved to a new repository with its own release cycle

Release instructions

Log4j JMX GUI employs the CI/CD foundation provided by the logging-parent. You can simply use its release instructions.

License

Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See NOTICE.txt 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.