From d2fd762bab62028cb6c30910bbba05807a26d118 Mon Sep 17 00:00:00 2001 From: Tyler Jones Date: Fri, 3 Mar 2023 11:35:26 -0700 Subject: [PATCH 1/4] first pass at example without screenshots --- EXAMPLE.md | 39 +++++++++++++++++++++++++++++++++++++++ README.md | 2 ++ 2 files changed, 41 insertions(+) create mode 100644 EXAMPLE.md diff --git a/EXAMPLE.md b/EXAMPLE.md new file mode 100644 index 00000000..ce51a9fc --- /dev/null +++ b/EXAMPLE.md @@ -0,0 +1,39 @@ +# Example +This guide will show how to run APerf to diagnose your application's performance. + +## Download APerf +1. Download the binaries from the [Releases](https://github.com/aws/APerf/releases) page. +2. Copy the binaries to the host that is running your application. +3. Untar the directory, and place the binary you want it to reside. +``` +tar -xvf ./aperf-v0.1.4-alpha-aarch64.tar.gz +``` + +## Running APerf +For the purpose of this example we will be collecting data on two systems. The first system will be an x86-based C6i system and the second one will be an AWS Graviton C7g instance. To collect performance data in 1 second time intervals for 10 seconds on the C6i instances, run the following command: + +``` +./aperf-v0.1.4-alpha-aarch64/aperf-collector -i 1 -p 10 -r c6i_performance_run_1 +``` + +To collect performance data in 1 second time intervals for 10 seconds on the C7gf instances, run the following command (not the `run_name` parameter has changed. This allows us to easily differentiate between two performance runs. + +``` +./aperf-v0.1.4-alpha-aarch64/aperf-collector -i 1 -p 10 -r c7g_performance_run_1 +``` + +## Visualizing The Results +To visualize the results you'll need access to a Linux desktop environment with a web browser installed. If you don't have access to a Linux desktop environment, [AWS Workspaces](https://aws.amazon.com/workspaces/) can be used to spin up a Linux desktop enviornment quickly and easily. + +To get started you'll need the `aperf-visualizer` binary and the performance data on the same machine. To visualize the results of a single performance run use the following command: + +``` +./aperf-v0.1.4-alpha-aarch64/aperf-visualizer --run-directory c7g_performance_run_1 +``` + +## Comparing Two Performance Run Results +To visualize and compare the results of two different performance runs, use the following command. APerf will automatically highlight variances between the two performance runs. This can be useful for comparing differences between systems. + +``` +./aperf-v0.1.4-alpha-aarch64/aperf-visualizer --run-directory c7g_performance_run_1 --run-directory c6i_performance_run_1 +``` diff --git a/README.md b/README.md index 6bd16078..2c4246a7 100644 --- a/README.md +++ b/README.md @@ -69,6 +69,8 @@ echo 100 | sudo tee /sys/devices/cpu/perf_event_mux_interval_ms ``` ./aperf-visualizer -r -p ``` +### Example +To see a step-by-step example, please see our example [here](./EXAMPLE.md) ### Configuration From 1cb40dca059ffb8170dd3da317a5cfa87cdc181e Mon Sep 17 00:00:00 2001 From: Tyler Jones Date: Fri, 3 Mar 2023 11:55:44 -0700 Subject: [PATCH 2/4] fixing arch typo --- EXAMPLE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EXAMPLE.md b/EXAMPLE.md index ce51a9fc..858eba45 100644 --- a/EXAMPLE.md +++ b/EXAMPLE.md @@ -13,7 +13,7 @@ tar -xvf ./aperf-v0.1.4-alpha-aarch64.tar.gz For the purpose of this example we will be collecting data on two systems. The first system will be an x86-based C6i system and the second one will be an AWS Graviton C7g instance. To collect performance data in 1 second time intervals for 10 seconds on the C6i instances, run the following command: ``` -./aperf-v0.1.4-alpha-aarch64/aperf-collector -i 1 -p 10 -r c6i_performance_run_1 +./aperf-v0.1.4-alpha-x86_64/aperf-collector -i 1 -p 10 -r c6i_performance_run_1 ``` To collect performance data in 1 second time intervals for 10 seconds on the C7gf instances, run the following command (not the `run_name` parameter has changed. This allows us to easily differentiate between two performance runs. From e7bb24ccb484f112f5d81ab0bae59bbbff4c7686 Mon Sep 17 00:00:00 2001 From: Tyler Jones Date: Fri, 3 Mar 2023 12:17:09 -0700 Subject: [PATCH 3/4] clarifying running aperf-visualizer, fixing typos --- EXAMPLE.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/EXAMPLE.md b/EXAMPLE.md index 858eba45..b4b3e346 100644 --- a/EXAMPLE.md +++ b/EXAMPLE.md @@ -16,24 +16,24 @@ For the purpose of this example we will be collecting data on two systems. The f ./aperf-v0.1.4-alpha-x86_64/aperf-collector -i 1 -p 10 -r c6i_performance_run_1 ``` -To collect performance data in 1 second time intervals for 10 seconds on the C7gf instances, run the following command (not the `run_name` parameter has changed. This allows us to easily differentiate between two performance runs. +To collect performance data in 1 second time intervals for 10 seconds on the C7gf instances, run the following command (note the `run_name` parameter has changed. This allows us to easily differentiate between two performance runs. ``` ./aperf-v0.1.4-alpha-aarch64/aperf-collector -i 1 -p 10 -r c7g_performance_run_1 ``` ## Visualizing The Results -To visualize the results you'll need access to a Linux desktop environment with a web browser installed. If you don't have access to a Linux desktop environment, [AWS Workspaces](https://aws.amazon.com/workspaces/) can be used to spin up a Linux desktop enviornment quickly and easily. - -To get started you'll need the `aperf-visualizer` binary and the performance data on the same machine. To visualize the results of a single performance run use the following command: +The APerf Visualizer runs a webserver to visualize the results. To get started you'll need the `aperf-visualizer` binary and the performance data on the same machine. `aperf-visualizer` currently only supports Linux environments. To visualize the results of a single performance run use the following command: ``` -./aperf-v0.1.4-alpha-aarch64/aperf-visualizer --run-directory c7g_performance_run_1 +./aperf-v0.1.4-alpha-aarch64/aperf-visualizer -p 8080 --run-directory c7g_performance_run_1 ``` +Once `aperf-visualizer` is up and running, simply point any web browser to the IP address of the machine running `aperf-visualizer`. + ## Comparing Two Performance Run Results -To visualize and compare the results of two different performance runs, use the following command. APerf will automatically highlight variances between the two performance runs. This can be useful for comparing differences between systems. +To visualize and compare the results of two different performance runs, use the following command. This can be useful for comparing differences between systems. ``` -./aperf-v0.1.4-alpha-aarch64/aperf-visualizer --run-directory c7g_performance_run_1 --run-directory c6i_performance_run_1 +./aperf-v0.1.4-alpha-aarch64/aperf-visualizer -p 8080 --run-directory c7g_performance_run_1 --run-directory c6i_performance_run_1 ``` From 5224188cf0ec5373bec92f6c4dc1ca6af631d266 Mon Sep 17 00:00:00 2001 From: Tyler Jones Date: Fri, 3 Mar 2023 15:55:39 -0700 Subject: [PATCH 4/4] updating localhost example --- EXAMPLE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EXAMPLE.md b/EXAMPLE.md index b4b3e346..c92a62ad 100644 --- a/EXAMPLE.md +++ b/EXAMPLE.md @@ -29,7 +29,7 @@ The APerf Visualizer runs a webserver to visualize the results. To get started y ./aperf-v0.1.4-alpha-aarch64/aperf-visualizer -p 8080 --run-directory c7g_performance_run_1 ``` -Once `aperf-visualizer` is up and running, simply point any web browser to the IP address of the machine running `aperf-visualizer`. +`aperf-visualizer` only listens for connections on localhost. If `aperf-visualizer` is running on a remote host you'll need to establish an SSH tunnel and then point a web browser to forwarded port established by the SSH tunnel. If you are running `aperf-visualizer` locally you can point your local web browser to `127.0.0.1:8080`. ## Comparing Two Performance Run Results To visualize and compare the results of two different performance runs, use the following command. This can be useful for comparing differences between systems.