External Debugging With JMXTerm

1. Overview

Debugging can be time-consuming for developers. One of the ways to make the debugging process more efficient is by using JMX (Java Management Extension), a monitoring and management technology for Java applications.

In this tutorial, we’ll look at how to use JMXTerm to perform external debugging on a Java application.

2. JMXTerm

JMX has several tools available for Java applications, such as JConsole, VisualVM, and JMXTerm. JConsole is a graphical tool for monitoring performance. VisualVM provides advanced debugging and profiling capabilities and needs a plugin to work with MBeans. While these are useful tools, JMXTerm is a lightweight, flexible, and command-line option which can be used for automation.

2.1. Setup

To use JMXTerm, we first need to download and install it. The latest version of JMXTerm is available on the official website. It’s packaged in a simple jar file:

$ java -jar jmxterm.jar

Note that it’s possible to get on later Java versions. This may happen due to the restriction on reflective access in modularized JDKs. To resolve the issue, we can use –add-exports:

$ java --add-exports jdk.jconsole/sun.tools.jconsole=ALL-UNNAMED -jar jmxterm.jar

2.2. Connection

After launching JMXTerm, we can connect to a Java application with a host and port. Note that this option might require additional steps to configure or to look up the needed port:

$ open [host]:[port]

Also, it’s possible to pass the address on the startup:

$ java -jar jmxterm.jar -l [host]:[port]

Alternatively, we can use PID to access and open the connection. JMXTerm allows us to look it up directly by using the jvms command:

$ jvms
83049    (m) - com.baeldung.jmxterm.GameRunner
$ open 83049
#Connection to 83049 is opened

2.3. MBeans

MBeans are Java objects that we can manage and monitor through JMX. They expose an interface that can be accessed and controlled through a JMX agent, making diagnosing and troubleshooting issues easier.

To create an MBean, we should follow the convention and first create an interface with a name that ends with MBean. In our case, it’ll be GuessGameMBean. This means that the name of the class should be GuessGame, not anything else. Alternatively, in some cases, it’s possible to use MXBeans. The interface contains the operations we want to expose to JMX:

public interface GuessGameMBean {
    void finishGame();
    void pauseGame();
    void unpauseGame();
}

The game itself is a simple guess-a-number game:

public class GuessGame extends GuessGameMBean {
    //...
    public void start() {
        int randomNumber = randomNumbergenerator.getLastNumber();
        while (!isFinished) {
            waitASecond();
            while (!isPaused && !isFinished) {
                log.info("Current random number is " + randomNumber);
                waitASecond();
                for (Player player : players) {
                    int guess = player.guessNumber();
                    if (guess == randomNumber) {
                        log.info("Players " + player.getName() + " " + guess + " is correct");
                        player.incrementScore();
                        notifyAboutWinner(player);
                        randomNumber = randomNumbergenerator.generateRandomNumber();
                        break;
                    }
                    log.info("Player " + player.getName() + " guessed incorrectly with " + guess);
                }
                log.info("\n");
            }
            if (isPaused) {
                log.info("Game is paused");
            }
            if (isFinished) {
                log.info("Game is finished");
            }
        }
    }
    //...
}

We’ll also track players via JMX:

public interface PlayerMBean {
    int getGuess();
    int getScore();
    String getName();
}

3. Debugging With JMXTerm

Once connected to a Java application with JMXTerm, we can query the available domains:

$ domains
#following domains are available
JMImplementation
com.baeldung.jmxterm
com.sun.management
java.lang
java.nio
java.util.logging
jdk.management.jfr

3.1. Logger Level

Let’s try to change the logging level of our running application. We’ll be using java.util.logging.Logger for demonstration purposes, but note that JUL has significant shortcomings. JUL provides MBeans out-of-the-box:

$ domain java.util.logging
#domain is set to java.util.logging

Now we can check MBeans available in the domain:

$ beans
#domain = java.util.logging:
java.util.logging:type=Logging

As the next step, we need to check the information provided by logging bean:

$ bean java.util.logging:type=Logging
#bean is set to java.util.logging:type=Logging
$ info
#mbean = java.util.logging:type=Logging
#class name = sun.management.ManagementFactoryHelper$PlatformLoggingImpl
# attributes
  %0   - LoggerNames ([Ljava.lang.String;, r)
  %1   - ObjectName (javax.management.ObjectName, r)
# operations
  %0   - java.lang.String getLoggerLevel(java.lang.String p0)
  %1   - java.lang.String getParentLoggerName(java.lang.String p0)
  %2   - void setLoggerLevel(java.lang.String p0,java.lang.String p1)
#there's no notifications

To access the logger in our GuessGame object, we need to find the logger’s name:

$ get LoggerNames
#mbean = java.util.logging:type=Logging:
LoggerNames = [ ..., com.baeldung.jmxterm.GuessGame, ...];

And finally, check the logging level:

$ run getLoggerLevel com.baeldung.jmxterm.GuessGame
#calling operation getLoggerLevel of mbean java.util.logging:type=Logging with params [com.baeldung.jmxterm.GuessGame]
#operation returns:
WARNING

To change it, we just call a setter method with an argument:

$ run setLoggerLevel com.baeldung.jmxterm.GuessGame INFO

...
Apr 14, 2023 12:04:30 PM com.baeldung.jmxterm.GuessGame start
INFO: Current random number is 7
Apr 14, 2023 12:04:31 PM com.baeldung.jmxterm.GuessGame start
INFO: Player Bob guessed incorrectly with 10
Apr 14, 2023 12:04:31 PM com.baeldung.jmxterm.GuessGame start
INFO: Player Alice guessed incorrectly with 5
Apr 14, 2023 12:04:31 PM com.baeldung.jmxterm.GuessGame start
INFO: Player John guessed incorrectly with 4
...

3.2. Working With Domain Beans

Let’s try to stop our game from outside of our application. The steps would be the same as in the example with the logger:

$ domain com.baeldung.jmxterm
#domain is set to com.baeldung.jmxterm
$ beans
#domain = com.baeldung.jmxterm:
com.baeldung.jmxterm:id=singlegame,type=game
$ bean com.baeldung.jmxterm:id=singlegame,type=game
#bean is set to com.baeldung.jmxterm:id=singlegame,type=game
$ info
#mbean = com.baeldung.jmxterm:id=singlegame,type=game
#class name = com.baeldung.jmxterm.GuessGame
#there is no attribute
# operations
  %0   - void finishGame()
  %1   - void pauseGame()
  %2   - void unpauseGame()
#there's no notifications
$ run pauseGame
#calling operation pauseGame of mbean com.baeldung.jmxterm:id=singlegame,type=game with params []

We should see in the output that the game is paused:

...
Apr 14, 2023 12:17:01 PM com.baeldung.jmxterm.GuessGame start
INFO: Game is paused
Apr 14, 2023 12:17:02 PM com.baeldung.jmxterm.GuessGame start
INFO: Game is paused
Apr 14, 2023 12:17:03 PM com.baeldung.jmxterm.GuessGame start
INFO: Game is paused
Apr 14, 2023 12:17:04 PM com.baeldung.jmxterm.GuessGame start
INFO: Game is paused
...

Also, we can finish the game:

$ run finishGame

The output should contain the information that the game was finished:

...
Apr 14, 2023 12:17:47 PM com.baeldung.jmxterm.GuessGame start
INFO: Game is finished

3.3. watch

Additionally, we can track the value of attributes with the watch command:

$ info
# attributes
#mbean = com.baeldung.jmxterm:id=Bobd661ee89-b972-433c-adff-93e7495c7e0a,type=player
#class name = com.baeldung.jmxterm.Player
#there's no operations
#there's no notifications
  %0   - Guess (int, r)
  %1   - Name (java.lang.String, r)
  %2   - Score (int, r)
$ watch Score
#press any key to stop. DO NOT press Ctrl+C !!!
683683683683683683683

The raw watch output is quite hard to read, but we can provide a format for it:

$ watch --format Score\\ {0}\\  Score
#press any key to stop. DO NOT press Ctrl+C !!!
Score 707 Score 707 Score 707 Score 707 Score 707 

However, we can improve it even more by –report and –stopafter options:

$ watch --report --stopafter 10 --format The\\ score\\ is\\ {0} Score
The score is 727
The score is 727
The score is 727
The score is 728
The score is 728

3.4. Notifications

Another great feature for debugging is MBeans notifications. However, this requires minimal changes in our code. First of all, we have to implement javax.management.NotificationBroadcaster interface:

public interface NotificationBroadcaster {
    void addNotificationListener(NotificationListener listener, NotificationFilter filter, Object handback)
      throws java.lang.IllegalArgumentException;
    void removeNotificationListener(NotificationListener listener)
      throws ListenerNotFoundException;
    MBeanNotificationInfo[] getNotificationInfo();
}

To send the notification about the winner, we’ll be using javax.management.NotificationBroadcasterSupport:

public abstract class BroadcastingGuessGame implements NotificationBroadcaster, GuessGameMBean {
    private NotificationBroadcasterSupport broadcaster =
      new NotificationBroadcasterSupport();

    private long notificationSequence = 0;

    private MBeanNotificationInfo[] notificationInfo;

    public BroadcastingGuessGame() {
        this.notificationInfo = new MBeanNotificationInfo[]{ 
            new MBeanNotificationInfo(new String[]{"game"}, Notification.class.getName(),"Game notification") 
        };
    }

    protected void notifyAboutWinner(Player winner) {
        String message = "Winner is " + winner.getName() + " with score " + winner.getScore();
        Notification notification = new Notification("game.winner", this, notificationSequence++, message);
        broadcaster.sendNotification(notification);
    }

    public void addNotificationListener(NotificationListener listener, NotificationFilter filter, Object handback) {
        broadcaster.addNotificationListener(listener, filter, handback);
    }

    public void removeNotificationListener(NotificationListener listener) throws ListenerNotFoundException {
        broadcaster.removeNotificationListener(listener);
    }

    public MBeanNotificationInfo[] getNotificationInfo() {
        return notificationInfo;
    }
}

After that, we can see the notifications on the bean:

$ bean com.baeldung.jmxterm:id=singlegame,type=game
#bean is set to com.baeldung.jmxterm:id=singlegame,type=game
$ info
#mbean = com.baeldung.jmxterm:id=singlegame,type=game
#class name = com.baeldung.jmxterm.GuessGame
#there is no attribute
# operations
  %0   - void finishGame()
  %1   - void pauseGame()
  %2   - void unpauseGame()
# notifications
  %0   - javax.management.Notification(game.winner)

Subsequently, we can subscribe to the notifications:

$ subscribe
#Subscribed to com.baeldung.jmxterm:id=singlegame,type=game
notification received: ...,message=Winner is John with score 10
notification received: ...,message=Winner is Alice with score 9
notification received: ...,message=Winner is Bob with score 13
notification received: ...,message=Winner is Bob with score 14
notification received: ...,message=Winner is John with score 11

By providing –domain and —bean options, we can subscribe to several beans.

4. Conclusion

JMXTerm is a powerful and flexible tool for managing and monitoring Java applications through JMX. By providing a command-line interface for JMX operations, JMXTerm allows developers and administrators to quickly and easily perform tasks like monitoring attribute values, invoking operations, and changing configuration settings.

The source code of this tutorial can be found over on GitHub.