Java Virtual Machine Startup Parameters

Setting Java Virtual Machine Startup Parameters

Starting Quuppa Positioning Engine (QPE) correctly requires some Java Virtual Machine (JVM) startup parameters to be set. Quuppa highly recommends using the latest Java versions to run the system efficiently. As a system dealing with real-time data, QPE is sensitive to any process interruptions, e.g. "stop-the-world" execution cycle of the JVM garbage collector. Quuppa currently recommends running all systems with Java Runtime Environment (JRE) version 15 with its production ready ZGC garbage collector that is specifically designed for real-time application in mind and for efficiently handling gigabytes of memory.

In Ubuntu system using Tomcat 8 as application container, JRE parameters are typically set in file /usr/share/tomcat8/bin/setenv.sh. Create one if this configuration file doesn't exist yet.

Java 15

When you have Java 15 available, add/modify the line export JAVA_OPTS=".." in the file to specify the required parameters, for example:
export JAVA_OPTS="-XX:+UseZGC -XX:MaxRAMPercentage=75 -XX:-ZUncommit -Djava.awt.headless=true -Dproject.folder=/opt/quuppa/PE"

Different options are supported in different versions of JVM. Refer to the table below for recommended options with ZGC and to ZGC documentation for other supported options.

Java 8

If Java 15 is not available in your environment, QPE requires at least Java 8. On those systems, G1GC (-XX:+UseG1GC) is the next best option for the garbage collector.

With Java 8, you might specify:

export JAVA_OPTS="-Xmx4g -XX:+UseG1GC -Djava.awt.headless=true -Dproject.folder=/opt/quuppa/PE"

Some parameters work also fine if added as export CATALINA_OPTS=".." -line. In Windows you may need to use the graphical user interface of Tomcat server to define these parameters.

Table 1. Available JVM Startup Parameters
Parameter Name Example Description
-XX:+UseZGC -XX:+UseZGC Optional. Tells JVM to use ZGC as the garbage collector. ZGC requires at least Java version 15.
-XX:+UseG1GC -XX:+UseG1GC Optional. Tells JVM to use G1 garbage collector. Use if Java 15 is not available.
-XX:MaxRAMPercentage -XX:MaxRAMPercentage=75 Optional. Requires at least Java 10. Sets the maximum RAM usage (in percentage of what's available in the system) for the JVM process. 75 is Oracle's current recommendation. Do not set it too high as it may lead to a system crash, especially in a busy system when the available memory becomes fragmented and the OS is anymore able to allocate a new memory JRE requests.
-Xmx -Xmx4g Optional. Maximum amount of memory that JVM can allocate for QPE, example allocates 4 GB which is enough for moderate sized projects. Only specify this or the relative maximum with MaxRAMPercentage but not both.
-XX:-ZUncommit -XX:-ZUncommit Optional. Requires at least Java 13. Means that JRE will not give memory back to the OS even when it doesn't need it. It will show up as continuously high memory usage but in a dedicated system that doesn't matter and it will help reduce memory fragmentation as the JRE is in the charge of managing memory for its needs.
-Djava.awt.headless=true -Djava.awt.headless=true Required.
-Dproject.folder -Dproject.folder=/opt/quuppa/PE Required. Tells QPE in which folder project files are stored. Do not store any additional files in this folder as the system will wipe this folder clean when communicating with the Quuppa Customer Portal. Also you do not need to manually add any files to the folder, QPE does that automatically when communicating with QCP.
-DallowLocatorsFromAnySubnet -DallowLocatorsFromAnySubnet Optional, Mandatory with DHCP options.This parameter shall be defined in case locators are receiving the QPE IP address via DHCP Options i.e. locators may reside in any subnet and use any IP address.If this parameter is defined, -DlocatorNetworkInterface should contain the local IP address of the network interface that is used to connect the QPE to the locators.
-DlocatorNetworkInterface -DlocatorNetworkInterface=192.168.123.124 Optional. -DlocatorNetworkInterface can be used for 3 different purposes:1. It enables the QPE to monitor the status of the right network interface in case locators are not in the same subnet with QPE, i.e. DHCP options are used and -DallowLocatorFromAnySubnet is defined. In this case -DlocatorNetworkInterface is the local IP address of the network interface that is used to connect to the locators. Only one IP address shall be defined.2. It enables the QPE to work with locators that are located in multiple local subnets instead of just one local subnet. In this case -DlocatorNetworkInterface contains the local IP addresses of the desired network interfaces.3. It enables the QPE to lock only to a specific local subnet, locators from other subnets will be ignored. In this case -DlocatorNetworkInterface is the local IP address of the desired network interface.
-DuseMovedLocators -DuseMovedLocators Optional. If this parameter is set, moved Locators are used in positioning. Otherwise they are commanded to deplyment mode.
-DuseThreadPool -DuseThreadPool=-2 Optional. Allows defining the number of threads the QPE will use. The number is number of threads reserved for actual positioning calculation relative to number of CPU cores in the system. Typical value would be -1 for system with around 4 cores, -2 for bigger setups with 10 cores or more.
-DsimulatorMode -DsimulatorMode Optional. Starts QPE in simulator mode, ready to receive simulated data from QSP. Project file is transmitted from QSP.