JVM GC Tuning Guide: G1, ZGC, Shenandoah Explained with Real Trade-offs

package io.thecodeforge.gc;

import java.util.concurrent.ConcurrentHashMap;
import java.util.Map;

/**
 * Demonstrates allocation patterns that stress G1 differently.
 *
 * Key insight: G1 humongous objects (>50% region size) bypass normal
 * allocation and can trigger to-space exhausted failures.
 */
public class G1TuningExample {

    // Cache with large value objects — common source of humongous allocations
    private final Map<String, byte[]> payloadCache = new ConcurrentHashMap<>();

    /**
     * BAD: Allocates objects that may exceed humongous threshold.
     * With default 1MB region size, objects > 512KB are humongous.
     * With 32MB regions, threshold is 16MB — much safer for large payloads.
     *
     * Tuning: -XX:G1HeapRegionSize=32M
     *         -XX:G1ReservePercent=15
     *         -XX:InitiatingHeapOccupancyPercent=35
     */
    public void cacheLargePayload(String key, int sizeBytes) {
        byte[] payload = new byte[sizeBytes];
        // Simulate deserialization fill
        for (int i = 0; i < Math.min(sizeBytes, 1024); i++) {
            payload[i] = (byte) (i & 0xFF);
        }
        payloadCache.put(key, payload);
    }

    /**
     * BETTER: Chunk large payloads to stay below humongous threshold.
     * Each chunk is independently collectible as a regular object.
     */
    public void cacheChunkedPayload(String key, byte[] fullPayload) {
        int chunkSize = 256 * 1024; // 256KB chunks — well below humongous threshold
        int numChunks = (fullPayload.length + chunkSize - 1) / chunkSize;

        for (int i = 0; i < numChunks; i++) {
            int offset = i * chunkSize;
            int length = Math.min(chunkSize, fullPayload.length - offset);
            byte[] chunk = new byte[length];
            System.arraycopy(fullPayload, offset, chunk, 0, length);
            payloadCache.put(key + ":chunk:" + i, chunk);
        }
    }

    /**
     * Production G1 flags for a 16GB heap with mixed allocation profile:
     *
     * -XX:+UseG1GC
     * -Xms16g -Xmx16g
     * -XX:G1HeapRegionSize=16m
     * -XX:MaxGCPauseMillis=200
     * -XX:G1ReservePercent=15
     * -XX:InitiatingHeapOccupancyPercent=35
     * -XX:G1MixedGCCountTarget=8
     * -XX:G1MixedGCLiveThresholdPercent=85
     * -Xlog:gc*,gc+humongous=debug:file=/var/log/gc.log:time,uptime,level,tags
     */
}

package io.thecodeforge.gc;

import java.util.concurrent.atomic.AtomicLong;

/**
 * ZGC-specific considerations for production workloads.
 *
 * ZGC trades per-access overhead for near-zero pause times.
 * The load barrier adds ~4-8% overhead on pointer-heavy workloads.
 */
public class ZGCTuningExample {

    private final AtomicLong allocationCounter = new AtomicLong(0);

    /**
     * ZGC is sensitive to allocation rate, not allocation size.
     * A workload allocating many small objects stresses ZGC more than
     * fewer large objects because load barriers fire more frequently.
     *
     * Monitor: jstat -gcutil <pid> 1000
     * Watch: ZGC cycle count and allocation rate.
     */
    public void highFrequencyAllocation() {
        // 1000 allocations per call — each triggers load barrier overhead
        // on subsequent reads. ZGC handles this well with generational mode.
        for (int i = 0; i < 1000; i++) {
            Object temp = new Object();
            allocationCounter.incrementAndGet();
            // temp is immediately eligible for collection
        }
    }

    /**
     * Production ZGC flags for a 32GB heap, latency-sensitive service:
     *
     * -XX:+UseZGC
     * -XX:+ZGenerational              // JDK 21+ — critical for throughput
     * -Xms32g -Xmx32g                // Always set Xms=Xmx for ZGC
     * -XX:SoftMaxHeapSize=28g         // ZGC-specific: target heap occupancy
     * -XX:ZCollectionInterval=5       // Suggest GC cycle every 5 seconds
     * -XX:ConcGCThreads=4             // Concurrent GC threads (default: auto)
     * -XX:ParallelGCThreads=8         // Parallel GC threads
     * -Xlog:gc*:file=/var/log/zgc.log:time,uptime,level,tags
     *
     * CRITICAL: ZGC uses ~20% native memory overhead beyond -Xmx.
     * Container memory limit must be heap * 1.25 minimum.
     */

    /**
     * ZGC SoftMaxHeapSize is unique — it tells ZGC to try to stay below
     * this threshold but can exceed it under allocation pressure.
     *
     * Use case: Set heap to 32GB, SoftMaxHeapSize to 28GB.
     * ZGC will trigger cycles aggressively to stay under 28GB.
     * Only allocates into the remaining 4GB under extreme pressure.
     * This prevents container OOM kills while keeping a safety margin.
     */
    public void demonstrateSoftMaxHeapConcept() {
        // With SoftMaxHeapSize=28g and Xmx=32g:
        // - ZGC targets 28GB occupancy
        // - If allocation pressure pushes past 28GB, ZGC cycles more aggressively
        // - Only if allocation rate exceeds reclamation rate does it use 28-32GB
        // - If it hits 32GB, allocation stalls (not OOM, but backpressure)
        //
        // This is fundamentally different from G1's IHOP which just triggers
        // a marking cycle. SoftMaxHeapSize is a continuous pressure signal.
    }
}

package io.thecodeforge.gc;

import java.util.ArrayList;
import java.util.List;

/**
 * Shenandoah-specific production considerations.
 *
 * Shenandoah uses Brooks pointers — every object has an extra forwarding
 * pointer field. This adds 8 bytes per object on 64-bit systems.
 * For applications with millions of small objects, this overhead is measurable.
 */
public class ShenandoahTuningExample {

    /**
     * Brooks pointer overhead calculation:
     *
     * Object with 2 fields (16 bytes header + 16 bytes data = 32 bytes)
     * + 8 bytes Brooks pointer = 40 bytes per object
     * Overhead: 25% increase per object
     *
     * For 10 million small objects: ~80MB additional memory
     * For 100 million small objects: ~800MB additional memory
     *
     * Compare to ZGC: no per-object overhead, but ~15% heap overhead
     * from multi-mapping and compressed oops unavailability.
     */
    public long estimateBrooksOverhead(int objectCount) {
        return (long) objectCount * 8; // 8 bytes per Brooks pointer
    }

    /**
     * Production Shenandoah flags for a 16GB heap:
     *
     * -XX:+UseShenandoahGC
     * -Xms16g -Xmx16g
     * -XX:ShenandoahGCHeuristics=adaptive  // or 'compact', 'static'
     * -XX:ShenandoahAllocationThreshold=10  // trigger cycle after 10% allocation
     * -XX:+UseCompressedOops               // works with Shenandoah (unlike ZGC)
     * -XX:+UseCompressedClassPointers
     * -Xlog:gc*:file=/var/log/shenandoah.log:time,uptime,level,tags
     *
     * Heuristic modes:
     * - adaptive: (default) adjusts cycle frequency based on allocation rate
     * - compact: more aggressive collection, lower heap usage, slightly higher CPU
     * - static: fixed cycle interval, predictable behavior for benchmarking
     */

    /**
     * Shenandoah pacing is a unique feature that backpressures allocation
     * threads when the collector falls behind.
     *
     * Unlike ZGC which stalls allocation entirely, Shenandoah slows down
     * allocating threads proportionally. This creates smoother latency
     * degradation under load rather than sharp spikes.
     *
     * Monitor: -Xlog:gc+stats to see pacing delays.
     * If pacing delays exceed 1ms consistently, allocation rate is too high
     * for the current heap size and ConcGCThreads setting.
     */
    public void demonstratePacingBehavior() {
        List<byte[]> allocations = new ArrayList<>();

        // Under heavy allocation, Shenandoah will pace this loop
        // by adding small delays to each allocation.
        // The delay is proportional to how far behind the collector is.
        //
        // This is different from ZGC's allocation stall which is a hard stop.
        // Shenandoah's pacing creates gradual degradation.
        for (int i = 0; i < 100_000; i++) {
            allocations.add(new byte[1024]); // 1KB each
        }
    }
}

package io.thecodeforge.gc;

/**
 * Decision framework for collector selection based on production constraints.
 *
 * No collector is universally superior. This guide maps workload
 * characteristics to the appropriate collector.
 */
public class CollectorSelectionGuide {

    /**
     * SELECTION MATRIX:
     *
     * Workload Profile          | Recommended Collector | Reason
     * --------------------------|----------------------|------------------
     * General web service       | G1                   | Good balance, mature ecosystem
     * Sub-10ms latency SLA     | ZGC (generational)   | Hard pause guarantee
     * Sub-10ms + <32GB heap    | Shenandoah           | Compressed oops, pacing
     * Batch processing         | G1 or Parallel       | Throughput over latency
     * Large heap (>64GB)       | ZGC                  | Pause times scale with heap
     * Small heap (<4GB)        | G1                   | Overhead of ZGC/Shenandoah unjustified
     * Container-constrained    | G1 or Shenandoah     | Lower native memory overhead
     * High allocation rate     | ZGC (generational)   | Generational mode handles young gen
     * Mixed object lifetimes   | G1                   | Region-based collection handles this well
     * Many small objects       | ZGC                  | No per-object overhead
     * Many large objects       | G1 (large regions)   | Humongous object handling
     */

    /**
     * NATIVE MEMORY OVERHEAD COMPARISON (approximate, production values):
     *
     * G1:
     *   - Remembered sets: 5-10% of heap
     *   - Card table: ~0.2% of heap
     *   - Total native overhead: ~10-15% of heap
     *
     * ZGC:
     *   - Multi-mapping: ~15-20% of heap (virtual address space)
     *   - Page table overhead: variable
     *   - No compressed oops: +15% heap usage for <32GB heaps
     *   - Total native overhead: ~20-25% of heap
     *
     * Shenandoah:
     *   - Brooks pointers: 8 bytes per object
     *   - Remembered sets: ~5% of heap
     *   - Compressed oops: supported (saves ~15% vs ZGC)
     *   - Total native overhead: ~10-15% of heap + per-object cost
     */

    /**
     * CONTAINER MEMORY FORMULA:
     *
     * G1:        container_limit = Xmx * 1.15
     * ZGC:       container_limit = Xmx * 1.25
     * Shenandoah: container_limit = Xmx * 1.15 + (object_count * 8)
     *
     * If container limit is fixed, work backwards:
     * G1:        Xmx = container_limit / 1.15
     * ZGC:       Xmx = container_limit / 1.25
     * Shenandoah: Xmx = (container_limit - object_count * 8) / 1.15
     */
}

package io.thecodeforge.gc;

/**
 * Production tuning patterns organized by problem type.
 * Each pattern addresses a specific failure mode.
 */
public class ProductionTuningPatterns {

    /**
     * PATTERN 1: Allocation Rate Spike Handler
     *
     * Problem: Bursts of allocation cause GC to fall behind.
     * Symptom: Increasing pause times during traffic spikes.
     *
     * G1 Fix:
     *   -XX:InitiatingHeapOccupancyPercent=30  // start marking earlier
     *   -XX:G1ReservePercent=15                // more evacuation buffer
     *   -XX:G1RSetUpdatingPauseTimePercent=5   // less RSet work in pause
     *
     * ZGC Fix:
     *   -XX:SoftMaxHeapSize=<70% of Xmx>       // trigger cycles earlier
     *   -XX:ConcGCThreads=<cores/4>            // more concurrent threads
     *   -XX:+ZGenerational                     // focus on young objects
     *
     * Shenandoah Fix:
     *   -XX:ShenandoahAllocationThreshold=5    // cycle after 5% allocation
     *   -XX:ConcGCThreads=<cores/4>            // more concurrent threads
     *   -XX:ShenandoahGCHeuristics=compact     // aggressive reclamation
     */

    /**
     * PATTERN 2: Long-Lived Cache Optimization
     *
     * Problem: Large caches create a big live data set that GC must scan
     * but never reclaim. This wastes GC cycles and increases pause times.
     *
     * Solution: Use off-heap caching (Caffeine with weakValues, or
     * Chronicle Map) to move cached data outside GC's jurisdiction.
     *
     * If on-heap caching is required:
     * G1:   -XX:G1MixedGCLiveThresholdPercent=90  // skip regions with >90% live
     * ZGC:  Already handles this well with concurrent marking
     * Shen: -XX:ShenandoahGCHeuristics=adaptive   // skip mostly-live regions
     */

    /**
     * PATTERN 3: Container-Aware Sizing
     *
     * Problem: JVM heap + native memory exceeds container limit.
     * Symptom: OOM kill with no heap exhaustion in metrics.
     *
     * Rule of thumb for container memory limits:
     * - Set Xmx = container_limit * 0.80 for G1
     * - Set Xmx = container_limit * 0.70 for ZGC
     * - Set Xmx = container_limit * 0.80 for Shenandoah
     *
     * Remaining memory covers:
     * - Thread stacks (1MB per thread, ~500 threads = 500MB)
     * - Metaspace (class metadata, usually 100-300MB)
     * - Direct byte buffers (monitor with MBean)
     * - GC internal structures (remembered sets, card tables)
     * - JNI native memory
     */

    /**
     * PATTERN 4: Warm-Up Tuning for Low-Latency Services
     *
     * Problem: First requests after deployment have high latency due to
     * JIT compilation, class loading, and initial GC cycles.
     *
     * Solution:
     * 1. Use -XX:+AlwaysPreTouch to pre-zero heap pages at startup
     * 2. Implement warm-up traffic routing (load balancer weight ramp)
     * 3. Run synthetic allocation load for 60s before accepting traffic
     * 4. For ZGC: first 2-3 cycles are slower as JIT optimizes load barriers
     *
     * io.thecodeforge.gc.WarmUpManager can handle synthetic warm-up.
     */
}

package io.thecodeforge.gc;

import java.lang.management.GarbageCollectorMXBean;
import java.lang.management.ManagementFactory;
import java.lang.management.MemoryPoolMXBean;
import java.lang.management.MemoryUsage;
import java.util.List;

/**
 * Production GC metrics exporter for Prometheus/Micrometer integration.
 *
 * These metrics enable correlation of GC behavior with application
 * latency and throughput in your observability stack.
 */
public class GCMetricsExporter {

    /**
     * Essential GC metrics every production service must emit:
     *
     * 1. jvm_gc_pause_seconds{collector, action}
     *    - Histogram of GC pause durations
     *    - Alert on p99 > SLA threshold
     *
     * 2. jvm_gc_allocation_rate_mbps
     *    - Calculated from heap usage delta between GC cycles
     *    - Leading indicator of GC pressure
     *
     * 3. jvm_gc_live_data_size_bytes
     *    - Size of live objects after major collection
     *    - Growing trend = memory leak
     *
     * 4. jvm_gc_memory_promoted_bytes_total
     *    - Bytes promoted from young to old generation
     *    - High rate = short-lived objects escaping young gen
     *
     * 5. jvm_memory_used_bytes{area, pool}
     *    - Per-memory-pool usage
     *    - Alert on old gen > 80% sustained
     */

    public void exportGCMetrics() {
        List<GarbageCollectorMXBean> gcBeans = ManagementFactory.getGarbageCollectorMXBeans();

        for (GarbageCollectorMXBean gcBean : gcBeans) {
            String collectorName = gcBean.getName();
            long collectionCount = gcBean.getCollectionCount();
            long collectionTimeMs = gcBean.getCollectionTime();

            // Export as:
            // jvm_gc_collection_count_total{collector="<name>"} <count>
            // jvm_gc_collection_time_seconds_total{collector="<name>"} <time_sec>

            System.out.printf("Collector: %s, Count: %d, Time: %dms%n",
                    collectorName, collectionCount, collectionTimeMs);
        }

        // Memory pool monitoring for heap pressure detection
        List<MemoryPoolMXBean> memoryBeans = ManagementFactory.getMemoryPoolMXBeans();
        for (MemoryPoolMXBean pool : memoryBeans) {
            MemoryUsage usage = pool.getUsage();
            long usedMB = usage.getUsed() / (1024 * 1024);
            long maxMB = usage.getMax() / (1024 * 1024);
            double utilization = (double) usage.getUsed() / usage.getMax() * 100;

            // Alert if old gen utilization > 80% for extended period
            System.out.printf("Pool: %s, Used: %dMB, Max: %dMB, Util: %.1f%%%n",
                    pool.getName(), usedMB, maxMB, utilization);
        }
    }

    /**
     * GC log analysis commands for production triage:
     *
     * 1. Pause time distribution:
     *    grep 'Pause' gc.log | awk '{print $NF}' | sort -n | awk '
     *      {a[NR]=$1} END {print "p50:",a[int(NR*0.5)],"p99:",a[int(NR*0.99)],"max:",a[NR]}'
     *
     * 2. GC frequency over time:
     *    grep '\[gc.*\]' gc.log | awk '{print $1}' | cut -d'T' -f1 | uniq -c
     *
     * 3. Humongous allocation rate (G1 specific):
     *    grep 'humongous' gc.log | wc -l
     *    grep 'humongous' gc.log | awk '{sum+=$NF} END {print sum/NR, "bytes avg"}'
     *
     * 4. ZGC cycle time distribution:
     *    grep 'Garbage Collection.*GC\(' gc.log | grep -oP '\d+\.\d+ms' | sort -n
     *
     * 5. Shenandoah pacing delays:
     *    grep 'Pacing' gc.log | awk '{print $NF}' | sort -n | tail -20
     */
}