Merge pull request #2262 from pareenaverma/content_review

Tech review of Tomcat tuning LP

Author: pareenaverma

content/learning-paths/servers-and-cloud-computing/tune-network-workloads-on-bare-metal/1_setup.md

@@ -1,5 +1,5 @@
 ---
-title: Tomcat benchmark set up
+title: Set up Tomcat
 weight: 2
 
 ### FIXED, DO NOT MODIFY
@@ -9,16 +9,16 @@ layout: learningpathall
 
 ## Overview 
 
-There are numerouse client-server and network-based workloads, and Tomcat is a typical example of such applications, which provide services via HTTP/HTTPS network requests.
+There are numerous client-server and network-based workloads, with Tomcat being a typical example of such applications. Tomcat provides services via HTTP/HTTPS network requests.
 
-In this section, you'll set up a benchmark environment using `Apache Tomcat` and `wrk2` to simulate HTTP load and evaluate performance on an Arm-based bare-metal, such as **__`AWS c8g.metal-48xl`__**.
+In this section, you will set up a benchmark environment using `Apache Tomcat` and `wrk2` to simulate an HTTP load and evaluate performance on an Arm-based bare metal instance. This Learning Path was tested on an AWS `c8g.metal-48xl` instance.
 
-## Set up the Tomcat benchmark server on **AWS c8g.metal-48xl**
+## Set up the Tomcat benchmark server
 [Apache Tomcat](https://tomcat.apache.org/) is an open-source Java Servlet container that runs Java web applications, handles HTTP requests, and serves dynamic content. It supports technologies such as Servlet, JSP, and WebSocket.
 
 ## Install the Java Development Kit (JDK)
 
-Install OpenJDK 21 on your Arm-based Ubuntu 24 bare-metal: 
+Install OpenJDK 21 on your Arm-based Ubuntu 24.04 bare-metal instance: 
 
 ```bash
 sudo apt update
@@ -44,13 +44,16 @@ The file is at:
 ~/apache-tomcat-11.0.10/webapps/examples/META-INF/context.xml
 ```
 
+Replace the existing allow value as shown:
 ```xml
-<!-- Before -->
 <Valve className="org.apache.catalina.valves.RemoteAddrValve" allow="127\.\d+\.\d+\.\d+|::1|0:0:0:0:0:0:0:1" />
+```
 
-<!-- After -->
+With:
+```xml
 <Valve className="org.apache.catalina.valves.RemoteAddrValve" allow=".*" />
 ```
+Save the changes to your file.
 
 ## Start the Tomcat server
 {{% notice Note %}}
@@ -91,7 +94,7 @@ You should see the Tomcat welcome page and examples, as shown below:
 [Wrk2](https://github.com/giltene/wrk2) is a high-performance HTTP benchmarking tool specialized in generating constant throughput loads and measuring latency percentiles for web services. `wrk2` is an enhanced version of `wrk` that provides accurate latency statistics under controlled request rates, ideal for performance testing of HTTP servers.
 
 {{% notice Note %}}
-Currently `wrk2` is only supported on x86 machines. Run the benchmark client steps below on an `x86_64` server running Ubuntu 24.
+Currently `wrk2` is only supported on x86 machines. Run the benchmark client steps below on a bare metal `x86_64` server running Ubuntu 24.04
 {{% /notice %}}
 
 ## Install dependencies 

content/learning-paths/servers-and-cloud-computing/tune-network-workloads-on-bare-metal/2_baseline.md

@@ -1,5 +1,5 @@
 ---
-title: Optimal baseline before tuning
+title: Establish baseline performance
 weight: 3
 
 ### FIXED, DO NOT MODIFY
@@ -11,59 +11,59 @@ To achieve maximum performance, ulimit -n 65535 must be executed on both server
 {{% /notice %}}
 
 ## Optimal baseline before tuning
-- Align the IOMMU settings with default Ubuntu
+- Align the IOMMU settings with default Ubuntu settings
 - Baseline on Arm Neoverse bare-metal (default configuration)
 - Baseline on Arm Neoverse bare-metal (access logging disabled)
 - Baseline on Arm Neoverse bare-metal (optimal thread count)
 
-### Align the IOMMU settings with default Ubuntu
+### Align the IOMMU settings with default Ubuntu settings
 
 {{% notice Note %}}
-Due to the customized Ubuntu distribution on AWS, you first need to align the IOMMU settings with default Ubuntu: iommu.strict=1 and iommu.passthrough=0.
+As you are using a custom Ubuntu distribution on AWS, you will first need to align the IOMMU settings with default Ubuntu settings for IOMMU: iommu.strict=1 and iommu.passthrough=0.
 {{% /notice %}}
 
-1. Setting IOMMU default status, use a text editor to modify the `grub` file by adding or updating the `GRUB_CMDLINE_LINUX` configuration.
+1. To change the IOMMU settings, use a text editor to modify the `grub` file by adding or updating the `GRUB_CMDLINE_LINUX` configuration:
 
 ```bash
 sudo vi /etc/default/grub
 ```
-then add or update
+Depending on what's in your `grub` file you will need to add or update `GRUB_CMDLINE_LINUX`:
 ```bash
 GRUB_CMDLINE_LINUX="iommu.strict=1 iommu.passthrough=0"
 ```
 
-2. Update GRUB and reboot to apply the default settings.
+2. Update GRUB and reboot your system to apply the default settings.
 ```bash
 sudo update-grub && sudo reboot
 ```
 
-3. Verify whether the default settings have been successfully applied.
+3. Verify that the default settings have been successfully applied:
 ```bash
 sudo dmesg | grep iommu
 ```
-It can be observed that under the default configuration, iommu.strict is enabled, and iommu.passthrough is disabled.
-```bash
+You should see that under the default configuration, `iommu.strict` is enabled, and `iommu.passthrough` is disabled:
+```output
 [    0.877401] iommu: Default domain type: Translated (set via kernel command line)
 [    0.877404] iommu: DMA domain TLB invalidation policy: strict mode (set via kernel command line)
 ...
 ```
 
-### Baseline on Arm Neoverse bare-metal (default configuration)
+### Establish a baseline configuration on Arm Neoverse bare-metal instances
 
 {{% notice Note %}}
-To align with the typical deployment scenario of Tomcat, reserve 8 cores online and set all other cores offline
+To align with typical deployment scenario of Tomcat, you will need to reserve 8 cores on your instance to be online and set all other cores to be offline
 {{% /notice %}}
 
-1. You can offline the CPU cores using the below command.
+1. To set the remaining CPU cores on your instance to be offline, run:
 ```bash
 for no in {8..191}; do sudo bash -c "echo 0 > /sys/devices/system/cpu/cpu${no}/online"; done
 ```
 2. Use the following commands to verify that cores 0-7 are online and the remaining cores are offline.
 ```bash
 lscpu
 ```
-You can check the following information:
-```bash
+The output should look like:
+```output
 Architecture:                aarch64
   CPU op-mode(s):            64-bit
   Byte Order:                Little Endian
@@ -75,22 +75,21 @@ Vendor ID:                   ARM
 ...
 ```
 
-3. Use the following command on the Arm Neoverse bare-metal where `Tomcat` is on
+3. Now shutdown and restart `Tomcat` on your Arm Neoverse bare-metal instance as shown:
 ```bash
 ~/apache-tomcat-11.0.10/bin/shutdown.sh 2>/dev/null
 ulimit -n 65535 && ~/apache-tomcat-11.0.10/bin/startup.sh
 ```
 
-4. And use the following command on the `x86_64` bare-metal where `wrk2` is on
-```bash
-tomcat_ip=172.31.46.193
-```
+4. On your `x86_64` bare-metal instance, run `wrk2` as shown:
+
 ```bash
 ulimit -n 65535 && wrk -c1280 -t128 -R500000 -d60 http://${tomcat_ip}:8080/examples/servlets/servlet/HelloWorldExample
 ```
+Replace `{tomcat_ip}` in the command above with the IP address of your Arm-based instance where the Tomcat server is running.
 
-The result of default configuration is:
-```bash
+The result with this baseline configuration should look like:
+```output
   Thread Stats   Avg      Stdev     Max   +/- Stdev
     Latency    16.76s     6.59s   27.56s    56.98%
     Req/Sec     1.97k   165.05     2.33k    89.90%
@@ -100,15 +99,15 @@ Requests/sec: 244449.62
 Transfer/sec:    129.90MB
 ```
 
-### Baseline on Arm Neoverse bare-metal (access logging disabled)
-To disable the access logging, use a text editor to modify the `server.xml` file by commenting out or removing the **`org.apache.catalina.valves.AccessLogValve`** configuration.
+### Disable Access logging
+To disable access logging, use a text editor to modify the `server.xml` file by commenting out or removing the **`org.apache.catalina.valves.AccessLogValve`** configuration.
 
 The file is at:
 ```bash
 vi ~/apache-tomcat-11.0.10/conf/server.xml
 ```
 
-The configuratin is at the end of the file, and common out or remove it.
+Either comment out or delete the configuration shown at the end of the file:
 ```xml
 <!-- 
     <Valve className="org.apache.catalina.valves.AccessLogValve" directory="logs"
@@ -117,18 +116,18 @@ The configuratin is at the end of the file, and common out or remove it.
 -->
 ```
 
-1. Use the following command on the Arm Neoverse bare-metal where `Tomcat` is on
+1. Shutdown and restart `Tomcat` on your Arm Neoverse bare-metal instance as shown:
 ```bash
 ~/apache-tomcat-11.0.10/bin/shutdown.sh 2>/dev/null
 ulimit -n 65535 && ~/apache-tomcat-11.0.10/bin/startup.sh
 ```
 
-2. And use the following command on the `x86_64` bare-metal where `wrk2` is on
+2. Run `wrk2` on the `x86_64` bare-metal instance:
 ```bash
 ulimit -n 65535 && wrk -c1280 -t128 -R500000 -d60 http://${tomcat_ip}:8080/examples/servlets/servlet/HelloWorldExample
 ```
 
-The result of access logging disabled is:
+The result with access logging disabled should look like:
 ```bash
   Thread Stats   Avg      Stdev     Max   +/- Stdev
     Latency    16.16s     6.45s   28.26s    57.85%
@@ -139,15 +138,15 @@ Requests/sec: 271675.12
 Transfer/sec:    144.36MB
 ```
 
-### Baseline on Arm Neoverse bare-metal (optimal thread count)
+### Set up optimal thread counts
 To minimize resource contention between threads and overhead from thread context switching, the number of CPU-intensive threads in Tomcat should be aligned with the number of CPU cores.
 
-1. When using `wrk` to perform pressure testing on `Tomcat`:
+1. When using `wrk` to perform pressure testing on `Tomcat`, use `top` to identify the CPU-intensive threads :
 ```bash
 top -H -p$(pgrep java)
 ```
 
-You can see the below information
+The output from `top` will look like:
 ```bash
 top - 08:57:29 up 20 min,  1 user,  load average: 4.17, 2.35, 1.22
 Threads: 231 total,   8 running, 223 sleeping,   0 stopped,   0 zombie
@@ -184,24 +183,26 @@ MiB Swap:      0.0 total,      0.0 free,      0.0 used. 382087.0 avail Mem
 ...
 ```
 
-It can be observed that **`http-nio-8080-e`** and **`http-nio-8080-P`** threads are CPU-intensive.
-Since the __`http-nio-8080-P`__ thread is fixed at 1 in current version of Tomcat, and the current number of CPU cores is 8, the http-nio-8080-e thread count should be configured to 7.
+You can observe from the output that **`http-nio-8080-e`** and **`http-nio-8080-P`** threads are CPU-intensive.
+As the __`http-nio-8080-P`__ thread is fixed at 1 in current version of Tomcat, and the current number of CPU cores is 8, the `http-nio-8080-e` thread count should be configured to 7.
 
-To configure the `http-nio-8080-e` thread count, use a text editor to modify the `context.xml` file by updating the `<Connector port="8080" protocol="HTTP/1.1"` configuration.
+To configure the `http-nio-8080-e` thread count, use a text editor to modify the `server.xml` file and update the `<Connector port="8080" protocol="HTTP/1.1"` configuration.
 
 The file is at:
 ```bash
 vi ~/apache-tomcat-11.0.10/conf/server.xml
 ```
 
-
+Replace the existing Connector setting as shown:
 ```xml
 <!-- Before -->
     <Connector port="8080" protocol="HTTP/1.1"
                connectionTimeout="20000"
                redirectPort="8443" />
 ```
 
+With the updated setting:
+
 ```xml
 <!-- After -->
     <Connector port="8080" protocol="HTTP/1.1"
@@ -214,23 +215,27 @@ vi ~/apache-tomcat-11.0.10/conf/server.xml
     />
 ```
 
-2. Use the following command on the Arm Neoverse bare-metal where `Tomcat` is on
+Save the changes to `server.xml`.
+
+2. Now shutdown and restart `Tomcat` on your Arm Neoverse bare-metal instance as shown:
 ```bash
 ~/apache-tomcat-11.0.10/bin/shutdown.sh 2>/dev/null
 ulimit -n 65535 && ~/apache-tomcat-11.0.10/bin/startup.sh
 ```
 
-3. And use the following command on the `x86_64` bare-metal where `wrk2` is on
+3. Run `wrk2` on the`x86_64` bare-metal instance:
 ```bash
 ulimit -n 65535 && wrk -c1280 -t128 -R500000 -d60 http://${tomcat_ip}:8080/examples/servlets/servlet/HelloWorldExample
 ```
 
-The result of optimal thread count is:
-```bash
+The result with the optimal thread count settings should look like:
+```output
   Thread Stats   Avg      Stdev     Max   +/- Stdev
     Latency    10.26s     4.55s   19.81s    62.51%
     Req/Sec     2.86k    89.49     3.51k    77.06%
   21458421 requests in 1.00m, 11.13GB read
 Requests/sec: 357835.75
 Transfer/sec:    190.08MB
 ```
+
+Now that you have established some baseline settings you can proceed to further tuning your setup.

content/learning-paths/servers-and-cloud-computing/tune-network-workloads-on-bare-metal/3_nic-queue.md

@@ -7,8 +7,7 @@ layout: learningpathall
 ---
 
 ## Tuning via NIC queue count
-- Setting NIC queue count
-- The result after tuning NIC queue count
+To further optmize your settings, you can set the NIC queue count and observe the performance uplift:
 
 Typically, the number of transmit/receive queues for network cards in bare-metal environments is relatively large, reaching 63 on Arm Neoverse. Each transmit/receive queue corresponds to one interrupt number. Before CPU cores are taken offline, there are sufficient cores to handle these interrupt numbers. However, when only 8 cores are retained, it results in a single core having to handle multiple interrupt numbers, thereby triggering more context switches.
 
@@ -18,8 +17,8 @@ Typically, the number of transmit/receive queues for network cards in bare-metal
 ```bash
 ip addr
 ```
-It can be observed that the NIC name `enp1s0f0np0` corresponsed to the IP address `10.169.226.181`.
-```bash
+From the output you can see that the NIC name `enp1s0f0np0` corresponds to the IP address `10.169.226.181`.
+```output
 1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000
     link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
     inet 127.0.0.1/8 scope host lo
@@ -66,8 +65,8 @@ sudo ethtool -L ${net} combined 8
 ```bash
 sudo ethtool -l ${net}
 ```
-It can be observed that the number of combined Rx/Tx queues has been updated to 8.
-```bash
+You should see that the number of combined Rx/Tx queues has been updated to 8.
+```output
 Channel parameters for enP11p4s0:
 Pre-set maximums:
 RX:		n/a
@@ -81,21 +80,21 @@ Other:		n/a
 Combined:	8
 ```
 
-### The result after tuning NIC queue count
+### The performance uplift after tuning NIC queue count
 
-1. Use the following command on the Arm Neoverse bare-metal where `Tomcat` is on
+1. Shutdown and restart `Tomcat` on your Arm Neoverse bare-metal instance as shown:
 ```bash
 ~/apache-tomcat-11.0.10/bin/shutdown.sh 2>/dev/null
 ulimit -n 65535 && ~/apache-tomcat-11.0.10/bin/startup.sh
 ```
 
-2. And use the following command on the `x86_64` bare-metal where `wrk2` is on
+2. Run `wrk2` on your `x86_64` bare-metal instance:
 ```bash
 ulimit -n 65535 && wrk -c1280 -t128 -R500000 -d60 http://${tomcat_ip}:8080/examples/servlets/servlet/HelloWorldExample
 ```
 
-The result after NIC queue count tuned:
-```bash
+Notice the performance uplift after tuning the NIC queue count:
+```output
   Thread Stats   Avg      Stdev     Max   +/- Stdev
     Latency     8.35s     4.14s   16.33s    61.16%
     Req/Sec     2.96k    73.02     3.24k    89.16%