Merge pull request #2320 from pareenaverma/content_review

pareenaverma · web-flow · commit 6e5f1ce577ce · 2025-09-16T10:28:19.000-04:00
Tech review of java azure LP
diff --git a/content/learning-paths/servers-and-cloud-computing/java-on-azure/_index.md b/content/learning-paths/servers-and-cloud-computing/java-on-azure/_index.md
@@ -7,23 +7,21 @@ cascade:
 
 minutes_to_complete: 30   
 
-who_is_this_for: This Learning Path introduces Java deployment on Microsoft Azure Cobalt 100 (Arm-based) virtual machines. It is designed for developers migrating Java applications from x86_64 to Arm with minimal or no changes.
+who_is_this_for: This is an introductory topic about Java deployment and benchmarking on Microsoft Azure Cobalt 100 (Arm-based) virtual machines. It is designed for developers migrating Java applications from x86_64 to Arm.
 
 learning_objectives: 
-    - Provision an Azure Arm64 virtual machine using Azure console, with Ubuntu Pro 24.04 LTS as the base image.
-    - Deploy Java on the Ubuntu Pro virtual machine.
-    - Perform Java baseline testing and benchmarking on both x86_64 and Arm64 virtual machines.
+    - Provision an Azure Arm-based Cobalt 100 virtual machine using Azure console, with Ubuntu Pro 24.04 LTS as the base image.
+    - Deploy Java on the Azure Arm64 virtual machine.
+    - Perform Java baseline testing and benchmarking on the Arm64 virtual machines.
 
 prerequisites:
     - A [Microsoft Azure](https://azure.microsoft.com/) account with access to Cobalt 100 based instances (Dpsv6). 
-    - Basic understanding of Linux command line.  
-    - Familiarity with the [Java platform](https://openjdk.org/) and deployment practices on Arm64 platforms.  
 
 
-author: Jason Andrews
+author: Pareena Verma
 
 ### Tags
-skilllevels: Advanced
+skilllevels: Introductory
 subjects: Performance and Architecture
 cloud_service_providers: Microsoft Azure
 
diff --git a/content/learning-paths/servers-and-cloud-computing/java-on-azure/baseline.md b/content/learning-paths/servers-and-cloud-computing/java-on-azure/baseline.md
@@ -7,14 +7,20 @@ layout: learningpathall
 ---
 
 
-### Deploy a Java application with Tomcat-like operation 
-Apache Tomcat is a Java-based web application server (technically, a Servlet container) that executes Java web applications. It's widely used to host Java servlets, JSP (JavaServer Pages), 
-and RESTful APIs written in Java. 
+### Deploy a Java application with a Tomcat-like operation 
+Apache Tomcat is a widely used Java web application server. Technically, it is a Servlet container, responsible for executing Java servlets and supporting technologies like:
 
-The below Java class simulates the generation of a basic HTTP response and measures the time taken to construct it, mimicking a lightweight Tomcat-like operation. It measures how long it 
-takes to build the response string, helping evaluate raw Java execution efficiency before deploying heavier frameworks like Tomcat.
+  * JSP (JavaServer Pages): Java-based templates for dynamic web content.
+  * RESTful APIs: Lightweight endpoints for modern microservices.
 
-Create a file named `HttpSingleRequestTest.java`, and add the below content to it:
+In production, frameworks like Tomcat introduce additional complexity (request parsing, thread management, I/O handling). Before layering those components, it's useful to measure how efficiently raw Java executes simple request/response logic on Azure Cobalt 100 Arm-based instances.
+
+In this section, you will run a minimal Tomcat-like simulation. It won't launch a real server, but instead it:
+  * Constructs a basic HTTP response string in memory.
+  * Measures the time taken to build that response, acting as a microbenchmark.
+  * Provides a baseline for raw string and I/O handling performance in Java.
+
+Using a file editor of your choice create a file named `HttpSingleRequestTest.java`, and add the content below to it:
 
 ```java
 public class HttpSingleRequestTest {
@@ -45,7 +51,7 @@ java -Xms128m -Xmx256m -XX:+UseG1GC HttpSingleRequestTest
 - -Xmx256m sets the maximum heap size for the JVM to 256 MB. 
 - -XX:+UseG1GC enables the G1 Garbage Collector (Garbage First GC), designed for low pause times and better performance in large heaps.
 
-You should see an output similar to:
+You should output similar to:
 ```output
 java -Xms128m -Xmx256m -XX:+UseG1GC HttpSingleRequestTest
 Response Generated:
@@ -56,8 +62,11 @@ Content-Length: 29
 Tomcat baseline test on Arm64
 Response generation took 12901.53 microseconds.
 ```
-Output summary:
+Output breakdown:
+
+Generated Response: The program generates a fake HTTP 200 OK response with headers and a custom body string.
+Timing Result: The program prints how long it took (in microseconds) to build that response.
+In this example, it took ~12,901 µs (~12.9 ms). Your result will vary depending on CPU load, JVM warm-up, and environment.
 
-- The program generated a fake HTTP 200 OK response with a custom message.
-- It then measured and printed the time taken to generate that response (22125.79 microseconds).
-- This serves as a basic baseline performance test of string formatting and memory handling on the JVM running on an Azure Arm64 instance.
+This provides you with a baseline measurement of how Java handles simple string operations and memory allocation on Cobalt 100 (Arm64) instances.
+It serves as a lightweight proxy for Tomcat-style request handling before adding the full complexity of a servlet container.
diff --git a/content/learning-paths/servers-and-cloud-computing/java-on-azure/benchmarking.md b/content/learning-paths/servers-and-cloud-computing/java-on-azure/benchmarking.md
@@ -6,18 +6,21 @@ weight: 6
 layout: learningpathall
 ---
 
-Now that you’ve built and run the Tomcat-like response, you can use it to test the JVM performance using JMH. You can also use it to test the performance difference between Cobalt 100 instances and other similar D series x86_64 based instances.
-## Run the performance tests using JMH
+Now that you have built and run a Tomcat-like response in Java, the next step is to benchmark it using a reliable, JVM-aware framework.
 
-JMH (Java Microbenchmark Harness) is a Java benchmarking framework developed by the JVM team at Oracle to measure the performance of small code snippets with high precision. It accounts for JVM optimizations like JIT and warm-up to ensure accurate and reproducible results. It measures the throughput, average latency, or execution time. Below steps help benchmark the Tomcat-like operation:
+## Run performance tests using JMH
+
+JMH (Java Microbenchmark Harness) is a Java benchmarking framework developed by the JVM team at Oracle to measure the performance of small code snippets with high precision. It accounts for JVM optimizations like JIT and warm-up to ensure accurate and reproducible results. You can measure throughput (ops/sec), average execution time, or percentiles for latency. 
+
+Follow the steps to help benchmark the Tomcat-like operation with JMH:
 
 
 Install Maven:
 
 ```console
 sudo apt install maven -y
 ```
-Create Benchmark Project:
+Once Maven is installed, create a JMH benchmark project using the official archetype provided by OpenJDK:
 
 ```console
 mvn archetype:generate \
@@ -30,8 +33,31 @@ mvn archetype:generate \
   -Dversion=1.0
 cd jmh-benchmark
 ```
+The output should look like:
+
+```output
+[INFO] ----------------------------------------------------------------------------
+[INFO] Using following parameters for creating project from Archetype: jmh-java-benchmark-archetype:1.37
+[INFO] ----------------------------------------------------------------------------
+[INFO] Parameter: groupId, Value: com.example
+[INFO] Parameter: artifactId, Value: jmh-benchmark
+[INFO] Parameter: version, Value: 1.0
+[INFO] Parameter: package, Value: com.example
+[INFO] Parameter: packageInPathFormat, Value: com/example
+[INFO] Parameter: package, Value: com.example
+[INFO] Parameter: groupId, Value: com.example
+[INFO] Parameter: artifactId, Value: jmh-benchmark
+[INFO] Parameter: version, Value: 1.0
+[INFO] Project created from Archetype in dir: /home/azureuser/jmh-benchmark
+[INFO] ------------------------------------------------------------------------
+[INFO] BUILD SUCCESS
+[INFO] ------------------------------------------------------------------------
+[INFO] Total time:  3.474 s
+[INFO] Finished at: 2025-09-15T18:28:15Z
+[INFO] ------------------------------------------------------------------------
+```
 
-Edit the `src/main/java/com/example/MyBenchmark.java` file and add the below code on it:
+Now edit the `src/main/java/com/example/MyBenchmark.java` file in the generated project. Replace the placeholder `TestMethod()` function with the following code:
 
 ```java
 package com.example;
@@ -56,23 +82,36 @@ public class MyBenchmark {
     }
 }
 ```
-This simulates HTTP response generation similar to Tomcat.
+This mirrors the Tomcat-like simulation you created earlier but now runs under JMH.
 
-Build the Benchmark:
+Build the Benchmark JAR:
 
 ```console
 mvn clean install
 ```
 
-After the build is complete, the JMH benchmark jar will be in the target/ directory.
+The output from this command should look like:
+
+```output
+[INFO] Installing /home/azureuser/jmh-benchmark/target/jmh-benchmark-1.0.jar to /home/azureuser/.m2/repository/com/example/jmh-benchmark/1.0/jmh-benchmark-1.0.jar
+[INFO] Installing /home/azureuser/jmh-benchmark/pom.xml to /home/azureuser/.m2/repository/com/example/jmh-benchmark/1.0/jmh-benchmark-1.0.pom
+[INFO] ------------------------------------------------------------------------
+[INFO] BUILD SUCCESS
+[INFO] ------------------------------------------------------------------------
+[INFO] Total time:  5.420 s
+[INFO] Finished at: 2025-09-15T18:31:32Z
+```
+
+After the build is complete, the JMH benchmark JAR will be located in the target directory.
 
 Run the Benchmark:
 
 ```console
 java -jar target/benchmarks.jar
 ```
+This will execute the benchmarkHttpResponse() method under JMH, showing average time per operation.
 
-You should see an output similar to:
+You should see output similar to:
 ```output
 # JMH version: 1.37
 # VM version: JDK 21.0.8, OpenJDK 64-Bit Server VM, 21.0.8+9-Ubuntu-0ubuntu124.04.1
@@ -160,6 +199,9 @@ Result "com.example.MyBenchmark.benchmarkHttpResponse":
 
 # Run complete. Total time: 00:08:21
 
+JMH runs warmup iterations so the JVM has a chance to JIT-compile and optimize the code before the real measurement begins.
+Each iteration shows how many times per second your `benchmarkHttpResponse()` method ran. You get an aggregate summary of the result at the end. In this example, on average the JVM executed ~35.6 million response constructions per second.
+
 REMEMBER: The numbers below are just data. To gain reusable insights, you need to follow up on
 why the numbers are the way they are. Use profilers (see -prof, -lprof), design factorial
 experiments, perform baseline and negative tests that provide experimental control, make sure
@@ -178,12 +220,12 @@ MyBenchmark.benchmarkHttpResponse  thrpt   25  35659618.044 ± 686946.011  ops/s
 
 ### Benchmark Metrics Explained  
 
-- **Run Count**: The total number of benchmark iterations executed. A higher run count increases statistical reliability and reduces the effect of outliers.  
-- **Average Throughput**: The mean number of operations executed per second across all iterations. This metric represents the overall sustained performance of the benchmarked workload.
+- **Run Count**: The total number of benchmark iterations that JMH executed. More runs improve statistical reliability and help smooth out anomalies caused by the JVM or OS. 
+- **Average Throughput**: The mean number of operations completed per second across all measured iterations. This is the primary indicator of sustained performance for the benchmarked code.
 - **Standard Deviation**: Indicates the amount of variation or dispersion from the average throughput. A smaller standard deviation means more consistent performance.  
-- **Confidence Interval (99.9%)**: The statistical range within which the true average throughput is expected to fall, with 99.9% certainty. Narrow intervals imply more reliable results.  
-- **Min Throughput**: The lowest throughput observed across all iterations, reflecting the worst-case performance scenario.  
-- **Max Throughput**: The highest throughput observed across all iterations, reflecting the best-case performance scenario.  
+- **Confidence Interval (99.9%)**: The statistical range in which the true average throughput is expected to fall with 99.9% certainty. Narrow confidence intervals suggest more reliable and repeatable measurements. 
+- **Min Throughput**: The lowest observed throughput across all iterations, representing a worst-case scenario under the current test conditions.
+- **Max Throughput**: The highest observed throughput across all iterations, representing the best-case performance under the current test conditions. 
 
 ### Benchmark summary on Arm64
 
@@ -198,26 +240,12 @@ Here is a summary of benchmark results collected on an Arm64 **D4ps_v6 Ubuntu Pr
 | **Min Throughput**             | 33.53M ops/sec            |
 | **Max Throughput**             | 36.99M ops/sec            |
 
-### Benchmark summary on x86
-
-Here is a summary of benchmark results collected on x86 **D4s_v6 Ubuntu Pro 24.04 LTS virtual machine**.
-
-| Metric                        | Value |
-|--------------------------------|---------------------------|
-| **Java Version**               | OpenJDK 21.0.8            |
-| **Run Count**                  | 25 iterations             |
-| **Average Throughput**         | 16.78M ops/sec            |
-| **Standard Deviation**         | ±0.06M ops/sec            |
-| **Confidence Interval (99.9%)**| [16.74M, 16.83M] ops/sec  |
-| **Min Throughput**             | 16.64M ops/sec            |
-| **Max Throughput**             | 16.88M ops/sec            |
-
 
-### Benchmark comparison insights
-When comparing the results on Arm64 vs x86_64 virtual machines:
+### Key insights from the results
 
-- **High Throughput:** Achieved an average of **35.66M ops/sec**, with peak performance reaching **36.99M ops/sec**.  
-- **Stable Performance:** Standard deviation of **±0.92M ops/sec**, with results tightly bounded within the 99.9% confidence interval **[34.97M, 36.34M]**.  
-- **Consistent Efficiency:** Demonstrates the reliability of Arm64 architecture for sustaining high-throughput Java workloads on Azure Ubuntu Pro environments.
+- **Strong throughput performance** The benchmark sustained around 35.6 million operations per second, demonstrating efficient string construction and memory handling on the Arm64 JVM.
+- **Consistency across runs** With a standard deviation under 1 million ops/sec, results were tightly clustered. This suggests stable system performance without significant noise from background processes.
+- **High statistical confidence** The narrow 99.9% confidence interval ([34.97M, 36.34M]) indicates reliable, repeatable results. 
+- **Predictable performance envelope** The difference between min (33.5M) and max (37.0M) throughput is modest (~10%), suggests the workload performed consistently without extreme slowdowns or spikes.
 
-You have now benchmarked Java on an Azure Cobalt 100 Arm64 virtual machine and compared results with x86_64.
+The Arm-based Azure `D4ps_v6` VM provides stable and efficient performance for Java workloads, even in microbenchmark scenarios. These results establish a baseline you can now compare directly against x86_64 instances to evaluate relative performance. 
diff --git a/content/learning-paths/servers-and-cloud-computing/java-on-azure/create-instance.md b/content/learning-paths/servers-and-cloud-computing/java-on-azure/create-instance.md
@@ -6,15 +6,13 @@ weight: 3
 layout: learningpathall
 ---
 
-## Introduction
+## Create an Azure Cobalt 100 Arm64 VM using the Azure portal
 
-There are several ways to create an Arm-based Cobalt 100 virtual machine : the Microsoft Azure console, the Azure CLI tool, or using your choice of IaC (Infrastructure as Code). This guide will use the Azure console to create a virtual machine with Arm-based Cobalt 100 Processor. 
+You can create an Azure Cobalt 100 Arm64 virtual machine in several ways, including the Azure portal, the Azure CLI, or an Infrastructure as Code (IaC) tool. 
 
-This learning path focuses on the general-purpose virtual machine of the D series. Please read the guide on [Dpsv6 size series](https://learn.microsoft.com/en-us/azure/virtual-machines/sizes/general-purpose/dpsv6-series) offered by Microsoft Azure.  
+In this Learning Path, you’ll use the Azure portal to create a VM with the Cobalt 100 processor, following a process similar to creating any other virtual machine in Azure.
 
-If you have never used the Microsoft Cloud Platform before, please review the microsoft [guide to Create a Linux virtual machine in the Azure portal](https://learn.microsoft.com/en-us/azure/virtual-machines/linux/quick-create-portal?tabs=ubuntu). 
-
-#### Create an Arm-based Azure Virtual Machine 
+## Step-by-step: create the virtual machine 
 
 Creating a virtual machine based on Azure Cobalt 100 is no different from creating any other virtual machine in Azure. To create an Azure virtual machine, launch the Azure portal and navigate to "Virtual Machines".
 1. Select "Create", and click on "Virtual Machine" from the drop-down list.
@@ -35,7 +33,7 @@ Creating a virtual machine based on Azure Cobalt 100 is no different from creati
 
 ![Azure portal VM creation — Azure Cobalt 100 Arm64 virtual machine (D4ps_v6) alt-text#center](images/ubuntu-pro.png "Figure 3: Review and Create an Azure Cobalt 100 Arm64 VM")
 
-10. Finally, when you are confident about your selection, click on the "Create" button, and click on the "Download Private key and Create Resources" button.
+10. Finally, click on the "Create" button, and click on the "Download Private key and Create Resources" button.
 
 ![Azure portal VM creation — Azure Cobalt 100 Arm64 virtual machine (D4ps_v6) alt-text#center](images/instance4.png "Figure 4: Download Private key and Create Resources")
 
diff --git a/content/learning-paths/servers-and-cloud-computing/java-on-azure/deploy.md b/content/learning-paths/servers-and-cloud-computing/java-on-azure/deploy.md
@@ -9,25 +9,24 @@ layout: learningpathall
 
 
 ## Java Installation on Azure Ubuntu Pro virtual machine
-Install Java on Ubuntu Pro virtual machine by updating the system and installing `default-jdk`, which includes both JRE and JDK. Verify the installation using `java -version` and `javac -version`, then set the `JAVA_HOME` environment variable for Arm-based systems.
+In this section, you will install Java on your Arm-based Ubuntu Pro virtual machine. The goal is to ensure you have both the Java Runtime Environment (JRE) for running Java applications and the Java Development Kit (JDK) for compiling code and running benchmarks.
 
 
 ### Install Java
 
+You will install Java using the Ubuntu package manager. `default-jdk` installs both the default JRE and JDK provided by Azure Ubuntu Pro machine.
 ```console
 sudo apt update
 sudo apt install -y default-jdk
 ```
  
-`default-jdk` installs both the default JRE and JDK provided by Azure Ubuntu Pro machine.
-
-Check to ensure that the JRE is properly installed: 
+Verify your JRE installation: 
 
 ```console
 java -version 
 ``` 
 
-You should see an output similar to: 
+You should the JRE version printed: 
 
 ```output
 openjdk version "21.0.8" 2025-07-15
@@ -40,13 +39,13 @@ Check to ensure that the JDK is properly installed:
 ```console
 javac -version 
 ```
-You should see an output similar to:
+The output should look similar to:
 
 ```output
 javac 21.0.8
 ```
 
-Set Java Environment Variable for Arm: 
+Set the Java Environment Variables to point to the root directory of your JDK installation: 
 
 ```console 
 export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-arm64
@@ -58,7 +57,7 @@ source ~/.bashrc
 Ubuntu Pro 24.04 LTS offers the default JDK version 21.0.8. It’s important to ensure that your version of OpenJDK for Arm is at least 11.0.9, or above. There is a large performance gap between OpenJDK-11.0.8 and OpenJDK 11.0.9. A patch added in 11.0.9 reduces false-sharing cache contention. 
 For more information, you can view this [Arm community blog](https://community.arm.com/arm-community-blogs/b/architectures-and-processors-blog/posts/java-performance-on-neoverse-n1). 
 
-The [Arm Ecosystem Dashboard](https://developer.arm.com/ecosystem-dashboard/) also recommends Java/OpenJDK version 11.0.9 as minimum recommended on the Arm platforms.
+You can also refer to the [Arm Ecosystem Dashboard](https://developer.arm.com/ecosystem-dashboard/) for software package version recommendations on Arm Neoverse Linux machines.
 {{% /notice %}}
 
-Java installation is complete. You can now proceed with the baseline testing.
+Your Java environment has been successfully configured. You may now proceed with baseline testing.
