Merge pull request #2060 from pareenaverma/content_review

Tech review of Go/Sweet LP

Author: pareenaverma

content/learning-paths/servers-and-cloud-computing/go-benchmarking-with-sweet/_index.md

@@ -1,17 +1,21 @@
 ---
 title: Go Benchmarks with Sweet and Benchstat
 
+draft: true
+cascade:
+    draft: true
+
 minutes_to_complete: 60
 
-who_is_this_for: This learning path is for developers who are interested in measuring the performance of Go-based applications on their servers.
+who_is_this_for: This is an introductory topic for developers who are interested in measuring the performance of Go-based applications on Arm-based servers.
 
 learning_objectives: 
-    - Bring up two instances of GCP VMs 
+    - Learn how to start up Arm64 and x64 instances of GCP VMs 
     - Install Go, benchmarks, benchstat, and sweet on the two VMs  
-    - Using sweet and benchstat, compare performance of Go applications on the two VMs
+    - Use sweet and benchstat to compare the performance of Go applications on the two VMs
 
 prerequisites:
-    - A [Google Cloud account](https://console.cloud.google.com/).  This learning path can be run on-prem or on any cloud provider, but specifically documents the process on GCP's Google Axion platform.
+    - A [Google Cloud account](https://console.cloud.google.com/).  This learning path can be run on on-prem or on any cloud provider instance, but specifically documents the process for running on Google Axion.
     - A local machine with [Google Cloud CLI](/install-guides/gcloud/) installed.
 
 author: Geremy Cohen
@@ -21,8 +25,9 @@ skilllevels: Introductory
 subjects: Performance and Architecture
 armips:
     - Neoverse
+cloud_service_providers: Google Cloud
 tools_software_languages:
-
+    - Go
 operatingsystems:
     - Linux
 

content/learning-paths/servers-and-cloud-computing/go-benchmarking-with-sweet/add_c4_vm.md

@@ -1,13 +1,13 @@
 ---
-title: Launching an Intel C4 Instance
+title: Launching a Intel Emerald Rapids Instance
 weight: 30
 
 ### FIXED, DO NOT MODIFY
 layout: learningpathall
 ---
 
 ## Section Overview
-In this section, you will set up the second benchmarking system, an Intel-based c4-standard-8 instance.
+In this section, you will set up the second benchmarking system, an Intel Emerald Rapids `c4-standard-8` instance.
 
 ## Creating the Instance
 
@@ -27,4 +27,4 @@ To create the second system, follow the previous lesson's c4a install instructio
 
 ![](images/launch_c4/5.png)
 
-After the c4 instance starts up, you are ready to continue to the next section, where you'll install the benchmarking software.
+After the c4 instance starts up, you are ready to continue to the next section, where you'll install the benchmarking software.

content/learning-paths/servers-and-cloud-computing/go-benchmarking-with-sweet/add_c4a_vm.md

@@ -1,13 +1,13 @@
 ---
-title: Launching an Arm Axion C4a Instance
+title: Launching a Google Axion Instance
 weight: 20
 
 ### FIXED, DO NOT MODIFY
 layout: learningpathall
 ---
 
-## Section Overview
-In this section, you'll learn how to spin up the first of two different systems used in our benchmarking tests, an Arm-based Google Axion c4a-standard-4 (c4a for short).
+## Overview
+In this section, you'll learn how to spin up the first of two different VMs used for benchmarking Go tests, an Arm-based Google Axion c4a-standard-4 (c4a for short).
 
 ## Creating the c4a-standard-4 Instance
 
@@ -63,5 +63,5 @@ The Machine configuration page appears.
 
 ![](images/launch_c4a/19.png)
 
-After a few seconds, your c4a instance starts up, and you are ready to continue to the next section. In the next step, you will launch the second system, an Intel-based Emerald Rapids c4-standard-8 (c4 for short), which will serve as the comparison system for our benchmarking tests.
+After a few seconds, your c4a instance starts up, and you are ready to continue to the next section. In the next step, you will launch the second VM, an Intel-based Emerald Rapids c4-standard-8 (c4 for short), which will serve as the comparison system for our benchmarking tests.
 

content/learning-paths/servers-and-cloud-computing/go-benchmarking-with-sweet/installing_go_and_sweet.md

@@ -6,21 +6,19 @@ weight: 40
 layout: learningpathall
 ---
 
-## Section Overview
-
 In this section, you'll install Go, Sweet, and the Benchstat comparison tool on both VMs.
 
 ## Installation Script
 
-Sweet is a Go benchmarking tool that provides a standardized way to run performance tests across different systems. Benchstat is a companion tool that analyzes and compares benchmark results, helping you understand performance differences between systems. Together, these tools will allow us to accurately measure and compare Go performance on Arm and x86 architectures.
+Sweet is a Go benchmarking tool that provides a standardized way to run performance tests across different systems. Benchstat is a companion tool that analyzes and compares benchmark results, helping you understand performance differences between systems. Together, these tools will allow you to accurately measure and compare Go performance on Arm and x86 architectures.
 
 
 {{% notice Note %}}
-Subsequent steps in the learning path assume you are running this script (installing) from your home directory (`~`), resulting in the creation of a `~/benchmarks/sweet` final install path. If you decide to install elsewhere, adjust the path accordingly when prompted to run the benchmark logic later in the learning path.
+Subsequent steps in the learning path assume you are running this script (installing) from your home directory (`$HOME`), resulting in the creation of a `$HOME/benchmarks/sweet` final install path. If you decide to install elsewhere, you will need to adjust the path accordingly when prompted to run the benchmark logic later in the learning path.
 {{% /notice %}}
 
 
-Copy and paste this script to **both** of your GCP VMs.  
+Start by copying and pasting the script below on **both** of your GCP VMs. This script checks the architecture of your running VM, installs the required Go packge on your VM. It then installs sweet, benchmarks, and the benchstat tools.
 
 **You don't need to run it after pasting**, just paste it into your home directory and press enter to install all needed dependencies: 
 
@@ -92,18 +90,39 @@ chmod 755 install_go_and_sweet.sh
 
 ```
 
+The end of the output should look like:
+
+```output
+Sweet v0.3.0: Go Benchmarking Suite
+
+Retrieves assets for benchmarks from GCS.
+
+Usage: sweet get [flags]
+  -cache string
+        cache location for assets (default "/home/pareena_verma_arm_com/.cache/go-sweet")
+  -clean
+        delete all cached assets before installing new ones
+  -copy string
+        location to extract assets into, useful for development
+  -version string
+        the version to download assets for (default "v0.3.0")
+```
 
 
 ## Verify Installation
 
-To test that everything is installed correctly, run the following command on each VM after the script completes:
+To test that everything is installed correctly, set the environment variables shown below on each VM:
 
 ```bash
-# Run the benchmarks
 export GOPATH=$HOME/go
 export GOBIN=$GOPATH/bin
 export PATH=$PATH:$GOBIN:/usr/local/go/bin
+```
+Now run the `markdown` benchmark with `sweet` on both VMs as shown:
+
+```bash
 cd benchmarks/sweet
+sweet get
 sweet run -count 10 -run="markdown" config.toml # run one, 1X
 ```
 
@@ -117,4 +136,4 @@ You should see output similar to the following:
 [sweet] Running benchmark markdown for arm-benchmarks: run 1
 ...
 [sweet] Running benchmark markdown for arm-benchmarks: run 10
-```
+```

content/learning-paths/servers-and-cloud-computing/go-benchmarking-with-sweet/manual_run_benchmark.md

@@ -6,59 +6,29 @@ weight: 51
 layout: learningpathall
 ---
 
-## Section Overview
+In this section, you'll download the results of the benchmark you ran manually in the previous sections from each VM. You will use these results to understand how `sweet` and `benchstat` work together.
 
-In this section, you'll run benchmarks manually to understand how `sweet` and `benchstat` work together.
+## Download Benchmark Results from each VM
+Lets walk through the steps to manually download the sweet benchmark results from your initial run on each VM.
 
-## Run Benchmarks on Each Machine
-The following explains how to run the benchmarks by hand on each machine.
 
-1. **Access VM instances:** Navigate to the GCP [VM Instances](https://console.cloud.google.com/compute/instances) console.
-
-2. **Connect to c4a instance:** Click on the `SSH` button next to your `c4a` instance.
-   An SSH terminal will open in a new tab.
-
-   ![](images/run_manually/2.png)
-
-3. **Set up environment:** Copy and paste the following into the SSH terminal to setup the environment and change to the sweet directory:
-
-   ```bash
-   cd benchmarks/sweet
-   export GOPATH=$HOME/go
-   export GOBIN=$GOPATH/bin
-   export PATH=$PATH:$GOBIN:/usr/local/go/bin
-   ```
-
-   ![](images/run_manually/3.png)
-
-{{% notice Note %}}
-The above instructions assume you installed the benchmarks in the `~/benchmarks/sweet` directory. If you installed them elsewhere, adjust the path accordingly.
-{{% /notice %}}   
-
-
-4. **Run the benchmark:** Copy and paste the following command to run the `markdown` benchmark with `sweet`:
-
-   ```bash
-   sweet run -count 10 -run="markdown" config.toml
-   ```
-
-5. **Locate results:** After the benchmark completes, cd to the `results/markdown` directory and list the files to see the `arm-benchmarks.result` file:
+1. **Locate results:** Change directory to the `results/markdown` directory and list the files to see the `arm-benchmarks.result` file:
 
    ```bash
    cd results/markdown
    ls -d $PWD/*
    ```
 
-6. **Copy result path:** Copy the absolute pathname of `arm-benchmarks.result`.
+2. **Copy result path:** Copy the absolute pathname of `arm-benchmarks.result`.
 
-7. **Download results:** Click `DOWNLOAD FILE`, and paste the **ABSOLUTE PATHNAME** you just copied for the filename, and then click `Download`. This will download the benchmark results to your local machine.
+3. **Download results:** Click `DOWNLOAD FILE`, and paste the **ABSOLUTE PATHNAME** you just copied for the filename, and then click `Download`. This will download the benchmark results to your local machine.
 
    ![](images/run_manually/6.png)
 
-8. **Rename the file:** Once downloaded, on your local machine, rename this file to `c4a.result` so you can distinguish it from the x86 results you'll download later. This naming convention will help you clearly identify which results came from which architecture. You'll know the file downloaded successfully if you see the file in your Downloads directory with the name `c4a.result`, as well as the confirmation dialog in your browser:
+4. **Rename the file:** Once downloaded, on your local machine, rename this file to `c4a.result` so you can distinguish it from the x86 results you'll download later. This naming convention will help you clearly identify which results came from which architecture. You'll know the file downloaded successfully if you see the file in your Downloads directory with the name `c4a.result`, as well as the confirmation dialog in your browser:
 
    ![](images/run_manually/7.png)
 
-9. **Repeat for c4 instance:** Repeat steps 2-8 with your `c4` (x86) instance. Do everything the same, except after downloading the c4's `arm-benchmarks.result` file, rename it to `c4.result`.
+5. **Repeat for c4 instance:** Repeat steps 2-8 with your `c4` (x86) instance. Do everything the same, except after downloading the c4's `arm-benchmarks.result` file, rename it to `c4.result`.
 
-Now that you have the results from both VMs, in the next section, you'll learn how to use benchstat to analyze these results and understand the performance differences between the two architectures.
+Now that you have the results from both VMs, in the next section, you'll learn how to use benchstat to analyze these results and understand the performance differences between the two architectures.

content/learning-paths/servers-and-cloud-computing/go-benchmarking-with-sweet/manual_run_benchstat.md

@@ -6,8 +6,6 @@ weight: 52
 layout: learningpathall
 ---
 
-## Section Overview
-
 You've successfully run and downloaded the benchmark results from both your Arm-based and x86-based VMs. In this section, you'll compare them to each other using the benchstat tool.
 
 
@@ -27,39 +25,36 @@ The file contains the results of the `markdown` benchmark run on the Arm-based c
 
 To compare the results, you'll use `benchstat` to analyze the two result files you downloaded. Since all the prerequisites are already installed on the `c4` and `c4a` instances, benchstat will be run from one of those instances.
 
-1. **Connect to VM:** As demonstrated in the previous chapter, SSH into the `c4a` instance.
 
-2. **Create working directory:** Make a temporary benchstat directory to hold the results files, and cd into it:
+1. **Create working directory:** Make a temporary benchstat directory to hold the results files on either the c4a or c4 isntance, and change directory into it:
 
    ```bash
    mkdir benchstat_results
    cd benchstat_results
    ```
 
-3. **Upload result files:** Click the `UPLOAD FILE` button in the GCP console, and upload the `c4a.results` AND `c4.results` files you downloaded earlier. (This uploads them to your home directory, not to the current directory.)
+2. **Upload result files:** Click the `UPLOAD FILE` button in the GCP console, and upload the `c4a.results` AND `c4.results` files you downloaded earlier. (This uploads them to your home directory, not to the current directory.)
 
    ![](images/run_manually/16.png)
 
-4. **Verify upload:** You'll know it worked correctly via the confirmation dialog in your terminal:
+3. **Verify upload:** You'll know it worked correctly via the confirmation dialog in your terminal:
 
    ![](images/run_manually/17.png)
 
-5. **Move files to working directory:** Move the results files to the `benchstat_results` directory, and confirm their presence:
+4. **Move files to working directory:** Move the results files to the `benchstat_results` directory, and confirm their presence:
 
    ```bash
    mv ~/c4a.results ~/c4.results .
    ls -al
    ```
 
-   You should see both files in the benchstat_results directory:
+   You should see both files in the `benchstat_results` directory:
 
    ```bash
-   # Example output:
-   c4a-48:~/benchstat_results$ ls
    c4.results  c4a.results
    ```
 
-6. **Run benchstat:** Now you can run `benchstat` to compare the two results files:
+5. **Run benchstat:** Now you can run `benchstat` to compare the two results files:
 
    ```bash
    export GOPATH=$HOME/go
@@ -68,7 +63,7 @@ To compare the results, you'll use `benchstat` to analyze the two result files y
    benchstat c4a.results c4.results > c4a_vs_c4.txt
    ```
 
-7. **View comparison results:** Run the `cat` command to view the results:
+6. **View comparison results:** Run the `cat` command to view the results:
 
    ```bash
    cat c4a_vs_c4.txt
@@ -77,8 +72,6 @@ To compare the results, you'll use `benchstat` to analyze the two result files y
    You should see output similar to the following:
 
    ```output
-   # Example output:
-   geremy_cohen_arm_com@c4a-48:~/benchstat_results$ cat c4a_vs_c4.txt 
                           │ c4a.results │     c4.results     │
                           │   sec/op    │   sec/op     vs base   │
    MarkdownRenderXHTML-48   143.9m ± 1%
@@ -125,4 +118,4 @@ To compare the results, you'll use `benchstat` to analyze the two result files y
 
 At this point, you can download the `c4a_vs_c4.txt` for further analysis or reporting. You can also run the same or different benchmarks with the same, or different combinations of VMs, and continue comparing results using `benchstat`.
 
-Continuing on to the next section, you will learn how to automate and gain enhanced visuals with sweet and benchstat.
+In the next section, you will learn how to automate and gain enhanced visuals with sweet and benchstat.

content/learning-paths/servers-and-cloud-computing/go-benchmarking-with-sweet/overview.md

@@ -6,9 +6,9 @@ weight: 10
 layout: learningpathall
 ---
 
-# Go Benchmarking Learning Path Overview
+# Go Benchmarking Overview
 
-In this module, you'll learn how to measure, collect, and compare Go performance data across different CPU architectures. This knowledge is essential for developers and system architects who need to make informed decisions about infrastructure choices for their Go applications.
+In this section, you will learn how to measure, collect, and compare Go performance data across different CPU architectures. This knowledge is essential for developers and system architects who need to make informed decisions about infrastructure choices for their Go applications.
 
 You'll gain hands-on experience with:
 
@@ -31,18 +31,4 @@ Arm-based c4a-standard-4 instances and Intel-based c4-standard-8 instances both
 {{% /notice %}}   
 
 
-## Prerequisites
 
-Before starting this learning path, you should have:
-- A Google Cloud Platform account with permissions to create VMs
-- Basic familiarity with Linux command line
-- Basic understanding of what benchmarking is and why it's useful
-
-## What You'll Accomplish
-
-When you are finished running through this learning path, you'll have:
-
-1. Brought up Arm and x86 instances of GCP-based VMs
-2. Installed Go, benchmarks, benchstat, and sweet on the two VMs
-3. Used sweet and benchstat to compare performance of Go applications on the two VMs
-4. Extrapolated the knowledge to create Go Benchmarks for your own workloads and systems