diff --git a/EXAMPLE.md b/EXAMPLE.md new file mode 100644 index 00000000..c92a62ad --- /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-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 (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 +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 -p 8080 --run-directory c7g_performance_run_1 +``` + +`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. + +``` +./aperf-v0.1.4-alpha-aarch64/aperf-visualizer -p 8080 --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