review before PR

Author: Your Name

content/learning-paths/servers-and-cloud-computing/microbenchmark-network-iperf3/Setup.md

@@ -10,7 +10,7 @@ layout: learningpathall
 
 For this demonstration I will be using instances available from AWS within a virtual private cloud (VPC)
 
-Create 2 Arm-based linux instances, 1 to act as the server and the other to act as the client. In this tutorial I will be using an `t4g.xlarge` instance running Ubuntu 22.04 LTS. 
+Create 2 Arm-based linux instances, 1 to act as the server and the other to act as the client. In this tutorial I will be using two `t4g.xlarge` instance running Ubuntu 22.04 LTS. 
 
 
 ### Install dependencies
@@ -25,22 +25,27 @@ sudo apt install iperf3 -y
 
 ### Update Security Rules 
 
-Next, we need to update the default security rules to enable specific inbound and outbound protocols. From the AWS console, navigate to the security tab. Edit the inbound rules to enable `ICMP`, `UDP` and `TCP` traffic. Please note: for security we recommend updating the source to be the IP addresses of the client and server respectively. 
+Next, we need to update the default security rules to enable specific inbound and outbound protocols. From the AWS console, navigate to the security tab. Edit the inbound rules to enable `ICMP`, `UDP` and `TCP` traffic to enable communication between the client and server
+
 
 ![example_traffic](./example_traffic_rules.png)
 
+{{% notice Note %}}
+For security set the source and port ranges to those that are being used
+{{% /notice %}}
+
 
 ### Update local DNS
 
-For readability, we will add the server IP address and an alias name to the local DNS cache in `/etc/hosts`. 
+For readability, we will add the server IP address and an alias to the local DNS cache in `/etc/hosts`. The local IP address of the server and client can be found in the AWS dashboard. 
 
 On the client, add the IP address of the server to the `/etc/hosts` file. Likewise on the server add the IP address of the client to the `/etc/hosts` file. 
 
 ![server-ip](./server-ip.png). 
 
 ### Confirm server is reachable
 
-Finally, confirm the client can reach the server with the ping command below.
+Finally, confirm the client can reach the server with the ping command below. As a reference we also ping the localhost. 
 
 ```bash
 ping SERVER -c 3 && ping 127.0.0.1 -c 3

content/learning-paths/servers-and-cloud-computing/microbenchmark-network-iperf3/_index.md

@@ -3,7 +3,7 @@ title: Get started with network microbenchmarking and tuning with iperf3
 
 minutes_to_complete: 30
 
-who_is_this_for: Network engineers, sys admins or application developers
+who_is_this_for: Performance Engineers, Linux system administrators or application developers looking to microbenchmark, simulate or tune the networking performance of distributed systems.
 
 learning_objectives: 
     - Understand how to use the iperf3 tool to microbenchmark different network conditions
@@ -12,7 +12,7 @@ learning_objectives:
 
 prerequisites:
     - Foundational understanding on networking principles such as TCP/IP and UDP.
-    - Access to change inbound and outbound security rules or access to physical hardware
+    - Access to Arm-based cloud instances or access to physical hardware
 
 author: Kieran Hejmadi
 

content/learning-paths/servers-and-cloud-computing/microbenchmark-network-iperf3/basic-microbenchmarking.md

@@ -6,7 +6,7 @@ weight: 3
 layout: learningpathall
 ---
 
-## Microbenchmark Existing Network Connection
+## Microbenchmark TCP Connection
 
 
 First we will microbenchmark the bandwidth between the client and server. First start the `iperf` server on the server node with the following command. 
@@ -24,11 +24,15 @@ Server listening on 5201 (test #1)
 ```
 By default, the server listens on port 5201. Use the `-p` flag to specify another port if it is in use.
 
-Please note: If you're unable to start the `iperf` server, kill the process with the following command: `sudo kill $(pgrep iperf3)`
+{{% notice Tip %}}
+If you already have an `iperf3` server running, you can manually kill the process with the following command. 
+ ```bash
+ sudo kill $(pgrep iperf3)
+ ```
+{{% /notice %}}
 
-### Running Basic TCP Microbenchmark
 
-Likewise, on the client node, run the following command to run a simple 10-second microbenchmark using the TCP protocol. 
+Next, on the client node, run the following command to run a simple 10-second microbenchmark using the TCP protocol. 
 
 ```bash
 iperf3 -c SERVER -V
@@ -61,19 +65,19 @@ rcv_tcp_congestion cubic
 iperf Done.
 ```
 
-The important information to observe is `Cwnd`, this stands for the control window size and corresponds to the allowed number of TCP transactions inflight before receiving an acknowledgment `ACK` from the server. This adjusts dynamically to not overwhelm the receiver and adjust for variable link connection strengths. 
+- The`Cwnd` stands for the control window size and corresponds to the allowed number of TCP transactions inflight before receiving an acknowledgment `ACK` from the server. This adjusts dynamically to not overwhelm the receiver and adjust for variable link connection strengths. 
 
-The `CPU Utilization` row shows both the usage on the sender and receiver. If you are migrating your workload to a different platform, such as from `x86` to `AArch64`, there may be subtle variations. 
+- The `CPU Utilization` row shows both the usage on the sender and receiver. If you are migrating your workload to a different platform, such as from `x86` to `AArch64`, there may be subtle variations. 
 
-Finally the `snd_tcp_congestion cubic` abd `rcv_tcp_congestion cubic` variables show the congestion control algorithm used.
+- The `snd_tcp_congestion cubic` abd `rcv_tcp_congestion cubic` variables show the congestion control algorithm used.
 
-This test has saturated the 5 Gbps bandwidth available to our `t4g.xlarge` AWS instance. 
+- This `bitrate` shows the throughput achieved under this microbenchmark. As we can see from the above, we have saturated the 5 Gbps bandwidth available to our `t4g.xlarge` AWS instance. 
 
 ![instance-network-size](./instance-network-size.png)
 
-### Running Basic UDP Microbenchmark
+### Microbenchmark UDP connection
 
-We can also microbenchmark the `UDP` protocol with the `-u` flag. As a reminder, UDP does not guarantee packat delivery with some packets being lost. As such we need to observe the statistics on the server side to see the % of packet lost and the variation in packet arrival time (jitter). The UDP protocol is widely used in applications that need timely packet delivery, such as online gaming on video calls. 
+We can also microbenchmark the `UDP` protocol with the `-u` flag. As a reminder, UDP does not guarantee packet delivery with some packets being lost. As such we need to observe the statistics on the server side to see the % of packet lost and the variation in packet arrival time (jitter). The UDP protocol is widely used in applications that need timely packet delivery, such as online gaming on video calls. 
 
 Run the following command from the client to send 2 parallel UDP streams with the `-P 2` option.
 
@@ -90,7 +94,7 @@ Looking at the server output we can observe 0% of packets where lost for our sho
 [SUM]   0.00-10.00  sec  2.51 MBytes  2.10 Mbits/sec  0.015 ms  0/294 (0%)  receiver
 ```
 
-Additionally on the client side, our 2 streams maxed out 2 of our 4 core system. 
+Additionally on the client side, our 2 streams saturated 2 of our 4 cores in the local node. 
 
 ```output
 CPU Utilization: local/sender 200.3% (200.3%u/0.0%s), remote/receiver 0.2% (0.0%u/0.2%s)

content/learning-paths/servers-and-cloud-computing/microbenchmark-network-iperf3/simulating-network-conditions.md

@@ -1,5 +1,5 @@
 ---
-title: Simulating Different Scenarios
+title: Simulating Different Network Conditions
 weight: 4
 
 ### FIXED, DO NOT MODIFY
@@ -8,7 +8,7 @@ layout: learningpathall
 
 ## Adding a delay to a TCP connection
 
-The linux `tc` utility can be used to manipulate traffic control settings. First, find the name of connections with the following command. 
+The linux `tc` utility can be used to manipulate traffic control settings. First, find the name of interface with the following command. 
 
 ```bash
 ip addr show
@@ -38,7 +38,7 @@ Run the following command to add an emulated delay of 10ms on `ens5`.
 sudo tc qdisc add dev ens5 root netem delay 10ms
 ```
 
-Rerunning the basic TCP test with a delay we observe the `Cwnd` size has grew larger to compensate for the longer response time. Additionally, the bitrate has dropped from ~4.9 to ~2.3 `Gbit/sec`.
+Rerunning the basic TCP test (`iperf3 -c SERVER -V`) with a delay we observe the `Cwnd` size has grew larger to compensate for the longer response time. Additionally, the bitrate has dropped from ~4.9 to ~2.3 `Gbit/sec`.
 
 
 ```output
@@ -76,7 +76,7 @@ sudo tc qdisc del dev ens5 root
 sudo tc qdisc add dev ens5 root netem loss 1%
 ```
 
-Rerunning the basic TCP test we no observe a significant number of retries (`Retr`) and a corresponding drop in bitrate. 
+Rerunning the basic TCP test we observe an increased number of retries (`Retr`) and a corresponding drop in bitrate. 
 
 ```bash
 iperf3 -c SERVER -V
@@ -88,3 +88,4 @@ Test Complete. Summary Results:
 [  5]   0.00-10.00  sec  4.40 GBytes  3.78 Gbits/sec                  receiver
 ```
 
+Please see the `tc` [user documentation](https://man7.org/linux/man-pages/man8/tc.8.html) for the different ways to simulate different perturbation and your systems resiliency to such events.

content/learning-paths/servers-and-cloud-computing/microbenchmark-network-iperf3/tuning.md

@@ -6,10 +6,16 @@ weight: 5
 layout: learningpathall
 ---
 
-## Base example
+### Connecting from Local Machine
 
-In this example I will connect to the server from my remote client that has a higher round trip time. 
+Now we can observe ways to mitigate performance degradation due to events such as packet loss. In this example, I will connect to the AWS server node from my local machine to demonstrate a longer response time. Please check the `iperf3` installation guide on the [official documentation](https://iperf.fr/iperf-download.php) if you're not using Ubuntu. As the output below shows we have a larger round trip time in excess of 40ms. 
 
+```output
+5 packets transmitted, 5 packets received, 0.0% packet loss
+round-trip min/avg/max/stddev = 44.896/46.967/49.279/1.444 ms
+```
+
+Running a standard TCP client connection with the `iperf3 -c SERVER -V` command shows an average bitrate of 157 Mbps.
 
 ```output
 Starting Test: protocol: TCP, 1 streams, 131072 byte blocks, omitting 0 seconds, 10 second test, tos 0
@@ -22,7 +28,7 @@ Test Complete. Summary Results:
 
 
 
-## Modify kernel parameters
+### Modify kernel parameters
 
 On the server, we can configure linux kernel runtime parameters with the `sysctl` command. 
 
@@ -32,21 +38,29 @@ There are a plenthora of dials to tune that relate to performance and security.
 sysctl -a | grep tcp
 ```
 
-Please note: Depending on your operating system, some parameters may not be available. For example on AWS Ubuntu 22.04 LTS only the `cubic` and `reno` algorithms are available (`net.ipv4.tcp_available_congestion_control = reno cubic`).
+{{% notice Note %}}
+Depending on your operating system, some parameters may not be available. For example on AWS Ubuntu 22.04 LTS only the `cubic` and `reno` congestion control algorithms are available.
+```bash
+net.ipv4.tcp_available_congestion_control = reno cubic
+```
+{{% /notice %}}
+
 
 We can increase the read and write max buffer sizes of the kernel on the server to enable more data to be held. This is at the tradeoff of increased memory utilisation. run the following commands from the server.
 
 ```bash
-sudo sysctl net.core.rmem_max=134217728
-sudo sysctl net.core.wmem_max=134217728
+sudo sysctl net.core.rmem_max=134217728 # default = 212992
+sudo sysctl net.core.wmem_max=134217728 # default = 212992
 ```
 
-Restart the `iperf3` server and rerunning leads to higher achieved bitrate. 
+Restart the `iperf3` server.  Run the `iperf3 -c SERVER -V` command from the client leads to significantly improved bitrate with no modification on the client side. 
 
 ```output
 Test Complete. Summary Results:
 [ ID] Interval           Transfer     Bitrate
 [  8]   0.00-10.00  sec   308 MBytes   258 Mbits/sec                  sender
 [  8]   0.00-10.03  sec   307 MBytes   257 Mbits/sec                  receiver
 
-```
+```
+
+This learning path serves as an introduction to microbenchmarking and performance tuning. Which parameters to adjust depends on your own use case and non-functional performance requirements of your system.