Merge pull request #1388 from kieranhejmadi01/java_tuning

Introduction to tuning Java Garbage Collection LP

Author: pareenaverma

content/learning-paths/servers-and-cloud-computing/java-gc-tuning/Example_application.md

@@ -0,0 +1,133 @@
+---
+title: Example Application
+weight: 4
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+## Example Application.
+
+Copy and paste the following Java snippet into a file called `HeapUsageExample.java`. This code example allocates 1 million string objects to fill up the heap. We can use this example to easily observe the effects of different GC tuning parameters.
+
+```java
+public class HeapUsageExample {
+    public static void main(String[] args) {
+        System.out.println("Starting the application...");
+
+        try {
+            // Create a large number of objects to quickly use up the heap
+            for (int i = 0; i < 1000000; i++) {
+                String[] array = new String[1000];
+                for (int j = 0; j < array.length; j++) {
+                    array[j] = "Object " + j;
+                }
+            }
+        } catch (OutOfMemoryError e) {
+            System.err.println("OutOfMemoryError caught: " + e.getMessage());
+        }
+
+        System.out.println("Application finished.");
+    }
+}
+```
+
+### Enable GC logging
+
+To observe the what the GC is doing, one option is to enabling logging whilst the JVM is running. To enable this, we need to pass in some command-line arguments. The `gc` option logs the GC information we are interested. The `filecount` option creates a rolling log to prevent uncontrolled growth of logs with the drawback that historical logs may be rewritten and lost. Run the following command from the terminal to enable logging on JDK 11 onwards.
+
+```bash
+java -Xms512m -Xmx1024m -XX:+UseSerialGC -Xlog:gc:file=gc.log:tags,uptime,time,level:filecount=10,filesize=16m HeapUsageExample.java
+```
+
+Use the following command if you are using JDK8.
+
+```bash
+java -Xms512m -Xmx1024m -XX:+UseSerialGC -Xloggc:gc.log -XX:+PrintGCTimeStamps -XX:+UseGCLogFileRotation HeapUsageExample.java
+```
+
+The `-Xms512m` and `-Xmx1024` options create a minimum and maximum heap size of 512 MiB and 1GiB respectively. This is simply so we do not have to wait for too long to see activity within the GC. Additionally, we force the JVM to use the serial garbage collector with the `-XX:+UseSerialGC` flag. 
+
+You will now see logs, named `gc.log.*` within the same directory. Viewing the contents you will see the following.
+
+```output
+[2024-11-08T15:04:54.304+0000][0.713s][info][gc          ] GC(2) Pause Young (Allocation Failure) 139M->3M(494M) 3.627ms
+...
+[2024-11-08T15:04:54.350+0000][0.759s][info][gc          ] GC(3) Pause Young (Allocation Failure) 139M->3M(494M) 3.699ms
+```
+
+These logs provide insights into the frequency, duration, and impact of Young garbage collection events. The results may vary depending on your system.
+
+    - Frequency: ~ every 46 ms
+    - Pause duration: ~ 3.6 ms
+    - Reduction size: ~ 139 MB (or 3M objects)
+
+This logging method has the benefit of being verbose but at the tradeoff of clarity. Furthermore, this method clearly isn't suitable for a running process which makes debugging a live environment slightly more challenging. 
+
+### Use jstat to observe real-time GC statistics
+
+The following java code snippet is a long-running example that prints out a random integer and double precision floating point number 4 times a second. Copy the example below and paste into a file called `WhileLoopExample.java`.
+
+```java
+import java.util.Random;
+
+public class GenerateRandom {
+
+    public static void main(String[] args) {
+        Random rand = new Random();
+
+        while (true) {
+            // Generate random integer in range 0 to 999
+            int rand_int1 = rand.nextInt(1000);
+
+            // Print random integer
+            System.out.println("Random Integers: " + rand_int1);
+
+            // Generate random double
+            double rand_dub1 = rand.nextDouble();
+
+            // Print random double
+            System.out.println("Random Doubles: " + rand_dub1);
+
+            // Sleep for 1 second (1000 milliseconds)
+            try {
+                Thread.sleep(250);
+            } catch (InterruptedException e) {
+                System.err.println("Thread interrupted: " + e.getMessage());
+            }
+        }
+    }
+}
+```
+
+Run the following command and open up a separate terminal session. Start the Java program with the command below. This will use the default parameters for the garbage collection. 
+
+```bash
+java WhileLoopExample.java
+```
+On the other terminal session, we use the `jstat` command to print out the JVM statistics specifically related to the GC using the `-gcutil` flag. 
+
+```bash
+jstat -gcutil $(pgrep java) 1000
+```
+
+
+You will obserse an output like the following until `ctl+c` is pressed. 
+
+```output
+  S0     S1     E      O      M     CCS    YGC     YGCT    FGC    FGCT    CGC    CGCT     GCT   
+  0.00 100.00   6.11   1.81  71.05  73.21      1    0.010     0    0.000     0    0.000    0.010
+  0.00 100.00   6.11   1.81  71.05  73.21      1    0.010     0    0.000     0    0.000    0.010
+  0.00 100.00   6.11   1.81  71.05  73.21      1    0.010     0    0.000     0    0.000    0.010
+...
+  0.00 100.00   6.11   1.81  71.05  73.21      1    0.010     0    0.000     0    0.000    0.010
+```
+
+The columns of interest are:
+- **E (Eden Space Utilization)**: The percentage of the Eden space that is currently used. High utilization indicates frequent allocations and can trigger minor GCs.
+- **O (Old Generation Utilization)**: The percentage of the Old (Tenured) generation that is currently used. High utilization can lead to Full GCs, which are more expensive.
+- **YGCT (Young Generation GC Time)**: The total time (in seconds) spent in Young Generation (minor) GC events. High values indicate frequent minor GCs, which can impact performance.
+- **FGCT (Full GC Time)**: The total time (in seconds) spent in Full GC events. High values indicate frequent Full GCs, which can significantly impact performance.
+- **GCT (Total GC Time)**: The total time (in seconds) spent in all GC events (Young, Full, and Concurrent). This provides an overall view of the time spent in GC, helping to assess the impact on application performance.
+
+

content/learning-paths/servers-and-cloud-computing/java-gc-tuning/Tuning Parameters.md

@@ -0,0 +1,71 @@
+---
+title: Basic GC Tuning
+weight: 5
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+### Update the JDK version used
+
+A sensible first step is to use one of the latest long-term-support (LTS) releases of JDK. This is because the GC versions included with recent JDKs offer improvements. For example, the G1GC included with JDK11 offers improvements in the pause time compared to JDK 8. As mentioned earlier, the `java --version` command will show you the version currently in use. 
+
+```output
+$ java --version
+openjdk 21.0.4 2024-07-16 LTS
+OpenJDK Runtime Environment Corretto-21.0.4.7.1 (build 21.0.4+7-LTS)
+OpenJDK 64-Bit Server VM Corretto-21.0.4.7.1 (build 21.0.4+7-LTS, mixed mode, sharing)
+```
+
+
+### Use an alternative GC
+
+In this section we will use the `HeapUsageExample.java` file we created earlier. 
+
+The G1 GC (Garbage-First Garbage Collector) is designed to handle large heaps and aims to provide low pause times by dividing the heap into regions and performing incremental garbage collection. This makes it suitable for applications with high allocation rates and large memory footprints.
+
+We can run the following command to generate the GC logs using a different GC and compare. We have simply changed the GC from `Serial` to `G1GC` using the `-XX:+UseG1GC` option. 
+
+```bash
+java -Xms512m -Xmx1024m -XX:+UseG1GC -Xlog:gc:file=gc.log:tags,uptime,time,level:filecount=10,filesize=16m HeapUsageExample.java
+```
+From the created log file `gc.log.*`, we can observe that at a very similar time after start up (~0.75s), the Pause Young time has reduced from ~3.6ms to ~1.9ms. Further, the time between GC pauses has imprved from ~46ms to every ~98ms.
+
+```output
+[2024-11-08T16:13:53.088+0000][0.790s][info][gc          ] GC(2) Pause Young (Normal) (G1 Evacuation Pause) 307M->3M(514M) 1.976ms
+...
+[2024-11-08T16:13:53.186+0000][0.888s][info][gc          ] GC(3) Pause Young (Normal) (G1 Evacuation Pause) 307M->3M(514M) 1.703ms
+```
+As discussed in the previous section, the performance improvement from moving to a G1GC will depend on the CPU overhead of your system. As such, the performance may vary depending on the cloud instance size and available CPU resources. 
+
+### Add GC Targets
+
+You can manually provide targets for specific metrics and the GC will attempt to meet those requirements. For example, if you have a time-sensitive application such as a rest server, you may want to ensure that all customers receive a response within a specific time. You may find that if a client request is sent during GC you need to ensure that the GC pause time is minimised. 
+
+Running the command with the `-XX:MaxGCPauseMillis=<N>` sets a target max GC pause time. 
+
+```bash
+java -Xms512m -Xmx1024m -XX:+UseG1GC -XX:MaxGCPauseMillis=1 -Xlog:gc:file=gc.log:tags,uptime,time,level:filecount=10,filesize=16m HeapUsageExample.java
+```
+
+Looking at the output below, we can see that at the same initial state after ~0.7s the pause time has been reduced. However, we can also see the initial size of the Young space has gone from 307MiB above to 124MiB. The GC decided to reduce the size of he Young space to reduce the pause time at the expense of more frequent pauses. 
+
+```output
+[2024-11-08T16:27:37.061+0000][0.765s][info][gc] GC(18) Pause Young (Normal) (G1 Evacuation Pause) 124M->3M(514M) 0.489ms
+[2024-11-08T16:27:37.149+0000][0.853s][info][gc] GC(19) Pause Young (Normal) (G1 Evacuation Pause) 193M->3M(514M) 0.482ms
+```
+
+Here are some additional target options you can consider to tune performance:
+
+-   -XX:InitiatingHeapOccupancyPercent: 
+
+Defines the old generation occupancy threshold to trigger a concurrent GC cycle. Adjusting this can be beneficial if your application experiences long GC pauses due to high old generation occupancy. For example, lowering this threshold can help start GC cycles earlier, reducing the likelihood of long pauses during peak memory usage.
+-   -XX:ParallelGCThreads
+
+Specifies the number of threads for parallel GC operations. Increasing this value can be beneficial for applications running on multi-core processors, as it allows GC tasks to be processed faster. For instance, a high-throughput server application might benefit from more parallel GC threads to minimize pause times and improve overall performance.
+-   -XX:G1HeapRegionSize
+
+Determines the size of G1 regions, which must be a power of 2 between 1 MB and 32 MB. Adjusting this can be useful for applications with specific memory usage patterns. For example, setting a larger region size can reduce the number of regions and associated overhead for applications with large heaps, while smaller regions might be better for applications with more granular memory allocation patterns.
+
+We recommend reading [this technical article](https://www.oracle.com/technical-resources/articles/java/g1gc.html) for more information of G1GC tuning. 
+

content/learning-paths/servers-and-cloud-computing/java-gc-tuning/_index.md

@@ -0,0 +1,36 @@
+---
+title: Tune the Performance of the Java Garbage Collector
+
+minutes_to_complete: 45
+
+who_is_this_for: This learning path is designed for Java developers aiming to optimize application performance on Arm-based servers. It is especially valuable for those migrating applications from x86-based to Arm-based instances. Here, you'll learn about essential garbage collection (GC) tuning parameters and how to adjust them to meet your specific performance needs. 
+
+learning_objectives: 
+    - Understand the key differences among Java garbage collectors (GCs).
+    - Monitor and interpret GC performance metrics.
+    - Adjust core parameters to optimize performance for your specific workload
+
+prerequisites:
+    - Access to an Arm-based server
+    - Basic understanding of Java
+    - Java installed on your system
+
+author_primary: Kieran Hejmadi
+
+### Tags
+skilllevels: Introductory
+subjects: Java
+armips:
+    - Neoverse
+tools_software_languages:
+    - Java
+operatingsystems:
+    - AWS Linux
+
+
+### FIXED, DO NOT MODIFY
+# ================================================================================
+weight: 1                       # _index.md always has weight of 1 to order correctly
+layout: "learningpathall"       # All files under learning paths have this same wrapper
+learning_path_main_page: "yes"  # This should be surfaced when looking for related content. Only set for _index.md of learning path content.
+---

content/learning-paths/servers-and-cloud-computing/java-gc-tuning/_next-steps.md

@@ -0,0 +1,23 @@
+---
+next_step_guidance: Run a Java Application on Google Axion instances. 
+
+recommended_path: /learning-paths/servers-and-cloud-computing/java-on-axion/
+
+further_reading:
+    - resource:
+        title: OpenJDK Wiki 
+        link: https://wiki.openjdk.org/
+        type: documentation
+    - resource:
+        title: G1GC Tuning 
+        link: https://www.oracle.com/technical-resources/articles/java/g1gc.html
+        type: documentation
+
+
+# ================================================================================
+#       FIXED, DO NOT MODIFY
+# ================================================================================
+weight: 21                  # set to always be larger than the content in this path, and one more than 'review'
+title: "Next Steps"         # Always the same
+layout: "learningpathall"   # All files under learning paths have this same wrapper
+---

content/learning-paths/servers-and-cloud-computing/java-gc-tuning/_review.md

@@ -0,0 +1,42 @@
+---
+review:
+    - questions:
+        question: >
+            What is the purpose of garbage collection?
+        answers:
+            - To manage memory by automatically reclaiming unused objects
+            - To manually manage memory allocation
+        correct_answer: 1                    
+        explanation: >
+            Garbage collection is used to manage memory by automatically reclaiming memory occupied by objects that are no longer in use, thus preventing memory leaks and optimizing memory usage.
+
+    - questions:
+        question: >
+            Which JVM flag can be used to enable detailed garbage collection logging?
+        answers:
+            - -XX:+UseG1GC
+            - -XX:+PrintGCDetails
+        correct_answer: 2                    
+        explanation: >
+            The flag -XX:+PrintGCDetails enables detailed logging of garbage collection events, which helps in monitoring and tuning the GC performance.
+
+    - questions:
+        question: >
+            Which garbage collector is best suited for applications requiring very low latency in a heavily multi-threaded application?
+        answers:
+            - Serial GC
+            - ZGC
+        correct_answer: 2                    
+        explanation: >
+            ZGC (Z Garbage Collector) is designed for applications requiring very low latency, as it aims to keep pause times below 10 milliseconds even for large heaps.
+
+
+
+
+# ================================================================================
+#       FIXED, DO NOT MODIFY
+# ================================================================================
+title: "Review"                 # Always the same title
+weight: 20                      # Set to always be larger than the content in this path
+layout: "learningpathall"       # All files under learning paths have this same wrapper
+---