Inspecting State of JVM Processes with Visual VM

visualvm-jvm-state-inspection.md

This guide assumes Visual VM, version 2.1.5 or later; does not explain usage on OSs other than Linux, macOS and Windows; and is incomplete

Visual VM can be used to profile and otherwise debug running JVM process(es).

See: https://visualvm.github.io/gettingstarted.html?VisualVM_2.1.5 for an in-depth guide to using Visual VM.

PREREQUISITES

VisualVM requires that a JDK be installed in order access a running JVM process.

JDK distributions/installers for your OS can be downloaded from Adoptium.

A reliable way to check whether a JDK is already installed would be to check for the existence of the javac executable in the PATH environment variable's list of search directories:

Windows

cmd.exe:

C:\> where javac
[example output from where]

Powershell:

PS C:\> Get-Command javac
[ditto]

Linux / macOS

$ bash -c 'type -P javac'
/usr/bin/javac

INSTALLING/LAUNCHING VIRTUAL VM

1. Download ZIP package from https://visualvm.github.io/download.html

2. Extract downloaded visualvm_$VERSION.zip file

3. For version 2.1.5, change to extracted visualvm_215/bin directory

4. Launching

   Windows: execute / double-click visualvm.exe

   Linux / macOS: execute / double-click visualvm

Note: To be sure that Visual VM will see the Java application that you want to interact with, start that application first and wait for it to finish loading, and then finally launch Visual VM.

ENTRY POINT PRIMER

Note: If you are familiar with Java applications and their entry points, you can probably skip this section.

Visual VM will refer to running JVM processes by their fully-qualified entry point name that might look something like com.example.Module.ClassName

Some common applications include:

• cpw.mods.bootstaplauncher.BootstrapLauncher (Minecraft)
• install4j.net.creeperhost.creeperlauncher.CreeperLauncher (the FTB App)
• org.multimc.EntryPoint (MultiMC)

Flesh this out more?

CONNECTING TO RUNNING JVM PROCESS

Once launched, Visual VM can attach to JVM processes running locally where the executing user has sufficient priveleges. JVMs that can be attached to will appear in the Applications sidebar shown below.

SCENARIO: GENERATING HEAP DUMP FROM RUNNING APPLICATION

1. Double click the application's entry point name (install4j.net.creeperhost.creeperlauncher.CreeperLauncher in the example screenshot below) under Local in the Applications sidebar.

2. In the main application view, click on the Monitor tab towards the top of the right-side view.

3. Under Monitor heading, click on the Heap Dump button

4. To view objects whose sizes dominate in the heap, the Compute Retained Sizes button must be clicked first.

5. Heap dumps can be saved for later examination by right-clicking the timestamped dump and clicking Save As...

SCENARIO: GENERATING THREAD DUMP FROM RUNNING APPLICATION

1. Double click the application's entry point name (install4j.net.creeperhost.creeperlauncher.CreeperLauncher in the example screenshot below) under Local in the Applications sidebar.

2. In the main application view, click on the Threads tab towards the top of the right-side view.

3. Under Threads heading, click on the Thread Dump button highlighted below.

4. As with heap dumps, thread dumps can also be saved to ease sharing by right clicking the timestamped threaddump

SCENARIO: PROFILING EXECUTION OF RUNNING APPLICATION

TBC

EDITOR'S NOTES

1. Gereralise where possible, e.g. instead of talking about the FTB App, use language and/or instructions that can apply to any of the Java applications referenced in the ENTRY POINT PRIMER section. (Done)

2. Flesh out the list of application entry points to include older Minecraft versions and perhaps additional launchers.

3. Finish section on profiling Minecraft including CPU/memory-based sampling.

4. Clean up the Markdown source (e.g. proper headings) for this guide and make it easier on the user by adding self-referencing links in place of blockquote references, etc.

5. Get and crop screenshots for the PREREQUISITES section.

6. Non-sampling based profiling of Minecraft (minimally) need further testing. With Amazon Coretto build 17.0.3+6-LTS at least, both Minecraft and Visual VM become unstable with the former unresponsive to keyboard/mouse input responding only to SIGKILL.

It might be better to start VisualVM after Java process is being started. At least in one case new process was not found automatically.

SCENARIO: CREATING HEAP DUMP OF RUNNING FTB APP and SCENARIO: CREATING THREAD DUMP OF RUNNING FTB APP could more more generic:

• first list well-known java apps

  • install4j.net.creeperhost.creeperlauncher.CreeperLauncher => FTB App
  • cpw.mods.bootstaplauncher.BootstrapLauncher => MC
  • TBD => older MC
  • TBD => MC started from MMC

  After those changes it would be easier to request e.g. thread dump for game or for FTB App's java parts.