Appendix: Additional HotSpot VM Command-Line Options of Interest
This appendix contains a listing of Java HotSpot VM (HotSpot VM) command-line options that may be of interest for the use or tuning of G1 GC. It also contains some command-line options that were not included or documented in the Java™ Performance appendix “HotSpot VM Command Line Options of Interest.”
For each VM command-line option listed, there is a description of what the command-line options does, and also when it is appropriate to consider using it. The general recommendation for using HotSpot VM command-line options is to first have a justification for using the command-line option. You should resist the temptation to use a command-line option simply because it may have been used by someone else with some other application, or you read in a blog posting that someone used it. You should collect performance data while running your Java application when using the command-line option as the means for justifying the use of a command-line option.
HotSpot VM command-line options take one of two general forms. First, there are command-line options that are boolean in nature, that is, they are toggled on or off with a “+” or a “-” character ahead of the command-line option name, for example, -XX:+PrintAdaptiveSizePolicy, which uses a “+” character, toggles on, or enables, the command-line option called PrintAdaptiveSizePolicy. Likewise, the -XX:-PrintAdaptiveSizePolicy command-line option toggles off, or disables, the command-line option PrintAdaptiveSizePolicy.
The second form of HotSpot VM command-line options takes a numerical value, or a list of specific keywords. This appendix does not include any command-line options of the latter kind. The former kind that take a numerical value do not use the “+” or “-” character ahead of the command-line option name. For instance, -XX:ConcGCThreads is a command-line option that expects a numeric value such as -XX:ConcGCThreads=6.
The default values for a given HotSpot VM command-line option mentioned in this appendix are based on the option’s default value in JDK 8u45. As a result, there may be some cases where a given command-line option has a different default value from what is mentioned in this appendix. Changes in default values usually occur due to additional information or input on the behavior of the command-line option at an alternative value.
-XX:+UseG1GC
Enables the G1 garbage collector. To use G1 in both Java 7 and Java 8 releases, it must be explicitly enabled using this command-line option. As of this writing, there are plans to make G1 the default GC for Java 9, though there is a possibility of reverting back to Parallel GC prior to Java 9’s release.
-XX:ConcGCThreads
Sets the number of threads that the GC should use when doing work concurrently with the Java application. By default this is roughly one-fourth of the number of threads used to perform GC work when the Java threads are stopped.
Reducing -XX:ConcGCThreads can lead to higher throughput performance since fewer GC threads compete with the Java application for CPU usage. Too few concurrent threads may cause the concurrent cycle to not complete fast enough to reclaim memory.
-XX:G1HeapRegionSize
Sets the size of the heap regions for G1. By default this is about 1/2000 of the heap size. Possible region sizes are 1M, 2M, 4M, 8M, 16M, and 32M.
Objects that are larger than half the region size need to be managed specially by G1. Increasing the region size allows larger objects to be allocated with the normal allocation path, which may help performance if such large objects are common. However, having larger regions means that G1 has less flexibility when it comes to making ergonomic decisions, such as, for example, deciding on the size of the young generation.
-XX:G1HeapWastePercent
Controls the acceptable amount of free memory that G1 will not collect. By default this value is 5 percent.
G1 will collect all regions until any regions left would only free up -XX:G1HeapWastePercent of memory. Especially on large heaps it can make sense to use a lower value for -XX:G1HeapWastePercent, since 5 percent of the heap size represents a fairly large amount of memory.
-XX:G1MixedGCCountTarget
Sets the target value for how many mixed GCs should be performed after a concurrent cycle. The default value is 8.
Old regions normally take a little longer to collect than young regions. Allowing more mixed GCs after a concurrent cycle allows G1 to spread out the reclamation of the old regions over more collections. But increasing -XX:G1MixedGCCountTarget also means that it will take longer until a new concurrent cycle can be started. If mixed GC pause times are too long, it may help to increase -XX:G1MixedGCCountTarget.
-XX:+G1PrintRegionLivenessInfo
This is a diagnostic VM option, and as such it needs to be enabled with -XX:+UnlockDiagnosticVMOptions. When enabled, it will print liveness information for each region on the heap. The information includes the usage, the size of the remembered set, and the “GC efficiency,” which is a measure of how valuable it is to collect this region. The information is logged after a marking cycle has completed and also after the regions have been sorted for inclusion in the collection set.
The information logged by -XX:+G1PrintRegionLivenessInfo can be useful when trying to understand the heap usage and to identify issues with remembered sets. Since it logs one line for each region in the heap, the data can be hard to manage for large heaps.
-XX:G1ReservePercent
To reduce the risk of getting a promotion failure, G1 reserves some memory for promotions. This memory will not be used for the young generation. By default G1 keeps 10 percent of the heap reserved for this purpose.
On a large heap with a large live set, 10 percent of the heap may be too much to reserve. Reducing this value can leave more memory for the young generation and lead to longer times between GCs, which normally increases throughput performance.
-XX:+G1SummarizeRSetStats
This is a diagnostic VM option, and as such it needs to be enabled with -XX:+UnlockDiagnosticVMOptions. When enabled, it will print a detailed summary about the remembered sets when the VM exits. In combination with -XX:G1SummarizeRSetStatsPeriod this summary can be printed periodically instead of just at VM exit.
If remembered set issues are suspected, this can be a useful tool to analyze them.
-XX:G1SummarizeRSetStatsPeriod
This is a diagnostic VM option, and as such it needs to be enabled with -XX:+UnlockDiagnosticVMOptions. It can only be used together with -XX:+G1SummarizeRSetStats. If set to a value other than 0, this will print the same summary produced by -XX:+G1SummarizeRSetStats. But instead of printing it just on VM exit, it will print it each time after the number of GCs specified as the –XX:G1SummarizeRSetStatsPeriod has occurred.
It can be expensive to print this information for every GC, but printing it periodically makes it possible to identify trends in the remembered set management.
-XX:+G1TraceConcRefinement
This is a diagnostic VM option, and as such it needs to be enabled in combination with -XX:+UnlockDiagnosticVMOptions. With -XX:+G1TraceConcRefinement enabled, information about the concurrent refinement threads is logged.
The information produced includes when concurrent refinement threads are activated and when they are deactivated. This can be useful to identify issues with concurrent refinement.
-XX:+G1UseAdaptiveConcRefinement
When enabled, this command-line option dynamically recalculates the values for -XX:G1ConcRefinementGreenZone, -XX:G1ConcRefinementYellowZone, and -XX:G1ConcRefinementRedZone every GC. This flag is enabled by default.
-XX:GCTimeRatio
Sets the time spent in the Java application threads compared to that spent in the GC threads.
G1 attempts to honor the value set for -XX:GCTimeRatio to ensure that the Java application threads get enough execution time as specified by this command-line option. G1 does this by splitting work up and aborting work that can be split up or aborted. G1 also tries to spread out GC pauses to accomplish this goal. The default value for -XX:GCTimeRatio can vary depending on the garbage collector in use by the HotSpot VM. When G1 is in use, the default -XX:GCTimeRatio is 9.
The HotSpot VM converts the -XX:GCTimeRatio value to a percentage using the following formula: 100/(1 + GCTimeRatio). In other words, -XX:GCTimeRatio can be thought of as asking the HotSpot VM to attempt to spend no more than 100/(1 + GCTimeRatio) percent of its time executing in the GC threads. Hence, a default value of -XX:GCTimeRatio=9 with G1 means that up to 10 percent of the time can be spent doing GC work.
It should be noted that the HotSpot VM’s throughput garbage collector, Parallel GC, sets a default value for -XX:GCTimeRatio=99. This means that the HotSpot VM should attempt to spend up to 1 percent of its time doing GC work. This makes sense since Parallel GC is the throughput GC in contrast to G1, which is intended to be a more balanced throughput, latency, and memory footprint type of GC.
-XX:+HeapDumpBeforeFullGC
When this command-line option is enabled, an hprof file is created just prior to a full GC starting. The hprof file is created in the directory where the HotSpot VM is launched.
Comparing the contents of the Java heap before and after a full GC using this command-line option in conjunction with -XX:+HeapDumpAfterFullGC can give a good indication of memory leaks and other issues.
-XX:+HeapDumpAfterFullGC
When this command-line option is enabled, an hprof file is created right after the full GC has completed. The hprof file is created in the directory where the HotSpot VM is launched.
Comparing the contents of the Java heap before and after a full GC using this command-line option in conjunction with -XX:+HeapDumpBeforeFullGC can give a good indication of memory leaks and other issues.
-XX:InitiatingHeapOccupancyPercent
Sets the value for when a concurrent cycle in G1 should be started. The default value is 45. In other words, after a GC, G1 measures the occupancy of the old generation space and compares that to the current Java heap size. If the occupancy of the old generation space reaches or exceeds the InitiatingHeapOccupancyPercent, then a G1 concurrent cycle is initiated by scheduling an initial-mark operation to begin on the next GC. The G1 concurrent cycle is the means by which G1 concurrently collects the old generation space. A concurrent cycle begins with an initial-mark operation, which can be observed in the GC logs with the -XX:+PrintGCDetails command-line option.
If full GCs are occurring due to the old generation running out of available space, lowering this value will initiate a concurrent cycle earlier to avoid exhausting available space.
If no full GCs are occurring and it is desirable to increase throughput, it may help to increase this value to get fewer concurrent cycles. G1 concurrent cycles do require CPU cycles to execute and therefore may steal CPU cycles from application threads. Hence, frequent G1 concurrent cycles can reduce peak throughput. However, it is generally better to err with G1 concurrent cycles running too early rather than too late. If G1 concurrent cycles are run too late, the consequence is likely to be frequent full GCs, which of course introduces undesirable lengthy GC pauses.
See also -XX:+G1UseAdaptiveIHOP.
-XX:+UseStringDeduplication
Enables the deduplication of Java Strings. This command-line option and feature was introduced in JDK 8u20. String deduplication is disabled by default.
When enabled, this option deduplicates Strings by looking at the String’s underlying character array. When a String contains a sequence of characters equal to another String’s sequence of characters, such as if string1.equals(string2) evaluates to true, the String objects are updated to share the same underlying String character array. The end result is the freeing of space required by the duplicate character array having the same sequence of characters. It should be noted that the String objects are actually not deduplicated; rather their underlying character arrays are deduplicated.
This feature is implemented only with the G1 garbage collector. While enabling this command-line option is allowed with the other non-G1 HotSpot collectors—Parallel GC, CMS GC, and Serial GC—no String deduplication is performed when enabled.
An object is considered a deduplication candidate if all of the following statements are true:
The object is an instance of java.lang.String.
The object is being evacuated from a young heap region.
The object is being evacuated to a young/survivor heap region and the object’s age is equal to the deduplication age threshold, or the object is being evacuated to an old heap region and the object’s age is less than the deduplication age threshold. See -XX:StringDeduplicationAgeThreshold for additional information on the deduplication threshold.
Interned Strings are dealt with differently from noninterned Strings. Interned Strings are explicitly deduplicated just before being inserted into the internal HotSpot VM’s StringTable to avoid counteracting HotSpot Server JIT compiler optimizations done on String literals.
See also -XX:StringDeduplicationAgeThreshold and -XX:+PrintStringDeduplicationStatistics.
-XX:StringDeduplicationAgeThreshold
Sets the String object age threshold when a String object is considered a candidate for deduplication. The default value is 3.
More specifically, a String becomes a candidate for deduplication once a String object has been promoted to a G1 old region, or its age is higher than the deduplication age threshold. Once a String has become a candidate for deduplication, or has been deduplicated, it will never become a candidate again. This approach avoids making the same object a candidate more than once.
Also see -XX:+UseStringDeduplication and -XX:+PrintStringDeduplicationStatistics.
-XX:+PrintStringDeduplicationStatistics
Enables the printing of String deduplication statistics. The default value is disabled.
This command-line option can be very helpful when you want to know if enabling deduplication will result in a significant savings in the amount of space in use by String objects in the Java heap. Hence, enabling this command-line option provides data that justifies whether there may be value in enabling -XX:+UseStringDeduplication.
Also see -XX:+UseStringDeduplication and -XX:StringDeduplicationAgeThreshold.
-XX:+G1UseAdaptiveIHOP
This is a new command-line option available in JDK 9 and later. It adaptively adjusts the initiating heap occupancy threshold from the initial value of the command-line option InitiatingHeapOccupancyPercent. The intent is to let G1 adapt the marking threshold to application behavior so as to increase throughput by triggering the marking cycle as late as possible yet not exhaust old generation space.
The mechanism enabled by G1UseAdaptiveIHOP uses the value of the command-line option InitiatingHeapOccupancyPercent as an initial value for the marking cycles until sufficient observations about the application behavior have been made. It then adaptively adjusts to a more optimal heap occupancy percent at which to start the marking cycle.
When G1UseAdaptiveIHOP is disabled (when -XX:-G1UseAdaptiveIHOP is explicitly specified as a command-line option), G1 will always use the InitiatingHeapOccupancyPercent value as the occupancy at which to start the marking cycle.
G1UseAdaptiveIHOP, as of this writing, will be enabled by default with its introduction in JDK 9.
See also -XX:InitiatingHeapOccupancyPercent.
-XX:MaxGCPauseMillis
This command-line option sets the pause time goal in milliseconds for G1. The default value is 200. Note that this is a goal, not a hard maximum pause time that G1 can never exceed.
G1 attempts to size the young generation to make sure that it can be collected within the goal set by -XX:MaxGCPauseMillis. When G1 is in use, this command-line option, along with sizing the Java heap with -Xms and –Xmx, is the command-line option that is expected to be used. These three command-line options are also the suggested starting point when using G1, even when migrating from Parallel GC or CMS GC to G1.
Sets the value for how much memory is allowed to be free on the heap. The default value is 40. The value is actually a percentage, not a ratio. It is unfortunate that the command-line name includes the term ratio.
The Java HotSpot VM uses the value set by -XX:MinHeapFreeRatio to help determine when to grow the Java heap. This decision is made during a GC and can be described thus: if less than -XX:MinHeapFreeRatio percent of the Java heap is free, G1 will attempt to grow the Java heap to meet the value set as the -XX:MinHeapFreeRatio.
Obviously, in order for the Java heap size to grow, the values set for -Xms, the initial Java heap size, and -Xmx, the maximum Java heap size, must be set to different values. If -Xms and -Xmx are set to the same value, the Java HotSpot VM will not grow or shrink the Java heap.
-XX:MaxHeapFreeRatio
Sets the value for how little memory is allowed to be free on the heap. The default value is 70. Similarly to -XX:MinHeapFreeRatio, the value is actually a percentage, not a ratio. Again, similarly to -XX:MinHeapFreeRatio, it is unfortunate that the command-line name includes the term ratio.
The Java HotSpot VM uses the value set by -XX:MaxHeapFreeRatio to help determine when to shrink the Java heap. This decision is made during a GC and can be described thus: if more than -XX:MaxHeapFreeRatio percent of the Java heap is free, G1 will attempt to shrink the Java heap to meet the value set as the -XX:MaxHeapFreeRatio.
Also as is the case with -XX:MinHeapFreeRatio, in order for the Java heap size to shrink, the values set for -Xms, the initial Java heap size, and -Xmx, the maximum Java heap size, must be set to different values. If -Xms and -Xmx are set to the same value, the Java HotSpot VM will not shrink or grow the Java heap.
-XX:+PrintAdaptiveSizePolicy
Turns on logging of information about heap size changes. This information can be very useful in understanding the ergonomic heuristic decisions made by G1 (also applicable to Parallel GC).
Use of -XX:+PrintAdaptiveSizePolicy in tuning G1 is described in Chapter 3, “Garbage First Garbage Collector Performance Tuning.”
-XX:+ResizePLAB
Sets whether the thread-local allocation buffers that the GC uses for promoting objects should be resized dynamically or just have a static size. The default value is true.
The dynamic resizing of the PLABs in G1 has been shown to cause some performance issues. For some applications, disabling the resizing of thread-local promotion buffers can improve performance by reducing the duration the G1 GC pauses.
-XX:+ResizeTLAB
Sets whether the thread-local allocation buffers that the Java application threads use for Java object allocations should be resized dynamically or have a static fixed size. The default is true.
In most cases the TLAB resizing improves application performance by reducing contention in the allocation path. Contrary to the PLAB sizing, it is not very common to see that turning this off is good for performance. Hence, for almost all applications, it is best to leave this command-line option enabled, which again is its default.
-XX:+ClassUnloadingWithConcurrentMark
Turns on class unloading during G1 concurrent cycles, the concurrent collection of old generation. The default is true.
Normally it is beneficial to be able to unload unreachable classes during G1 concurrent cycles rather than having to rely on full GCs to do so. The unloading of classes during G1 concurrent cycles can sometimes increase G1 remark GC times. If G1 remark pause times are higher than can be tolerated to meet GC pause time goals, and few classes are expected to be unreachable, it may be beneficial to disable this option, that is, -XX:-ClassUnloadingWithConcurrentMark.
-XX:+ClassUnloading
Turns class unloading on and off. The default value is true, meaning the HotSpot VM will unload unreachable classes. If this command-line option is disabled—that is, -XX:-ClassUnloading—the HotSpot VM will not unload any unreachable classes, ever, not even as part of full GCs.
-XX:+UnlockDiagnosticVMOptions
Sets whether flags tagged as diagnostic options should be allowed or not. The default is false.
There are some command-line options that are tagged as “diagnostic.” These can be seen in a list of Java HotSpot VM command-line options using the -XX:+PrintFlagsFinal in conjunction with -XX:+UnlockDiagnosticVMOptions. “Diagnostic” options have a field {diagnostic} command-line option type listed in the -XX:+PrintFlagsFinal output. Examples of diagnostic HotSpot VM command-line options include -XX:+G1PrintRegionLivenessInfo, which prints detailed liveness information for each G1 region on each GC, and -XX:+LogCompilation, which produces information about optimization decisions the Java HotSpot VM’s JIT compiler has made.
Diagnostic options tend to introduce additional overhead to normal execution and are generally used to investigate or diagnose unexpected behavior of the Java HotSpot VM or the application it is executing.
-XX:+UnlockExperimentalVMOptions
Sets whether flags tagged as experimental options should be allowed or not. The default is false.
Similar to -XX:+UnlockDiagnosticVMOptions, there are some command-line options that are tagged as “experimental.” These can be seen in a list of Java HotSpot VM command-line options using the -XX:+PrintFlagsFinal in conjunction with -XX:+UnlockExperimentalVMOptions. “Experimental” options have a field {experimental} command-line option type listed in the -XX:+PrintFlagsFinal output.
It is important to note experimental command-line options are not part of the officially supported Java SE product—but are available for experimenting with—yet offer additional capabilities that may be worth exploring for some user cases.
Some experimental command-line options may be performance related features but may not have undergone full scrutiny or rigorous quality assurance testing. Yet, they may offer performance benefits in some use cases.
An example of an experimental command-line option is -XX:G1NewSizePercent, which controls the minimum size of G1 can reduce the young generation relative to the Java heap size. It defaults to 5. In other words, the minimum size G1 can adaptively size young generation is 5% of the Java heap size. For some use cases where very low GC pause times are desired, one could experiment in a non-production environment setting a lower -XX:G1NewSizePercent to say 1 or 2, yet realizing in doing so there is no official product support.
To use an experimental option, the -XX:+UnlockExperimentalVMOptions must be specified in conjunction with the experimental command-line option. For example, to use the -XX:G1NewSizePercent=2 command-line option, you would specify both -XX:+UnlockExperimentalVMOptions -XX:G1NewSizePercent=2. The –XX:+UnlockExperimentalVMOptions only need be specified once if more than one experimental command-line option is desired.
-XX:+UnlockCommercialFeatures
Sets whether Oracle-specific features that require a license are to be enabled. The default is false.
There are some capabilities or features developed by Oracle that are available only via the Oracle Java runtime distributed by Oracle and are not included in OpenJDK. An example of an Oracle commercial feature is Java Flight Recorder, which is part of Oracle’s monitoring and management tool called Java Mission Control. Java Flight Recorder is a profiling and event collection framework that can collect and show within Java Mission Control low-level information about how the application and JVM are behaving.