Visualizing GraalVM Native Images

This project is a result of the Software Architecture Group's Master Project WS 22/23 of the Hasso Plattner Institute Potsdam. Together in cooperation with Oracle, we explored several ways to explain casual GraalVM users how their Native Image sizes came to be. Moreover, what they can do to make it smaller. We offer different use cases:

Offering a visual way to explore Native Images' contents
Removing usages of methods, classes, etc., to see how it affects the total size in real time
Comparing multiple, different Native Images to see the impact of users' code and what included items they can even have an effect on
Saving & Loading your current settings to share interesting parts with others

If you are interested in the project's motivation and technical information, check out our final presentation.

You can try it out by following the instructions on our latest release.

Visualizations

For a run-through of the visualizations see Visualization Explanations. You can see the videos when downloading the files locally.

Additional data export

The subdirectory ./graal contains a graalvm-fork that adds additional data acquisition and output functionality to native-image.

Building

It can be built as usual using

mx -p ./substratevm build

An added subcomponent HeapAssignmentTracingAgent requires CMake to be installed. It is also currently only expected to work on linux-based setups.

Reachability.json

This output can be generated by supplying the option

-H:+GenerateReachabilityFile

which is active by default. The generated file <name>.reachability.json contains information about all reachable classes, methods and fields.

It is the basic input of the observatory visualizations.

CausalityExport

-H:+PrintCausalityGraph

Specifying this option generates a file <name>.cg.zip. It extends the Reachability.json-export with information about how events during the analysis lead to each other. Image building is expected to take more time.

Troubleshooting

Per default, a native JVMTI agent is attached to the VM during build, in order to collect information about heap writes. If the build fails for strange reasons, the agent may be causing unforeseen problems. For this case, it can be disabled using

-H:-HeapAssignmentTracingAgent

Of course the quality of the generated data will be degraded without the agent.

Visualization

The subdirectory ./observatory contains a web-app for visualizing the additonal data output (README). The application can be served statically and works client-side in the browser.

Both the Reachability.json and the CausalityExport can be fed into this app. The visualization CutTool only works with the CausalityExport, as the advanced data is necessary for cutoff-predictions.

hpi-swa-lab/native-image-visualizations