Merge pull request #2200 from pareenaverma/content_review

Tech review of Java Flamegraph LP

Author: pareenaverma

content/learning-paths/servers-and-cloud-computing/java-perf-flamegraph/1_setup.md

@@ -7,17 +7,17 @@ layout: learningpathall
 ---
 
 
-## Before You Begin 
-- There are numerous performance analysis methods and tools for Java applications, among which the call stack flame graph method is regarded as a conventional entry-level approach. Therefore, generating flame graphs is considered a basic operation.
-- Various methods and tools are available for generating Java flame graphs, including `async-profiler`, `Java Agent`, `jstack`, `JFR` (Java Flight Recorder), etc.
-- This Learning Path focuses on introducing two simple and easy-to-use methods: `async-profiler` and `Java Agent`.
+## Overview 
+There are numerous performance analysis methods and tools for Java applications, among which the call stack flame graph method is regarded as a conventional entry-level approach. Therefore, generating flame graphs is considered a basic operation.
+Various methods and tools are available for generating Java flame graphs, including `async-profiler`, `Java Agent`, `jstack`, `JFR` (Java Flight Recorder), etc.
+This Learning Path focuses on introducing two simple and easy-to-use methods: `async-profiler` and `Java Agent`.
 
 
 ## Setup Benchmark Server - Tomcat
 - [Apache Tomcat](https://tomcat.apache.org/) is an open-source Java Servlet container that enables running Java web applications, handling HTTP requests and serving dynamic content.
 - As a core component in Java web development, Apache Tomcat supports Servlet, JSP, and WebSocket technologies, providing a lightweight runtime environment for web apps.
 
-1. Start by installing Java Development Kit (JDK) on your Arm-based server:
+1. Start by installing Java Development Kit (JDK) on your Arm-based server running Ubuntu:
 ```bash
 sudo apt update
 sudo apt install -y openjdk-21-jdk
@@ -31,13 +31,13 @@ tar xzf apache-tomcat-11.0.9.tar.gz
 
 3. If you intend to access the built-in examples of Tomcat via an intranet IP or even an external IP, you need to modify a configuration file as shown:
 ```bash
-vim apache-tomcat-11.0.9/webapps/examples/META-INF/context.xml
+vi apache-tomcat-11.0.9/webapps/examples/META-INF/context.xml
 ```
-Then change the values:
-```console
+Then change the allow value as shown and save the changes:
+```output
 # change <Valve className="org.apache.catalina.valves.RemoteAddrValve" allow="127\.\d+\.\d+\.\d+|::1|0:0:0:0:0:0:0:1" />
 # to
-# <Valve className="org.apache.catalina.valves.RemoteAddrValve" allow=".*" />
+<Valve className="org.apache.catalina.valves.RemoteAddrValve" allow=".*" />
 ```
 Now you can start Tomcat Server:
 ```bash
@@ -62,9 +62,14 @@ Tomcat started.
 
 ![example image alt-text#center](./_images/lp-tomcat-examples.png "Tomcat-Examples")
 
+Make sure port 8080 is open in the security group of the IP address for your Arm-based Linux machine.
+
 ## Setup Benchmark Client - [wrk2](https://github.com/giltene/wrk2)
 `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.
 
+Currently `wrk2` is only supported on x86 machines. You will run the Benchmark Client steps shown below on an x86_64 server running Ubuntu.
+
+
 1. To use `wrk2`, you will need to install some essential tools before you can build it:
 ```bash
 sudo apt-get update

content/learning-paths/servers-and-cloud-computing/java-perf-flamegraph/2_async-profiler.md

@@ -6,11 +6,11 @@ weight: 3
 layout: learningpathall
 ---
 
-## Java Flame Graph Generation via async-profiler [async-profiler](https://github.com/async-profiler/async-profiler) (Recommended)
-- async-profiler is a low-overhead sampling profiler for JVM applications, capable of capturing CPU, allocation, and lock events to generate actionable performance insights.
-- A lightweight tool for Java performance analysis, async-profiler produces flame graphs and detailed stack traces with minimal runtime impact, suitable for production environments.
+## Java Flame Graph Generation using [async-profiler](https://github.com/async-profiler/async-profiler)
+`async-profiler` is a low-overhead sampling profiler for JVM applications, capable of capturing CPU, allocation, and lock events to generate actionable performance insights.
+A lightweight tool for Java performance analysis, `async-profiler` produces flame graphs and detailed stack traces with minimal runtime impact, suitable for production environments. In this section, you will learn how to install and use it to profile your Tomcat instance being benchmarked.
 
-You should deploy async-profiler on the same machine where Tomcat is running to ensure accurate performance profiling.
+You should deploy `async-profiler` on the same Arm Linux machine where Tomcat is running to ensure accurate performance profiling.
 1. Download async-profiler-4.0 and uncompress
 ```bash
 wget -c https://github.com/async-profiler/async-profiler/releases/download/v4.0/async-profiler-4.0-linux-arm64.tar.gz
@@ -21,10 +21,12 @@ tar xzf async-profiler-4.0-linux-arm64.tar.gz
 ```bash
 cd async-profiler-4.0-linux-arm64/bin
 ./asprof -d 10 -f profile.html $(jps | awk /Bootstrap/'{print $1}')
-# or 
+```
+You can also run:
+```
 ./asprof -d 10 -f profile.html ${tomcat_process_id}
 ```
 
-3. Launch profile.html in a browser to analyse the profiling result
+3. Now launch `profile.html` in a browser to analyse your profiling result
 
 ![example image alt-text#center](_images/lp-flamegraph-async.png "Java Flame Graph via async-profiler")

content/learning-paths/servers-and-cloud-computing/java-perf-flamegraph/3_agent.md

@@ -7,32 +7,42 @@ weight: 4
 layout: learningpathall
 ---
 
-## Java Flame Graph Generation via Java agent and perf
-To profile a Java application with perf and ensure proper symbol resolution, you must include libperf-jvmti.so when launching the Java application.
-- libperf-jvmti.so is a JVM TI agent library enabling perf to resolve Java symbols, facilitating accurate profiling of Java applications.
-- A specialized shared library, libperf-jvmti.so bridges perf and the JVM, enabling proper translation of memory addresses to Java method names during profiling.
+## Java Flame Graph Generation using Java agent and perf
+To profile a Java application with perf and ensure proper symbol resolution, you must include `libperf-jvmti.so` when launching the Java application.
+- `libperf-jvmti.so` is a JVM TI agent library enabling perf to resolve Java symbols, facilitating accurate profiling of Java applications.
+- A specialized shared library, `libperf-jvmti.so` bridges perf and the JVM, enabling proper translation of memory addresses to Java method names during profiling.
 
-1. Find and add libperf-jvmti.so to Java option
+1. Find where `libperf-jvmti.so` is installed on your Arm-based Linux server: 
+```bash
+pushd /usr/lib
+find . -name libperf-jvmti.so`
+```
+The output will show the path of the library that you will then include in your Tomcat setup file:
 ```bash
 vi apache-tomcat-11.0.9/bin/catalina.sh
-# add JAVA_OPTS="$JAVA_OPTS -agentpath:/usr/lib/linux-tools-6.8.0-63/libperf-jvmti.so -XX:+PreserveFramePointer"
+```
+Add JAVA_OPTS="$JAVA_OPTS -agentpath:/usr/lib/linux-tools-6.8.0-63/libperf-jvmti.so -XX:+PreserveFramePointer" to `catalina.sh`. Make sure the path matches the location on your machine from the previous step.
+
+Now shutdown and restart Tomcat:
+```bash
 cd apache-tomcat-11.0.9/bin
 ./shutdown.sh
 ./startup.sh
 ```
 
-2. Use perf to profile Tomcat, and restart wrk if necessary
+2. Use perf to profile Tomcat, and restart wrk that running on your x86 instance if necessary:
 ```bash
 sudo perf record -g -k1 -p $(jps | awk /Bootstrap/'{print $1}') -- sleep 10
 ```
+This command will record the collected data in a file named `perf.data`
 
-3. Convert the collected perf.data file into a Java flame graph using FlameGraph
+3. Convert the collected `perf.data` into a Java flame graph using FlameGraph
 ```bash
 git clone https://github.com/brendangregg/FlameGraph.git
-export PATH=$PATH:/root/FlameGraph
+export PATH=$PATH:`pwd`/FlameGraph
 sudo perf inject -j -i perf.data | perf script | stackcollapse-perf.pl | flamegraph.pl &> profile.svg
 ```
 
-4. Launch profile.svg in a browser to analyse the profiling result
+4. You can now successfully launch `profile.svg` in a browser to analyse the profiling result
 
 ![example image alt-text#center](_images/lp-flamegraph-agent.png "Java Flame Graph via Java agent and perf")

content/learning-paths/servers-and-cloud-computing/java-perf-flamegraph/_index.md

@@ -15,8 +15,8 @@ learning_objectives:
     - How to generate flame graphs for Java applications using Java agent
 
 prerequisites:
-    - Basic familiarity with Java applications
-    - Basic familiarity with flame graphs
+    - An Arm-based and x86 computer running Ubuntu. You can use a server instance from a cloud service provider of your choice.
+    - Basic familiarity with Java applications and flame graphs
 
 author: Ying Yu, Martin Ma
 
@@ -42,16 +42,13 @@ further_reading:
         link: https://wiki.openjdk.org/
         type: documentation
     - resource:
-        title: PLACEHOLDER BLOG 
-        link: PLACEHOLDER BLOG LINK
-        type: blog
-    - resource:
-        title: PLACEHOLDER GENERAL WEBSITE 
-        link: PLACEHOLDER GENERAL WEBSITE LINK
+        title: Java FlameGraphs
+        link: https://www.brendangregg.com/flamegraphs.html
         type: website
 
 
 
+
 ### FIXED, DO NOT MODIFY
 # ================================================================================
 weight: 1                       # _index.md always has weight of 1 to order correctly