Path 2 · lesson 1 of 4
Garbage collection: G1 and ZGC
How G1 and ZGC reclaim memory in JDK 21, what each one pauses for, what each one costs, and how to choose between them from a latency goal and a heap size.
What you will learn
- Explain the generational hypothesis and how both collectors use it
- Describe a G1 cycle: young collections, concurrent marking, mixed collections, and the full collection it falls back to
- Say what makes an object humongous in G1 and recognise it in a log
- Explain how ZGC moves objects while the application runs, at the level of load barriers and coloured pointers
- Enable generational ZGC correctly on JDK 21 and state what changed in later releases
- Choose G1 or ZGC from a pause goal, a heap size and the CPU and memory you can spare
Before you start
The concept
A garbage collector answers one question over and over: which objects can the program still reach? It starts from the GC roots (local variables on thread stacks, static fields, JNI handles), follows every reference, and treats everything it reached as live. Whatever it did not reach is garbage, and its memory can be reused. Collectors differ in when they do this work and in how much of it happens while your threads are stopped.
Two numbers describe a service to its collector. The allocation rate is how many megabytes of new objects it creates per second. The live set is how much memory is still reachable after a collection. The heap has to hold the live set plus enough free space to absorb allocation until the next collection finishes. Almost every GC problem in production is one of those two numbers being larger than the heap was sized for.
| G1 | ZGC | |
|---|---|---|
| Selected by | Default on server-class machines (2 or more CPUs and at least 1792 MB of memory), or -XX:+UseG1GC | -XX:+UseZGC. On JDK 21 add -XX:+ZGenerational for the generational version |
| Stops application threads for | Every young and mixed collection, plus short Remark and Cleanup pauses | Three very short pauses per cycle. The GC tuning guide puts them below one millisecond |
| Pause length depends on | How much live data the pause has to copy | Neither heap size nor live set |
| Work done while the application runs | Marking the old generation | Marking, relocating objects and fixing references |
| Goal you give it | -XX:MaxGCPauseMillis, 200 ms by default, a soft target | None. The main setting is the maximum heap size |
| What it costs | Pauses of milliseconds to tens of milliseconds, more under pressure | Some throughput, CPU for concurrent work, and more heap headroom |
Why it exists
A stop-the-world pause stops every application thread at the same moment. A request that arrives during a 40 ms pause waits 40 ms before a single line of its handler runs, and so does every other request in flight. Average latency barely moves, because pauses are rare compared with requests. The 99th percentile does, because the unlucky requests all sit in the same place.
You cannot get short pauses, high throughput and a small heap at once. Short pauses mean doing the work concurrently, which takes CPU away from request threads and needs free heap for the application to allocate into while the collector is still running. The choice between G1 and ZGC is a choice of which of the three you are prepared to pay with.
GC logG1, live set 60 MB in a 256 MB heap (java -Xmx256m -Xlog:gc GcPressure.java 60)
Real JVM output[0.002s][info][gc] Using G1 [0.225s][info][gc] GC(0) Pause Young (Normal) (G1 Evacuation Pause) 7M->3M(126M) 2.640ms [0.305s][info][gc] GC(1) Pause Young (Normal) (G1 Evacuation Pause) 8M->4M(126M) 2.440ms [0.399s][info][gc] GC(2) Pause Young (Normal) (G1 Evacuation Pause) 16M->6M(126M) 3.195ms ... [8.300s][info][gc] GC(87) Pause Young (Normal) (G1 Evacuation Pause) 110M->91M(130M) 1.010ms [8.409s][info][gc] GC(88) Pause Young (Normal) (G1 Evacuation Pause) 113M->98M(130M) 0.899ms live set target 60 MB, max heap 256 MB requests 7,440 in 8 s, allocated 1,600 MB (200 MB/s) slowest five requests (ms): [4, 5, 6, 6, 7]
Pause Young line is one stop-the-world collection: heap used before, heap used after, heap committed in brackets, and the pause. The run has 76 of them in 8 seconds, the longest 5.9 ms, and no line containing Pause Full. The slowest request took 7 ms: roughly one pause.How it works inside
G1: a heap made of regions
G1 divides the heap into equally sized regions. The size is a power of two between 1 MB and 32 MB, chosen at startup so that the heap has about 2048 regions, or set with -XX:G1HeapRegionSize. Each region is at any moment free, eden, survivor, old, or part of a humongous object. The generations are therefore not two contiguous blocks of memory but two sets of regions, and G1 can change how many regions each has from one collection to the next.
GC logWhat G1 decided at startup (java -Xmx256m -Xlog:gc* ...)
Real JVM output[0.004s][info][gc,init] CPUs: 2 total, 2 available [0.004s][info][gc,init] Memory: 7932M [0.004s][info][gc,init] Compressed Oops: Enabled (32-bit) [0.004s][info][gc,init] Heap Region Size: 1M [0.004s][info][gc,init] Heap Min Capacity: 8M [0.004s][info][gc,init] Heap Initial Capacity: 124M [0.004s][info][gc,init] Heap Max Capacity: 256M [0.004s][info][gc,init] Parallel Workers: 2 [0.004s][info][gc,init] Concurrent Workers: 1
gc,init lines are the first thing to read in any GC log, because they state the facts every later line depends on. Here: 1 MB regions (so 256 of them), 2 threads for stop-the-world work and 1 for concurrent marking. Heap Initial Capacity: 124M is why the early log lines show (126M) in brackets although the limit is 256 MB: G1 commits memory as it needs it unless -Xms equals -Xmx.G1: young collections
Application threads allocate into eden regions. When the eden regions G1 has allowed are full, it stops the application and evacuates: it copies every live object out of eden and survivor regions into new survivor regions, or into old regions once an object has survived enough collections. The emptied regions become free. Dead objects are never touched, which is why a young collection that finds little alive is fast no matter how much garbage it clears. The log calls this Pause Young (Normal) (G1 Evacuation Pause).
To collect the young regions without scanning the old ones, G1 keeps a remembered set for each region: a record of locations elsewhere in the heap that hold references into it. Application threads maintain it through a small piece of code run on every reference store (a write barrier), and background refinement threads keep it up to date.
G1: concurrent marking and mixed collections
Young collections alone never free the old generation. When old-generation occupancy crosses the Initiating Heap Occupancy threshold (-XX:InitiatingHeapOccupancyPercent, 45 at first, then adjusted automatically by adaptive IHOP), the next young collection is a Concurrent Start: it also begins concurrent marking, which traces the whole live object graph while the application keeps running. Marking uses snapshot-at-the-beginning: everything that was live when marking started is treated as live for this cycle.
GC logOne concurrent marking cycle in detail (-Xlog:gc*, live set 215 MB)
Real JVM output[4.668s][info][gc ] GC(46) Concurrent Mark Cycle [4.668s][info][gc,marking ] GC(46) Concurrent Scan Root Regions [4.670s][info][gc,marking ] GC(46) Concurrent Scan Root Regions 1.776ms [4.670s][info][gc,marking ] GC(46) Concurrent Mark [4.670s][info][gc,marking ] GC(46) Concurrent Mark From Roots [4.670s][info][gc,task ] GC(46) Using 1 workers of 1 for marking [4.674s][info][gc,marking ] GC(46) Concurrent Mark From Roots 4.390ms [4.674s][info][gc,marking ] GC(46) Concurrent Preclean [4.674s][info][gc,marking ] GC(46) Concurrent Preclean 0.012ms [4.675s][info][gc,start ] GC(46) Pause Remark [4.677s][info][gc ] GC(46) Pause Remark 254M->248M(256M) 2.312ms [4.677s][info][gc,marking ] GC(46) Concurrent Mark 7.430ms [4.677s][info][gc,marking ] GC(46) Concurrent Rebuild Remembered Sets and Scrub Regions [4.681s][info][gc,marking ] GC(46) Concurrent Rebuild Remembered Sets and Scrub Regions 3.547ms [4.681s][info][gc,start ] GC(46) Pause Cleanup [4.681s][info][gc ] GC(46) Pause Cleanup 249M->249M(256M) 0.100ms [4.682s][info][gc ] GC(46) Concurrent Mark Cycle 13.880ms
Pause stop the application: Remark for 2.3 ms and Cleanup for 0.1 ms. Everything labelled Concurrent ran beside it, on the one marking thread the gc,task line reports. The cycle took 13.9 ms of wall-clock time and paused the application for 2.4 ms of it. This heap is tiny; on a multi-gigabyte heap the concurrent part takes seconds, and the application allocates the whole time.Marking tells G1 how much live data each old region holds. If enough space is worth reclaiming, the following young collections are mixed: besides all young regions they also evacuate a few old regions, starting with the ones that are mostly garbage (hence the name, garbage first). G1 spreads this over several pauses and stops when the remaining candidates are not worth the copying.
| Log line | What happened | Stops the application |
|---|---|---|
Pause Young (Normal) | Evacuated the young regions | Yes |
Pause Young (Concurrent Start) | A young collection that also started concurrent marking | Yes |
Concurrent Mark Cycle | Marking of the old generation | No, apart from Remark and Cleanup |
Pause Remark | Finished marking, processed references, unloaded classes, freed completely empty regions | Yes, briefly |
Pause Cleanup | Decided whether mixed collections will follow | Yes, very briefly |
Pause Young (Prepare Mixed) | The last young-only collection before mixed ones | Yes |
Pause Young (Mixed) | Evacuated young regions plus some old regions | Yes |
Pause Full (G1 Compaction Pause) | The fallback: mark and compact the entire heap with everything stopped | Yes, for the longest of all |
The pause target
-XX:MaxGCPauseMillis (200 by default) is a goal, not a limit. G1 measures how long evacuation takes and uses it to predict how many young regions it can collect within the goal, then sizes the young generation accordingly, between 5% and 60% of the heap by default. A lower target means a smaller young generation and more frequent pauses; it does not make the collector faster. Fixing the young size yourself with -Xmn takes away the one control G1 uses to meet the goal, which is why the tuning guide tells you not to.
Humongous objects
An object whose size is at least half a region is humongous. With 1 MB regions that is any array of 512 kB or more. G1 does not allocate it in eden: it goes straight into the old generation, in its own run of contiguous regions, and the unused tail of the last region is wasted until the object dies. Every humongous allocation also checks the marking threshold and can start a concurrent cycle on the spot.
GC log600 kB buffers with 1 MB regions (java -Xmx256m -Xlog:gc,gc+heap GarbageCollectionG1Zgc.java 600)
Real JVM output[1.065s][info][gc,heap] GC(3) Eden regions: 2->0(25) [1.065s][info][gc,heap] GC(3) Survivor regions: 2->3(5) [1.065s][info][gc,heap] GC(3) Old regions: 5->5 [1.065s][info][gc,heap] GC(3) Humongous regions: 51->20 [1.065s][info][gc ] GC(3) Pause Young (Concurrent Start) (G1 Humongous Allocation) 58M->26M(126M) 8.213ms [1.065s][info][gc ] GC(4) Concurrent Undo Cycle [1.067s][info][gc ] GC(4) Concurrent Undo Cycle 2.179ms [1.074s][info][gc,heap] GC(5) Eden regions: 0->0(34) [1.074s][info][gc,heap] GC(5) Survivor regions: 3->2(4) [1.074s][info][gc,heap] GC(5) Old regions: 5->6 [1.074s][info][gc,heap] GC(5) Humongous regions: 51->20 [1.074s][info][gc ] GC(5) Pause Young (Concurrent Start) (G1 Humongous Allocation) 57M->26M(126M) 4.384ms ... buffers of 600 kB, allocated 878 MB in total, 20 kept alive
G1 Humongous Allocation, not G1 Evacuation Pause: the collection was triggered by a large array, not by eden filling up. Eden regions: 2->0 and 0->0 show eden was almost unused when it happened. And Humongous regions: 51->20: each 600 kB buffer occupies a whole 1 MB region, so 40% of every one of those regions is wasted. The same program with 400 kB buffers produced 13 ordinary young collections instead of 27 humongous-triggered ones.ZGC: moving objects while the application runs
G1 pauses the application to move objects because moving an object changes its address, and every reference to it has to change with it. ZGC removes that pause by letting references be temporarily out of date and repairing them at the moment they are used. Two mechanisms make that safe:
- Coloured pointers. A reference stored in an object field carries a few metadata bits besides the address. The bits record what the collector knows about that reference: for instance whether it has been marked, and whether the address is still correct after relocation. This needs 64-bit references, so ZGC never uses compressed object pointers.
- Load barriers. Wherever compiled application code reads a reference from a field, the JIT inserts a short check of those bits. If the reference is in the good state, the check costs a few instructions. If it is stale, a slow path looks up the object's new address, repairs the field, and the application continues with a correct reference.
- Store barriers (generational ZGC only). Code run when a reference is written, which tracks pointers from the old generation into the young one and does the marking bookkeeping.
With those in place, marking and relocation can both run on GC threads beside the application. What remains stop-the-world is three short synchronisation points per cycle, whose length does not grow with the heap.
GC logOne generational ZGC young collection (-XX:+UseZGC -XX:+ZGenerational -Xlog:gc*, live set 60 MB)
Real JVM output[2.536s][info][gc ] GC(4) Minor Collection (Allocation Rate) [2.536s][info][gc,task ] GC(4) Using 1 Workers for Young Generation [2.536s][info][gc,phases ] GC(4) y: Young Generation [2.536s][info][gc,phases ] GC(4) y: Pause Mark Start 0.009ms [2.564s][info][gc,phases ] GC(4) y: Concurrent Mark 27.595ms [2.567s][info][gc,phases ] GC(4) y: Pause Mark End 0.011ms [2.567s][info][gc,phases ] GC(4) y: Concurrent Mark Free 0.000ms [2.567s][info][gc,phases ] GC(4) y: Concurrent Reset Relocation Set 0.004ms [2.579s][info][gc,phases ] GC(4) y: Concurrent Select Relocation Set 12.335ms [2.582s][info][gc,phases ] GC(4) y: Pause Relocate Start 0.009ms [2.618s][info][gc,phases ] GC(4) y: Concurrent Relocate 35.354ms [2.618s][info][gc,alloc ] GC(4) y: Allocation Stalls: 0 0 0 0 [2.618s][info][gc,phases ] GC(4) y: Young Generation 198M(77%)->100M(39%) 0.082s [2.618s][info][gc ] GC(4) Minor Collection (Allocation Rate) 198M(77%)->100M(39%) 0.082s
Pause lines add up to 0.029 ms. The collection as a whole took 82 ms (0.082s on the last line), and for all of it the application kept running and allocating. That last number is a duration, not a pause: reading it as a pause is the most common mistake with ZGC logs. Allocation Stalls: 0 in all four columns is the line that says nobody had to wait for memory.Generational ZGC is opt-in on JDK 21
Until JDK 21, ZGC kept all objects together and had to mark the whole heap in every cycle. JEP 439 added a young and an old generation, collected independently, so that the cheap young collections (Minor Collection in the log) run often and the expensive old ones (Major Collection) rarely. Its stated goals are a lower risk of allocation stalls, less heap overhead and less GC CPU.
Program outputThe collector names the JVM reports (GarbageCollectionG1ZgcReport.java)
Real JVM output$ java -XX:ActiveProcessorCount=2 -Xmx256m GarbageCollectionG1ZgcReport.java collector beans: G1 Young Generation collections=18 total time=677 ms G1 Concurrent GC collections=6 total time=86 ms G1 Old Generation collections=0 total time=0 ms ... $ java -XX:ActiveProcessorCount=2 -Xmx256m -XX:+UseZGC -XX:+ZGenerational GarbageCollectionG1ZgcReport.java collector beans: ZGC Minor Cycles collections=4 total time=222 ms ZGC Minor Pauses collections=12 total time=0 ms ZGC Major Cycles collections=3 total time=1258 ms ZGC Major Pauses collections=15 total time=0 ms ... $ java -XX:ActiveProcessorCount=2 -Xmx256m -XX:+UseZGC GarbageCollectionG1ZgcReport.java collector beans: ZGC Cycles collections=4 total time=823 ms ZGC Pauses collections=12 total time=0 ms
ZGC Minor and ZGC Major beans mean generational ZGC. Plain ZGC Cycles and ZGC Pauses mean the non-generational one, which is what the third command got by leaving out -XX:+ZGenerational. The Pauses beans report 0 ms in total because each pause is a few microseconds. The Cycles times are concurrent durations. G1 Old Generation counts full collections: it should stay at 0.When ZGC runs out of headroom
A concurrent collector frees memory while the application is still allocating. If the live set leaves too little free heap, allocation catches up with the collector before a cycle finishes. ZGC then makes the allocating thread wait.
GC logGenerational ZGC, live set 215 MB in a 256 MB heap (-Xlog:gc GcPressure.java 215)
Real JVM output[5.231s][info][gc] Allocation Stall (main) 2.220ms [5.232s][info][gc] GC(63) Minor Collection (Allocation Stall) [5.244s][info][gc] GC(63) Minor Collection (Allocation Stall) 252M(98%)->254M(99%) 0.012s [5.254s][info][gc] GC(64) Minor Collection (Allocation Stall) [5.259s][info][gc] Allocation Stall (main) 5.027ms [5.264s][info][gc] GC(64) Minor Collection (Allocation Stall) 256M(100%)->252M(98%) 0.009s ... [5.319s][info][gc] Allocation Stall (main) 3.687ms
Allocation Stall (main) 5.027ms means the thread named main asked for memory and waited 5 ms for it. The heap is at 98 to 100% before and after each collection: the collector is running back to back (about 190 collections in 8 seconds in this run) and recovering almost nothing, because nearly everything is live. The log has no Pause line at all, and seven stalls of up to 5 ms. The remedy is the same as for G1 under the same conditions: more heap or a smaller live set.Architecture
Drawing diagram…
Flowchart. From the pause goal, services that tolerate tens of milliseconds stay on G1 and only fix sizing if the log shows full collections or long pauses. Services that need pauses of a few milliseconds or less move to generational ZGC, but only if they can provide extra heap and CPU. Otherwise they stay on G1.
flowchart TD
A["GC pause goal for the service"] --> B{"Are pauses of tens of milliseconds acceptable at p99"}
B -->|"Yes"| C["G1, the default"]
B -->|"No, single digit milliseconds or less"| D{"Can you give it more heap and some CPU"}
C --> E{"Does the log show Pause Full or pauses above the goal"}
E -->|"No"| F["Keep G1, leave the flags alone"]
E -->|"Yes"| G["Fix heap size, live set or allocation rate first"]
G --> H{"Still above the goal with a healthy log"}
H -->|"Yes"| D
H -->|"No"| F
D -->|"Yes"| I["ZGC with ZGenerational on JDK 21"]
D -->|"No"| J["Stay on G1, a starved ZGC stalls allocations"]
I --> K["Watch for Allocation Stall in the log"]- Start with G1. It is the default, it needs no configuration beyond a heap size, and a healthy G1 pause on a few gigabytes of heap is in the low tens of milliseconds or less. Many services with a p99 target of 100 ms or more never need anything else.
- A G1 log with
Pause Fullin it is not an argument for switching collector. It says the heap is too small for the live set and allocation rate. ZGC under the same conditions produces allocation stalls instead, as the lab showed. Fix the sizing, then judge the collector. - Move to ZGC when a correctly sized G1 still pauses for longer than the service can tolerate, typically because the live set is large (pause time in G1 grows with the live data it copies) or because the latency goal is in single-digit milliseconds.
- ZGC's price is headroom and CPU. It does not use compressed object pointers, so reference-heavy data takes more memory than under G1 on heaps below 32 GB, and its concurrent threads compete with request threads. On a container limited to one or two CPUs that competition is visible.
Step by step
Drawing diagram…
Sequence diagram with application threads, G1 pause workers and the concurrent marking thread. Young collections pause the application to copy live objects. When the old generation passes its threshold, a Concurrent Start pause begins marking, which runs alongside the application and ends with Remark and Cleanup pauses, followed by a Prepare Mixed and then Mixed collections.
sequenceDiagram participant A as Application threads participant G as G1 pause workers participant M as Concurrent marking thread A->>G: Eden regions are full Note over A,G: Pause Young Normal, live objects copied to survivor and old regions G-->>A: Resume, eden is empty again A->>G: Eden full and old occupancy above the threshold Note over A,G: Pause Young Concurrent Start G->>M: Start marking the old generation G-->>A: Resume Note over A,M: Application runs while marking traces the live objects M->>G: Marking almost done Note over A,G: Pause Remark, then Pause Cleanup G-->>A: Resume A->>G: Eden regions are full Note over A,G: Pause Young Prepare Mixed A->>G: Eden regions are full Note over A,G: Pause Young Mixed, young regions plus the emptiest old regions G-->>A: Resume with old regions freed
- Every box that spans the application and the pause workers is a stop-the-world pause. The only stretch in which GC work and application work overlap is concurrent marking.
- The application keeps allocating during marking. If it fills the heap before marking and the mixed collections have freed old regions, G1 has nowhere to copy survivors to. It logs
(Evacuation Failure)on the young collection and falls back toPause Full. - In ZGC the same picture has three pauses of microseconds, and both marking and relocation are in the concurrent stretch. The failure mode moves from a long pause to an allocation stall, but its cause is the same: allocation outran reclamation.
In a real system
The lab program runs the same workload four ways: a request loop that allocates 200 MB per second and keeps a sliding window of session data alive, in a 256 MB heap. Only the live set and the collector change.
| Collector | Live set | What the log shows | Slowest five requests (ms) |
|---|---|---|---|
| G1 | 60 MB | 76 young pauses, longest 5.9 ms, no full collection | 4, 5, 6, 6, 7 |
| G1 | 215 MB | 114 young pauses, 29 marked (Evacuation Failure), 8 Pause Full of 15 to 21 ms | 18, 19, 20, 21, 22 |
| Generational ZGC | 60 MB | 16 collections, no stalls | 0, 0, 0, 0, 3 |
| Generational ZGC | 215 MB | About 190 collections, 7 allocation stalls of up to 5 ms | 2, 2, 2, 3, 5 |
GC logG1 when the live set nearly fills the heap (-Xlog:gc GcPressure.java 215)
Real JVM output[4.346s][info][gc] GC(37) Pause Young (Concurrent Start) (G1 Evacuation Pause) (Evacuation Failure) 251M->245M(256M) 0.664ms [4.346s][info][gc] GC(38) Concurrent Mark Cycle [4.354s][info][gc] GC(38) Pause Remark 246M->241M(256M) 1.042ms [4.356s][info][gc] GC(38) Pause Cleanup 242M->242M(256M) 0.061ms [4.356s][info][gc] GC(38) Concurrent Mark Cycle 10.857ms [4.395s][info][gc] GC(39) Pause Young (Prepare Mixed) (G1 Evacuation Pause) 249M->243M(256M) 0.644ms [4.445s][info][gc] GC(40) Pause Young (Mixed) (G1 Evacuation Pause) (Evacuation Failure) 253M->249M(256M) 0.610ms [4.480s][info][gc] GC(41) Pause Young (Concurrent Start) (G1 Evacuation Pause) (Evacuation Failure) 255M->255M(256M) 0.881ms [4.480s][info][gc] GC(43) Concurrent Mark Cycle [4.501s][info][gc] GC(42) Pause Full (G1 Compaction Pause) 255M->218M(256M) 20.922ms [4.501s][info][gc] GC(43) Concurrent Mark Cycle 21.024ms ... slowest five requests (ms): [18, 19, 20, 21, 22]
255M->255M(256M): the heap is full and a young collection freed nothing. (Evacuation Failure) says G1 found no free region to copy survivors into. The next line is Pause Full, which frees memory down to 218 MB: that number is the live set. The collector is not misbehaving. 215 MB of live data plus 200 MB per second of allocation do not fit in 256 MB. The slowest requests, 18 to 22 ms, are the full collections.Scale the numbers up and this is a normal production story. A checkout service with a 4 GB heap, a 1.2 GB live set and a p99 target of 150 ms runs on G1 with default flags for years. A pricing gateway that must answer in 10 ms at p99 with an 8 GB live set cannot: a G1 mixed collection that copies part of that data takes longer than its whole budget. It moves to generational ZGC, is given a 24 GB heap instead of 16 GB, and its owners alert on allocation stalls rather than on pause time. The investigation case on latency spikes starts from the symptom side of the same problem.
Java and Spring Boot
Choosing a collector is one or two flags. What a service should add is the evidence: a GC log from the first day, and a line at startup that states which collector is actually running, so that a test labelled "ZGC" was not run on the non-generational mode by accident. The flag lines were started on OpenJDK 21.0.13 here. The Spring class is written against Spring Boot 3.5 and was not compiled against Spring in this environment; its use of java.lang.management is the same as in the lab program that produced the output above.
# G1 is already the default on a machine with 2+ CPUs and 1792 MB+ of memory.# State the heap, keep the default pause goal, and always write a GC log.JAVA_TOOL_OPTIONS="-Xms4g -Xmx4g \ -Xlog:gc*:file=/var/log/checkout/gc.log:time,uptime,level,tags:filecount=5,filesize=20m"Why it is written this way
- No
-XX:+UseG1GC, no pause target, no generation sizes: the defaults are the recommended starting point in the G1 tuning guide. Add-XX:MaxGCPauseMillisonly when you have a measured reason. -Xmsequal to-Xmxmakes the JVM commit the whole heap at startup instead of growing it under load. It also means the container's memory need is known from the first second.-Xlog:gc*writes every message whose tags includegcat info level.file=sends it to a file, the third field picks the decorations on each line, andfilecountwithfilesizerotate it: five files of 20 MB.
# Generational ZGC on JDK 21 needs BOTH flags. -XX:+UseZGC alone is the non-generational collector.JAVA_TOOL_OPTIONS="-XX:+UseZGC -XX:+ZGenerational -Xms24g -Xmx24g \ -Xlog:gc*:file=/var/log/pricing/gc.log:time,uptime,level,tags:filecount=5,filesize=20m"Why it is written this way
- The heap is larger than the G1 configuration it replaces. ZGC needs room for the application to allocate into while a concurrent cycle runs; the tuning guide's advice is that, in general, the more memory you give ZGC the better.
- No pause target: ZGC has none to set. Its main tuning option is the maximum heap size.
- On JDK 23 and later the generational mode is the default and
-XX:+ZGenerationalis no longer needed. Keep the flag in a JDK 21 deployment and remove it when you upgrade.
package com.example.checkout.ops;import java.lang.management.GarbageCollectorMXBean;import java.lang.management.ManagementFactory;import java.util.List;import org.slf4j.Logger;import org.slf4j.LoggerFactory;import org.springframework.boot.ApplicationArguments;import org.springframework.boot.ApplicationRunner;import org.springframework.stereotype.Component;/** Logs, once at startup, which collector this JVM is really using and how large its heap may get. */@Componentpublic class CollectorReport implements ApplicationRunner { private static final Logger log = LoggerFactory.getLogger(CollectorReport.class); @Override public void run(ApplicationArguments args) { List<String> collectors = ManagementFactory.getGarbageCollectorMXBeans().stream() .map(GarbageCollectorMXBean::getName) .toList(); long maxHeapMb = Runtime.getRuntime().maxMemory() / (1024 * 1024); log.info("collectors={} maxHeapMb={} cpus={}", collectors, maxHeapMb, Runtime.getRuntime().availableProcessors()); if (collectors.contains("ZGC Cycles")) { log.warn("Running non-generational ZGC. On JDK 21 add -XX:+ZGenerational to -XX:+UseZGC."); } }}Why it is written this way
- The bean names identify the collector:
G1 Young Generation,G1 Concurrent GCandG1 Old Generationfor G1;ZGC Minor Cycles,ZGC Minor Pauses,ZGC Major CyclesandZGC Major Pausesfor generational ZGC;ZGC CyclesandZGC Pausesfor the non-generational one. These are the names OpenJDK 21.0.13 printed in the run above. availableProcessors()andmaxMemory()are what the JVM believes after container limits are applied. A container limited to one CPU gets the Serial collector by default, not G1, and this line is where you would notice.- The warning costs nothing and catches the single most common ZGC configuration mistake on JDK 21.
Wrong, then right
An order export endpoint builds a CSV file for a merchant. Files are a few megabytes. The service runs on G1 with a 256 MB heap in the test environment and 2 GB in production, so regions are 1 MB in both. The first version works, and the GC log fills with collections that eden did not ask for.
Incorrect implementation
package com.example.orders.export;import java.io.ByteArrayOutputStream;import java.io.IOException;import java.io.OutputStreamWriter;import java.io.Writer;import java.nio.charset.StandardCharsets;import org.springframework.http.MediaType;import org.springframework.http.ResponseEntity;import org.springframework.web.bind.annotation.GetMapping;import org.springframework.web.bind.annotation.PathVariable;import org.springframework.web.bind.annotation.RestController;@RestControllerpublic class OrderExportController { private final OrderRepository orders; public OrderExportController(OrderRepository orders) { this.orders = orders; } @GetMapping("/merchants/{merchantId}/orders.csv") public ResponseEntity<byte[]> export(@PathVariable long merchantId) throws IOException { // The whole file is assembled in memory before the first byte is sent. ByteArrayOutputStream buffer = new ByteArrayOutputStream(); try (Writer out = new OutputStreamWriter(buffer, StandardCharsets.UTF_8)) { out.write("order_id,placed_at,total\n"); for (OrderRow row : orders.findByMerchant(merchantId)) { out.write(row.orderId() + "," + row.placedAt() + "," + row.total() + "\n"); } } byte[] file = buffer.toByteArray(); // a second full-size copy return ResponseEntity.ok().contentType(MediaType.parseMediaType("text/csv")).body(file); }}Why it is written this way
ByteArrayOutputStreamgrows by allocating a larger array and copying the old one into it. On the way to a 3 MB file it allocates arrays of roughly 512 kB, 1 MB, 2 MB and 4 MB, andtoByteArray()then allocates one more of the final size.findByMerchantreturning a list means every row object for the export is also alive at once.
Why it fails
- With 1 MB regions, every array of 512 kB or more is humongous. It is not allocated in eden and it is never collected by ordinary evacuation: it is placed directly in the old generation in a run of contiguous regions, and the unused part of its last region is wasted for as long as it lives.
- Each humongous allocation checks the marking threshold and can force a
Concurrent Startcollection immediately. In the real run above, 600 kB buffers turned 13 ordinary young collections into 27 collections with the causeG1 Humongous Allocation, each followed by a concurrent cycle that was started and then abandoned. - A burst of exports puts tens of megabytes straight into the old generation. Old occupancy jumps, marking runs back to back, and because humongous objects need contiguous free regions, a fragmented heap can fail to place one even though the total free space is sufficient. The G1 tuning guide lists this as a cause of full collections.
- In production you would see it as latency spikes on unrelated endpoints whenever exports run,
Pause Young (Concurrent Start) (G1 Humongous Allocation)in the GC log, andHumongous regions: X->Ywith a largeXunder-Xlog:gc+heap.
Corrected implementation
package com.example.orders.export;import java.io.BufferedWriter;import java.io.OutputStreamWriter;import java.io.Writer;import java.nio.charset.StandardCharsets;import java.util.stream.Stream;import org.springframework.http.MediaType;import org.springframework.http.ResponseEntity;import org.springframework.web.bind.annotation.GetMapping;import org.springframework.web.bind.annotation.PathVariable;import org.springframework.web.bind.annotation.RestController;import org.springframework.web.servlet.mvc.method.annotation.StreamingResponseBody;@RestControllerpublic class OrderExportController { private final OrderRepository orders; public OrderExportController(OrderRepository orders) { this.orders = orders; } @GetMapping("/merchants/{merchantId}/orders.csv") public ResponseEntity<StreamingResponseBody> export(@PathVariable long merchantId) { StreamingResponseBody body = response -> { // Rows are read and written one at a time. The largest array is the writer's 8 kB buffer. try (Stream<OrderRow> rows = orders.streamByMerchant(merchantId); Writer out = new BufferedWriter(new OutputStreamWriter(response, StandardCharsets.UTF_8), 8 * 1024)) { out.write("order_id,placed_at,total\n"); for (OrderRow row : (Iterable<OrderRow>) rows::iterator) { out.write(Long.toString(row.orderId())); out.write(','); out.write(row.placedAt().toString()); out.write(','); out.write(row.total().toPlainString()); out.write('\n'); } } }; return ResponseEntity.ok().contentType(MediaType.parseMediaType("text/csv")).body(body); }}Why it is written this way
StreamingResponseBodylets the handler write to the response stream directly. Nothing the size of the file ever exists on the heap, so nothing is humongous.streamByMerchantreturns aStreambacked by a database cursor, closed by the try-with-resources. EachOrderRowbecomes garbage as soon as it is written, which is exactly the short-lived allocation a young collection is good at.- Writing the fields separately avoids building one concatenated
Stringper row. It is a small saving per row, and this loop runs once per order. OrderRepositoryandOrderRow(a record withorderId,placedAtandtotal) are assumed to exist. The streaming logic was compiled on JDK 21 against stand-in Spring types; it was not run inside Spring here.
Trade-offs
- The response has no
Content-Length, because the size is not known in advance. Clients see chunked transfer and cannot show a progress percentage. - The status line is sent before the data. If the database fails halfway through, the client has already received
200 OKand gets a truncated file. The in-memory version could still return an error. - The database cursor and its connection stay open for as long as the client takes to download. A slow client now holds a pooled connection, so the endpoint needs a timeout and a limit on concurrent exports.
- If large arrays cannot be avoided (image or protobuf payloads, for instance), the alternative is a larger region:
-XX:G1HeapRegionSize=4mraises the humongous threshold to 2 MB at the cost of coarser collection units. Measure with-Xlog:gc+heapbefore and after.
Configuration
The flags that select a collector and the few that matter when choosing one. Defaults are those of OpenJDK 21, checked with java -XX:+PrintFlagsFinal -version on 21.0.13 and against the java command reference.
-XX:+UseG1GCDefault Selected automatically on server-class machines (2 or more CPUs and at least 1792 MB of memory); otherwise Serial
- What it does
- Use the G1 collector.
- When to change it
- Rarely needed explicitly. Do check small containers: with one CPU the JVM picks Serial, whose every collection is a single-threaded pause.
-XX:MaxGCPauseMillisDefault 200
- What it does
- G1's pause-time goal in milliseconds. A soft goal that G1 tries to meet by sizing the young generation.
- When to change it
- Leave it until the log shows pauses you cannot accept on a heap that is otherwise healthy. Lowering it trades fewer long pauses for more short ones and more GC work overall.
-XX:G1HeapRegionSizeDefault Ergonomic: a power of 2 from 1 MB to 32 MB, aiming for about 2048 regions
- What it does
- Size of one G1 region. Objects of at least half this size are humongous.
- When to change it
- Raise it only to stop a known, unavoidable object size from being humongous. The
gc,initlog lineHeap Region Sizeshows the value in use.
-XX:InitiatingHeapOccupancyPercentDefault 45
- What it does
- Old-generation occupancy at which G1 starts its first concurrent marking cycles. With adaptive IHOP (on by default) G1 then computes its own threshold.
- When to change it
- Not a first-line setting. If marking starts too late and full collections follow, give G1 more heap before reaching for this.
-XX:+UseZGCDefault Disabled
- What it does
- Use the Z Garbage Collector. On JDK 21 this alone selects the non-generational mode.
- When to change it
- Use together with
-XX:+ZGenerationalon JDK 21 for services whose pause goal G1 cannot meet, and size the heap with headroom.
-XX:+ZGenerationalDefault Disabled in JDK 21 (enabled by default from JDK 23, option removed in JDK 24)
- What it does
- Select generational ZGC (JEP 439): separate young and old generations collected independently.
- When to change it
- Set it whenever you use ZGC on JDK 21. Confirm from the log that collections are named Minor and Major.
-XmxDefault Ergonomic: 25% of available memory (`MaxRAMPercentage=25`)
- What it does
- Maximum heap size.
- When to change it
- The most important setting for both collectors. Size it from the measured live set and allocation rate, not from the container limit alone; the next lesson shows how.
-XX:SoftMaxHeapSizeDefault Equal to the maximum heap size
- What it does
- ZGC only: a heap size ZGC tries to stay under, exceeding it only to avoid stalling the application.
- When to change it
- Useful when you want ZGC to keep the footprint low in normal operation but still have the full
-Xmxavailable for a spike.
Hands-on exercise
The same workload under G1 and ZGC
Run one allocation workload against both collectors, first with a comfortable live set and then with one that nearly fills the heap, and see which symptom each collector produces when it runs out of room.
Steps · 0 of 6 done
256 MB heap, 200 MB/s of allocation
Simulation · not a real JVMChange the collector, the live set, the heap size and the allocation rate one at a time. Watch the heap fill, the kind of each collection and the delay it causes.
What you should see
With a 60 MB live set both collectors are comfortable: G1 shows short young pauses of a few milliseconds and ZGC shows none worth measuring. As the live set approaches the heap size, G1 moves from young to mixed to full collections and its worst delay jumps; ZGC shows no long pause but starts stalling allocations. More heap fixes both. A lower allocation rate makes the problem rarer but does not remove it, because the live set still leaves too little room. The real lab gave the same picture: 8 full collections of 15 to 21 ms for G1 and 7 allocation stalls for ZGC at 215 MB.
What can go wrong
Testing "ZGC" on JDK 21 without -XX:+ZGenerational
- Symptom
- A ZGC trial shows high GC CPU and allocation stalls at a heap size where others report it works well. The log says
Garbage Collection (...)instead ofMinor CollectionandMajor Collection. - Cause
-XX:+UseZGCalone selects non-generational ZGC on JDK 21, which marks the whole heap in every cycle.- Fix
- Use
-XX:+UseZGC -XX:+ZGenerationalon JDK 21, and confirm from the collector names or the log before comparing results.
Switching collector to escape full collections
- Symptom
- G1 logs
Pause Full. The service is moved to ZGC and the long pauses vanish, but p99 latency is no better and CPU use is higher. - Cause
- The heap was too small for the live set. G1 showed it as full collections; ZGC shows it as allocation stalls and back-to-back concurrent cycles.
- Fix
- Size the heap first: compare heap used after a full collection (the live set) with
-Xmx. Then choose the collector on a healthy heap.
Reading a ZGC cycle duration as a pause
- Symptom
- Someone reports that ZGC "paused for 82 ms" from a line such as
Minor Collection (Allocation Rate) 198M(77%)->100M(39%) 0.082s. - Cause
- That figure is how long the concurrent cycle ran. The application was running throughout. The pauses are the
Pause Mark Start,Pause Mark EndandPause Relocate Startlines undergc+phases. - Fix
- Log with
-Xlog:gc*or at leastgc,gc+phases, and read pause lines andAllocation Stalllines separately from cycle durations.
Large arrays on a small-region heap
- Symptom
- Collections with the cause
G1 Humongous Allocation, marking cycles that start far more often than old-generation growth explains, and full collections with free space apparently available. - Cause
- Objects of at least half a region are humongous: allocated in the old generation in contiguous regions, with the tail of the last region wasted.
- Fix
- Stop creating them (stream, chunk, pool), or raise
-XX:G1HeapRegionSizeso the size falls below half a region. Verify with-Xlog:gc+heap.
A one-CPU container silently running Serial
- Symptom
- Pauses grow in proportion to the heap, and the log starts with
Using Serialalthough nobody chose it. - Cause
- G1 is the default only on server-class machines: two or more CPUs and at least 1792 MB of memory, as the JVM sees them inside the container.
- Fix
- Give the container at least two CPUs, or select the collector explicitly, and log the collector at startup.
How to troubleshoot
You do not know which collector a running service uses
Check
jcmd <pid> VM.flags | tr ' ' '\n' | grep -E 'Use(G1|Z|Serial|Parallel)GC|ZGenerational'
- How to read it
- The flag printed with a
+is the collector in use. With-XX:+UseZGCand no-XX:+ZGenerationalon JDK 21 the service is on non-generational ZGC. The first line of any GC log (Using G1,Using The Z Garbage Collector) says the same.
Latency spikes and you suspect G1 pauses
Check
grep -E 'Pause (Young|Full|Remark)' gc.log | awk '{print $NF, $0}' | sort -n | tail -5- How to read it
- The five longest pauses with their type. Young pauses near the goal are normal.
Pause Full, or(Evacuation Failure)on the lines before it, means the heap is too small for the live set and allocation rate.
Latency spikes on ZGC although pauses are microseconds
Check
grep -c 'Allocation Stall' gc.log
- How to read it
- Any number above zero means application threads waited for memory. Check the heap percentage on the collection lines around them: values near 100% before and after mean the live set leaves no headroom.
Marking cycles start much more often than expected
Check
java -Xlog:gc,gc+heap ... then: grep -E 'Humongous regions|Humongous Allocation' gc.log
- How to read it
- A large first number in
Humongous regions: X->Y, or collections whose cause isG1 Humongous Allocation, point at arrays of half a region or more. Compare the array size withHeap Region Sizefrom thegc,initlines.
Key takeaways
- Both collectors rely on the generational hypothesis: collect new objects often, because the cost follows what is alive and most new objects are not.
- G1 stops the application to copy live objects, in young and mixed collections sized to a pause goal of 200 ms by default; only old-generation marking is concurrent.
- ZGC marks and relocates concurrently using coloured pointers and load barriers, so its pauses stay under a millisecond regardless of heap size.
- On JDK 21 generational ZGC needs
-XX:+UseZGC -XX:+ZGenerational.-XX:+UseZGCalone is the older non-generational collector. - Out of room looks different per collector:
Pause Fullafter(Evacuation Failure)in G1,Allocation Stallin ZGC. The cause and the fix are the same. - In G1 an object of half a region or more is humongous. Avoid creating them, or raise the region size.
- Choose from the pause the service can tolerate: G1 by default, ZGC when a healthy G1 still pauses too long and you can pay with heap and CPU.
Practical check
Small scenarios, one decision each. Pick what you would do, then read why.
Scenario 1 of 3
A payment API runs on JDK 21 with G1 and a 6 GB heap. Its p99 target is 200 ms and it is met. The GC log shows young pauses of 15 to 40 ms every two seconds, a marking cycle every few minutes and no Pause Full. A colleague proposes moving to ZGC because "it has no pauses".
What is the right call?
Scenario 2 of 3
A team switches a JDK 21 service to ZGC with -XX:+UseZGC -Xmx8g. Under load the log shows lines such as GC(41) Garbage Collection (Allocation Rate) 6902M(84%)->5120M(63%) and several Allocation Stall entries per minute. The live set measured earlier under G1 was about 3 GB.
What should they check first?
Scenario 3 of 3
A report service on G1 with -Xmx2g logs Heap Region Size: 1M. During month-end, the log fills with Pause Young (Concurrent Start) (G1 Humongous Allocation) and Humongous regions: 410->35. The reports are rendered into a byte[] of 600 to 900 kB each before being written to object storage.
Which change addresses the cause with the least risk?
References
References: Java SE 21 GC Tuning Guide: Garbage-First (G1) Garbage Collector ↗ · Java SE 21 GC Tuning Guide: The Z Garbage Collector ↗ · Java SE 21 GC Tuning Guide: Available Collectors (selecting a collector) ↗ · Java SE 21 GC Tuning Guide: Ergonomics (server-class machine, default selections) ↗ · JEP 439: Generational ZGC (delivered in JDK 21) ↗ · JEP 474: ZGC: Generational Mode by Default (JDK 23) ↗ · The java command, JDK 21 (G1 and ZGC options, -Xlog) ↗ · Report a problem