Visit Azul.com Support

Running an Application With CRaC

Table of Contents
Need help?
Schedule a consultation with an Azul performance expert.
Contact Us

The full CRaC functionality is only available on Linux/x64 and Linux/ARM64, in version 17, 21, and 25 of Azul Zulu Builds of OpenJDK. This means, for now, you can run an application with CRaC on any system, but checkpoints can only be created and restored on Linux systems where the CRaC functionality is fully available.

Before an application is CRaC-ready, you may need to add the crac.org dependency and some custom implementations, as described on Integrating CRaC in your Application.

Running CRaC on Linux

This is a step-by-step description of how to use CRaC with Azul Zulu on Linux. The same approach can be used with Azul Zing on Linux since version 25.08.1.0.

Version 17, 21, and 25 of Azul Zulu Builds of OpenJDK, with CRaC functionality, are available as of the release of April 2023. Only the bundles with -crac- in the name, have the integrated CRaC functionality.

In case you want to use CRaC in a Linux Docker container, check Running CRaC in a Container for detailed instructions.

Note
 Some VMs, like Parallels, cannot run foreign CPU instructions, and you need a build matching your CPU. Some other virtualization environments, like WSL, do not provide a complete feature set of Linux kernel, limiting the CRaC functionality in the current version.

Download a Runtime

On the download section of the Azul website, you can use the "Java Package" > "JDK CRaC" filter.

Note
 You must extract the JDK archive with sudo. 
 
$ sudo tar zxf <jdk>.tar.gz

Generating a Checkpoint

Start the JVM with an additional flag -XX:CRaCCheckpointTo so it’s prepared to create a checkpoint:

 
java -XX:CRaCCheckpointTo=$HOME/crac-image/ -jar my_app.jar
Note
 This eventually generates a set of files in the given directory, whose cumulative size is roughly the size of the JVM resident memory.

Then you can trigger the checkpoint from outside the JVM, using jcmd with JDK.checkpoint:

 
jcmd my_app.jar JDK.checkpoint

Using a Checkpoint

When a checkpoint is available, you can (re)start your application and restore from the image:

 
java -XX:CRaCRestoreFrom=$HOME/crac-files/

Running CRaC on Windows or macOS

You can run a CRaC application on Windows or macOS to validate the implementation of the beforeCheckpoint() and afterRestore() methods. Use one of the following approaches:

  • Run your application in a containerized Linux system, e.g. following the Docker approach. For instance, on macOS you can use Docker, Podman, Parallels, VirtualBox,…​

    This approach can create a checkpoint and allows you to test the restore process.

  • Use an Azul Zulu Build of OpenJDK with CRaC support for development purposes, available for Windows and macOS. These provide a simulated checkpoint/restore mechanism to be used for development and testing only, as these only simulate the CRaC behavior, and don’t create a checkpoint. See CRaC Engines > Simulation Engines.

    You need to specify the -XX:CRaCCheckpointTo command line option, but the given path will not be used as no actual checkpoint gets created. For clearness, in the example below the engine is specified, but this is the default value on Windows and macOS.

     
    java -XX:CRaCCheckpointTo=/this/path/is/ignored \
  -XX:CRaCEngine=simengine \
  -jar my_app.jar

Example Application

If you need an example to experiment with CRaC, you can find a Spring Boot application modified to work on CRaC within the CRaC project on GitHub.

Using Different CPU Counts and Memory Sizes During Checkpoint and Restore

In the current implementation the internal VM threads, Java heap size, and other internal data structure sizes are fixed according to the size of the container/system during checkpoint. They do not automatically adjust to the new configuration during restore.

Having more CPUs or more memory during restore should not cause any stability issues. Having lower number of CPUs or memory during restore may result in the JVM being over-sized and potentially lead to stability or performance issues.