jcmd-ui

jcmd-ui visualizes diagnostic data of jvm applications by using native-memory-tracking capabilities of JDK's jcmd cli utility. It uses Tauri as a multi-platform toolkit having a backend written in rust and a frontend written in typescript.

JDK Compatibility

jcmd-ui should work with all openJDK based distributions, but it is only tested on a limited set.

Distribution	Version	Status
GraalVM CE	21	✅
GraalVM CE	17	✅
Java.net	21	✅
Java.net	17	✅
Temurin (Eclipse)	21	✅
Temurin (Eclipse)	17	✅

Install

There are currently no prebuilt binaries for the different operating systems, but it can build on macOS and Linux easily.

Building

jcmd-ui can easily be built on a local machine. Required tools are:

• Rust
• Node.js 20.9.0 (LTS)
• Tauri prerequisites (see below).

Installing Tauri Prerequisites

Tauri prerequisites can be installed as described in the tauri documentation linked below.

macOS

Follow these instructions to install required dependencies for macOS.

Linux

Follow these instructions to install required dependencies for the linux distribution of choice.

Windows

Windows is currently not supported.

Cloning the repository

git clone https://github.com/cschaible/jcmd-ui.git

Downloading build-dependencies

cd gui
npm install

Build

cd gui
npm run tauri build

Run

jcmd-ui requires that the JAVA_HOME variable is set or being specified in config file.

⚠️ On macOS it is not sufficient to publish the JAVA_HOME variable in ~/.bashrc or ~/.zshrc as GUI applications do not read variables from those files.
The variable can be exported by using launchctl:
launchctl setenv JAVA_HOME "<jdk-path>"
This has to be re-applied after each restart of the system.

ℹ️ The path to the java home directory can also be provided in the file ~/.config/jcmd-ui/config as follows:
java.home=<jdk-path>

After installing the previously built package the ui can be started (e.g. graphically via launchpad / gnome menu / etc.).

Monitor JVM applications

jcmd-ui requires to enable native-memory-tracking in summary mode as command line parameter of the jvm application to analyze. The feature can be applied by adding the
-XX:NativeMemoryTracking=summary parameter.

java -XX:NativeMemoryTracking=summary -jar app.jar

Once the jvm application to monitor is started, the dropdown with the list of jvm applications in the upper left corner of jcmd-ui can be refreshed by clicking on the reload button beside the dropdown. After selecting the application to monitor data is requested. It may take a few seconds until the data is visualized. The UI automatically refreshes the charts every few seconds.

ℹ️ jcmd-ui has only a primitive in-memory data storage and data visualization. Therefore, memory consumption will grow noticeable over time. It is not recommended to track metrics longer than 30 minutes. Restarting the measurement by reloading and (re-selecting) an application from the application list releases the memory.

Developing

Before applying changes to the code, the Building instructions should be applied successfully to ensure that potential errors are not related to general build issues.

Starting dev-server

Tauri supports hot-reloading by using the dev server to see changes immediately applied in the running application. The rust code and frontend-code is automatically re-compiled (depending on what has been changed):

cd gui
npm run tauri dev

Developer Tools

Tauri applications are rendered in a web-view. To debug problems in the frontend part or to analyze problems in the communication between the frontend and the backend, the browser's (i.e. web-view's) developer tools can be used to analyze the issues.

Analyzing crashes

jcmd-ui is tested on a limited set of operating systems (using english as system language) and a limited set JDKs. Therefore, errors can occur. If the application crashes, the root cause normally can be identified by looking in the terminal where the dev-server has been started. Often it makes sense to run the executed jcmd commands manually in the terminal to preview what's returned to be parsed.