Generational ZGC Migration From G1 or Non Generational ZGC
Move a Java service to generational ZGC: the flags by JDK version, what changes from G1 and single generation ZGC, heap headroom and how to compare results.

ZGC is the Java garbage collector built for low pause times on large heaps, and since JDK 21 it comes in a form that handles most allocation patterns much better: generational ZGC, which treats young and old objects differently the way G1 does, while keeping pauses well below a millisecond. The history matters if you operate services across JDK versions, because the flags changed three times in four releases. On JDK 21 you opt in, on JDK 23 it became the default for ZGC, and on JDK 24 the old non-generational mode was removed. This post gives the setting for each version, what changes for your service when you switch, how to size memory, how to compare collectors before you commit, when to stay on G1 and how to roll back. The reference is JEP 439, and the project page is the OpenJDK ZGC wiki. The comparisons assume you measure on your own workload, because collector choice is workload-specific.
What to set by version
The flags that select the collector depend on the JDK you run:
| JDK | Select generational ZGC | Notes |
|---|---|---|
| 21, 22 | -XX:+UseZGC -XX:+ZGenerational | Generational mode is opt-in; plain -XX:+UseZGC selects the older single-generation mode |
| 23 | -XX:+UseZGC | Generational is the default for ZGC; -XX:-ZGenerational selects the old mode and prints a deprecation warning |
| 24, 25 | -XX:+UseZGC | The non-generational mode is removed; ZGenerational is obsolete |
On JDK 25, the case for new deployments, the setting is one flag:
java -XX:+UseZGC -Xmx4g -jar app.jarConfirm that the JVM really chose it, and which mode:
java -XX:+UseZGC -Xlog:gc*:stdout -version 2>&1 | grep -i -E 'Using|ZGC|Generational'[0.004s][info][gc] Using The Z Garbage Collector
[0.004s][info][gc,init] Version: 25.0.1+9 (release)Migrating from non-generational ZGC means upgrading the JDK; on 21 to 22 you add -XX:+ZGenerational and on 23 you remove it. Leaving -XX:+ZGenerational in a script that moves to JDK 24 produces an obsolete-flag warning (and, in a strict launcher, a failure), so grep your deployment scripts and Dockerfiles for it when you upgrade. Check for flags that tune the old mode too, such as ZAllocationSpikeTolerance combinations written for the non-generational collector; revisit them after the switch. Moving from G1 is one flag swap on any version: replace -XX:+UseG1GC with the ZGC flags above and drop G1-specific tuning (MaxGCPauseMillis, G1HeapRegionSize, InitiatingHeapOccupancyPercent), which ZGC ignores or rejects.
What changes for your service
Pauses. ZGC does its work concurrently with your threads: marking, relocation and reference processing run in the background, and the stop-the-world pauses are short, typically well under a millisecond, and do not grow with heap size. G1's pauses grow with the live set and the amount it has to copy, so a service with a 16 GiB heap that sees G1 pauses of 80 to 200 ms can drop to sub-millisecond pauses. That helps tail latency of the services where p99 and p99.9 matter.
Throughput and CPU. The concurrent work uses CPU. ZGC has load barriers that add a little cost to every reference load, and background GC threads compete with application threads for cores. A service already at CPU saturation can lose some throughput. A service with spare cores usually pays little. Generational ZGC cut the cost of the original design a great deal, because most objects die young and are collected without marking the whole heap, so allocation-heavy services that struggled with non-generational ZGC fare far better now.
Memory. ZGC uses more memory than G1 for the same live set. It needs headroom to stay ahead of allocation, and it keeps multi-mapped memory that makes some tools report a larger resident size than it really uses. Plan for a heap larger than your G1 heap by a margin that you find by measurement; 10 to 30 percent is common, and more for allocation-heavy services.
Tuning. There is far less to tune. -Xmx and the number of concurrent GC threads (-XX:ConcGCThreads) are the usual dials. The cargo-cult flags of G1 tuning have no equivalent, which is a feature; the G1 side is in tuning G1 without cargo culting.
Tooling. Heap histograms, dumps and the JFR events work as before. GC logs have a different format, so a log parser written for G1 needs updating; the shape of the log is explained in reading GC logs to find the real problem.
Sizing
The central rule is that ZGC needs room. It collects concurrently, so allocation continues while a cycle runs, and if the application allocates faster than the collector can free, the heap fills and threads stall waiting for memory (an allocation stall, visible in the log). The remedy is a bigger heap or more concurrent threads, not a pause-time target.
For a container, derive the heap from measurements and the container limit, as laid out in Java heap size in a container with real numbers; then raise the heap above the G1 value:
java -XX:+UseZGC -XX:MaxRAMPercentage=70 -XX:SoftMaxHeapSize=2g -jar app.jarSoftMaxHeapSize tells ZGC the heap size to try to stay under, below the hard maximum, so it collects earlier and returns memory to the operating system when it can, while still having the full maximum to absorb a spike. Watch the log for the lines that mean trouble:
[12.331s][info][gc] Allocation Stall (http-nio-8080-exec-7) 3.412ms
[12.598s][info][gc] Garbage Collection (Allocation Rate) 3810M(93%)->1204M(29%)An Allocation Stall means a thread had to wait for memory, which is the failure mode to avoid; a few milliseconds occasionally is tolerable, repeated stalls are not. Increase the heap or reduce the allocation rate. In a container, count the non-heap memory too: ZGC's bookkeeping and the multi-mapping are included in the process's memory in some views, so check the container's working set, not just the heap graph.
Compare before switching
Do not switch on a hunch. A comparison takes an afternoon and prevents a regression.
- Same build, same load, one flag different. Run the service under a realistic load test with G1 and again with generational ZGC, on identical hardware, heap and container limits (heap larger for ZGC, as above).
- Collect the same measures. Latency percentiles (p50, p99, p99.9), throughput, CPU use, resident memory, the GC pause distribution and the number of allocation stalls.
- Run long enough to reach steady state and several full cycles: 30 minutes at minimum, a day for services with daily patterns.
- Include a bad day: a traffic spike and a cache cold start.
java -XX:+UseG1GC -Xmx4g -Xlog:gc*:file=g1.log:time,uptime -jar app.jar
java -XX:+UseZGC -Xmx5g -Xlog:gc*:file=zgc.log:time,uptime -jar app.jarCompare pause maxima and p99.9 latency from your load tool, not only the GC logs. A collector can win on pauses and lose on overall throughput by 5 percent; whether that is a good trade is a product decision. The broader comparison with Shenandoah and Parallel, with decision criteria, is in G1 versus ZGC versus Shenandoah and Parallel.
When to stay on G1
G1 remains a good default, and ZGC is not always an improvement.
- Small heaps (under 2 to 4 GiB) where G1 pauses are already short; ZGC's benefit is largely in big heaps and strict latency targets.
- CPU-bound services with no spare cores, where ZGC's concurrent threads and barriers cost throughput you cannot afford.
- Batch jobs and throughput-oriented work, where pauses do not matter and Parallel or G1 gets more work done per CPU second.
- Tight memory. If you cannot give ZGC extra headroom, it will stall.
- Very small containers, under about 1 GiB, where the fixed overhead dominates.
- No latency problem. If p99 is within its objective with G1, the switch buys nothing and adds a risk.
The decision follows the measurement: if G1's pauses are the cause of tail latency you can see, ZGC is the fix; if they are not, leave it.
Rollback
A collector change is reversible by a flag, which is why it is a safe experiment. Do it with a canary: one instance, or a small percentage of traffic, on ZGC for a day, with the dashboard open. Keep the G1 flags in the deployment configuration, commented or behind a variable, so the rollback is a one-line change and a restart:
env:
- name: JAVA_TOOL_OPTIONS
value: "-XX:+UseZGC -XX:MaxRAMPercentage=70" # was: -XX:+UseG1GC -XX:MaxRAMPercentage=70Roll back when you see repeated allocation stalls, throughput regression beyond your tolerance, container memory approaching the limit or kills. Because the collector does not change data formats or behavior, the rollback has no migration cost.
Where this does not apply
If you run JDK 17, generational ZGC is not available there (it arrived in 21), and the non-generational ZGC of 17 is a different, less capable collector, so the comparison in this post does not hold. If your latency problem is not GC (a slow query, lock contention, a cold cache), changing the collector will not fix it; confirm with GC logs that pauses line up with the slow requests. And if you run a native image, the garbage collector is a different one, selected at build time.


