final draft

Author: geremyCohen

content/learning-paths/servers-and-cloud-computing/go-gc-default-settings/_index.md

@@ -1,15 +1,14 @@
 ---
-title: Measure Go GC behavior on AWS Graviton with default runtime settings
-description: Learn how to run a Go allocation benchmark on AWS Graviton and measure garbage collection behavior without changing Go runtime settings.
+title: Measure Go GC behavior on AWS Graviton
+description: Learn how to measure and observe Go garbage collection metrics on AWS Graviton instances.
 
 minutes_to_complete: 75
 
-who_is_this_for: This Learning Path is for Go developers and performance engineers who want to measure garbage collection behavior on Arm servers without changing Go runtime GC settings.
+who_is_this_for: This Learning Path is for engineers interested in learning more about Go garbage collection (GC) behavior on Arm.
 
 learning_objectives:
     - Select an AWS Graviton instance for repeatable Go GC measurements
     - Install Go and Benchstat on an Arm Linux server
-    - Confirm that Go runtime tuning variables are unset
     - Run a Go benchmark that reports allocation, GC, and pause-time metrics
     - Capture CPU and heap profiles without changing GC behavior
 
@@ -66,11 +65,3 @@ weight: 1                       # _index.md always has weight of 1 to order corr
 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.
 ---
-
-## Measure default Go GC behavior on Arm servers
-
-Go applications can spend meaningful time allocating memory and running garbage collection (GC). You should measure that behavior before you change runtime settings.
-
-In this Learning Path, you run Go benchmarks on an AWS Graviton instance and keep the Go runtime in its default GC mode. You do not set `GOGC`, `GOMEMLIMIT`, `GODEBUG`, or `GOMAXPROCS`.
-
-The goal is to build a clean baseline. You will measure operation time, allocation rate, GC frequency, GC pause cost, and profiles before making tuning decisions.

content/learning-paths/servers-and-cloud-computing/go-gc-default-settings/choose_aws_instance.md

@@ -5,35 +5,31 @@ weight: 2
 ### FIXED, DO NOT MODIFY
 layout: learningpathall
 ---
+## What is Garbage Collection? (GC)
+Memory management is a critical aspects of application performance, and Garbage Collection (GC) plays a central role in automating that process. GC continuously identifies and removes objects that are no longer needed, freeing memory for re-use for other purposes..
 
-## Select an instance for Go GC measurements
+While this automation improves productivity and application safety, inefficient garbage collection can lead to increased CPU usage, longer response times, and unexpected application pauses. 
 
-Use an AWS Graviton instance that has enough CPU and memory to make Go runtime behavior visible, while keeping the Learning Path inexpensive to run.
+Tracking GC metrics provides a window into an application's memory health, helping engineers optimize performance, and ensuring the system can scale efficiently under load.
 
-For the first prototype, use `m8g.xlarge`.
+## Measuring default Go GC behavior on Arm servers
 
-`m8g.xlarge` is a good starting point because it provides four vCPUs and 16 GiB of memory on AWS Graviton4. Four vCPUs are enough to observe default Go CPU parallelism and GC worker behavior without requiring a large benchmark host. The 16 GiB memory size is enough for allocation-heavy benchmarks without immediately making the lab memory-bound.
+Go is one such language which implements GC.  As Go applications can spend meaningful time allocating memory and running garbage collection, it is important to understand how the Go runtime behaves under default settings. 
 
-Avoid burstable `t4g` instances for this Learning Path. CPU credits can affect benchmark repeatability and make GC measurements harder to explain.
+In this Learning Path, you'll run Go benchmarks on an AWS Graviton instance. The goal is to build a clean baseline, measuring operation time, allocation rate, GC frequency, and GC pause cost.
 
-If `m8g.xlarge` is not available in your AWS Region or Availability Zone, use `m7g.xlarge` as the fallback. It has the same vCPU and memory shape on an earlier Graviton generation, so the commands and benchmark workflow remain the same.
+## Selecting an instance for Go GC measurements
 
-## Recommended prototype machine
+An AWS Graviton `m8g.xlarge` instance has enough CPU and memory to make Go runtime behavior visible, while keeping costs minimal. It's a good starting point as it provides four vCPUs and 16 GiB of memory on AWS Graviton4. If you choose to run this Learning Path on a different instance, make sure it has at least 4 vCPUs and 16 GiB of memory to ensure the benchmark runs smoothly and provides meaningful GC metrics.
 
-Use this instance shape for the first version of the Learning Path:
-
-| Purpose | Instance type | Processor | vCPUs | Memory |
-| --- | --- | --- | ---: | ---: |
-| Default prototype | `m8g.xlarge` | AWS Graviton4 | 4 | 16 GiB |
-| Fallback | `m7g.xlarge` | AWS Graviton3 | 4 | 16 GiB |
+Avoid burstable `t4g` instances as CPU credits can affect benchmark repeatability and make GC measurements harder to explain.
 
 {{% notice Note %}}
 You can use larger instances, such as `m8g.2xlarge`, when you want more CPU width or more memory headroom. Start with `m8g.xlarge` so the first benchmark run is easy to reproduce and inexpensive.
 {{% /notice %}}
 
-The commands in this Learning Path were validated on an `m8g.xlarge` instance running Ubuntu 24.04 LTS Arm64 and Go 1.26.3.
 
-## Check instance availability
+## Checking instance availability
 
 Use the AWS CLI to check whether `m8g.xlarge` is available in your selected Region.
 
@@ -48,9 +44,7 @@ aws ec2 describe-instance-type-offerings \
     --output table
 ```
 
-If the command returns one or more Availability Zones, you can use `m8g.xlarge` in that Region.
-
-Run the same command for `m7g.xlarge` if `m8g.xlarge` is not available:
+If the command returns one or more Availability Zones, you can use `m8g.xlarge` in that Region.  If you are unable to find `m8g.xlarge` in your Region, you can try a different Region, or fallback to an 'm7g.xlarge' instance, which is based on the previous generation AWS Graviton3:
 
 ```console
 aws ec2 describe-instance-type-offerings \
@@ -61,4 +55,4 @@ aws ec2 describe-instance-type-offerings \
     --output table
 ```
 
-You have now selected a repeatable AWS Graviton test machine. You will confirm the default Go runtime environment before running the benchmark.
+Once you have chosen an instance type, provision it to run Ubuntu 24.04 LTS Arm64.  Once the instance is running, and you are ssh'd into it, you can proceed to the next step.

content/learning-paths/servers-and-cloud-computing/go-gc-default-settings/create_gc_benchmark.md

@@ -6,96 +6,167 @@ weight: 4
 layout: learningpathall
 ---
 
-## Create a benchmark module
+## Creating a benchmark module
 
-Create a small Go module for the benchmark:
+You'll first create a small Go benchmark module.  The high-level flow is:
+
+1. Generate a large input string.
+2. Repeatedly parse it and create new objects/strings.
+3. Force memory allocations so the garbage collector has work to do.
+4. Measure how long the workload takes.
+5. Measure how much GC activity occurred during the benchmark.
+6. Report both performance metrics and GC-related metrics.
+
+Pasting the code below will create the module and benchmark file:
+
+```bash
+
+# Create the module directory and initialize it.
 
-```console
 mkdir -p $HOME/go-gc-default/parsebench
 cd $HOME/go-gc-default
 go mod init example.com/go-gc-default
-```
 
-Create the benchmark file:
+# Create the benchmark file:
 
-```console
 cat > parsebench/parsebench_test.go <<'EOF'
 package parsebench
 
 import (
+
 	"runtime"
 	"strconv"
 	"strings"
 	"testing"
+
 )
 
+// Global variable used to store benchmark results.
+
 var sink []string
 
 func BenchmarkParseAndAllocate(b *testing.B) {
-	payload := strings.Repeat("name=arm&runtime=go&gc=default&value=12345;", 2048)
 
+	// This simulates a large payload by creating a large test string by
+	// repeating the same key=value data many times.
+	//
+	// Example:
+	// name=arm&runtime=go&gc=default&value=12345;
+	//
+	
+	payload := strings.Repeat("name=arm&runtime=go&gc=default&value=12345;",2048)
+	
+	// Next, we tell the benchmark framework to track memory allocations.
+	//
+	// This will show metrics such as allocations per operation, and bytes allocated per operation
+	
 	b.ReportAllocs()
-
+	
+	// Capture runtime memory statistics before the benchmark starts.  We will later compare these
+	// values to see:
+	// - how many garbage collections occurred
+	// - how much pause time was spent in GC
+	
 	var before runtime.MemStats
 	runtime.ReadMemStats(&before)
-
+	
+	// Reset benchmark timing so that any setup work performed above will not be included
+	// in the benchmark measurements.
+	
 	b.ResetTimer()
+	
+	// The benchmark loop is where the actual work is done.  The number of times this loop is
+	// executed is controlled by the b.N variable.  The value of b.N is automatically chosen by
+	// the Go benchmark framework to obtain stable and statistically useful measurements.
+	
+	// The reason for this design is that timing a single operation is often unreliable; running 
+	// it many times reduces noise from:
+	// * OS scheduling
+	// * CPU frequency changes
+	// * background processes
+
 	for i := 0; i < b.N; i++ {
+		// split the large payload into individual records.
+		// Example:
+		// "a=1;b=2;c=3;" becomes: ["a=1", "b=2", "c=3", ""]
 		parts := strings.Split(payload, ";")
+		// Create a new slice to store parsed output.  This allocation is intentional because we want
+		// the benchmark to generate memory pressure and trigger garbage collection activity.
+		
 		out := make([]string, 0, len(parts))
-
+		
+		// Process each record.
+		
 		for _, part := range parts {
+			// Ignore the empty string created by the trailing semicolon.
 			if part == "" {
 				continue
 			}
+			// Split the string into key and value.
+			
 			fields := strings.SplitN(part, "=", 2)
+			
+			// Make sure both key and value exist.
 			if len(fields) == 2 {
-				out = append(out, fields[0]+":"+strconv.Itoa(len(fields[1])))
+				// Build a new string containing: key:length_of_value
+				// This creates additional allocations and string objects, increasing GC activity.
+				out = append(out,fields[0]+":"+strconv.Itoa(len(fields[1])),)
 			}
 		}
-
+		// Save the result so the compiler cannot eliminate the work as unused.
 		sink = out
 	}
+	// Stop benchmark timing.
+	//
+	// Everything below is measurement/reporting logic and should not affect benchmark performance results.
 	b.StopTimer()
-
+	
+	// Capture memory statistics after the benchmark completes.
+	
 	var after runtime.MemStats
 	runtime.ReadMemStats(&after)
-
+	
+	// Number of benchmark operations executed.
 	ops := float64(b.N)
+	
+	// Total number of garbage collection cycles that occurred while the benchmark was running:
+	
 	gcCycles := after.NumGC - before.NumGC
+	
+	// Total "stop-the-world" pause time spent in GC. During these pauses, application execution
+	// is temporarily halted while the runtime performs parts of garbage collection.
+	
 	pauseNs := after.PauseTotalNs - before.PauseTotalNs
-
+	
+	// Report GC events per benchmark operation.  Example: 0.002 gc/op means one GC cycle
+	// every 500 operations.
+	
 	if ops > 0 {
 		b.ReportMetric(float64(gcCycles)/ops, "gc/op")
+	
+		// Report average GC pause time per operation.
 		b.ReportMetric(float64(pauseNs)/ops, "stw-ns/op")
 	}
+	// If at least one GC occurred, report the average stop-the-world pause duration for each GC cycle.
 	if gcCycles > 0 {
-		b.ReportMetric(float64(pauseNs)/float64(gcCycles), "stw-ns/GC")
+		b.ReportMetric(
+			float64(pauseNs)/float64(gcCycles),
+			"stw-ns/GC",
+		)
 	}
+
 }
 EOF
 ```
 
-This benchmark repeatedly parses and allocates strings. It reports the default Go benchmark metrics plus three GC-specific metrics:
-
-| Metric | Meaning |
-| --- | --- |
-| `gc/op` | GC cycles per completed benchmark operation |
-| `stw-ns/op` | GC stop-the-world pause nanoseconds per completed operation |
-| `stw-ns/GC` | GC stop-the-world pause nanoseconds per GC cycle |
+The benchmark code is now ready to run!  Give it a try by running the following command:
 
-The benchmark reads `runtime.MemStats` before and after the timed loop. It does not set Go runtime tuning variables.
-
-## Confirm the benchmark builds
-
-Run one short benchmark pass:
-
-```console
+```bash
 cd $HOME/go-gc-default
 go test ./parsebench -run '^$' -bench BenchmarkParseAndAllocate -benchmem -count 1 -benchtime=2s
 ```
 
-You should see output with `ns/op`, `B/op`, `allocs/op`, and the GC-specific metrics:
+You should see output similar to below:
 
 ```output
 goos: linux
@@ -106,4 +177,7 @@ PASS
 ok      example.com/go-gc-default/parsebench    4.127s
 ```
 
-Your exact numbers will differ by instance type, Go version, operating system, and system load.
+Your exact numbers will differ by instance type, Go version, operating system, and system load.  If this test run yields results with no errors, you're ready to move on to the next step.
+
+
+