Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

first pass at example without screenshots #57

Merged
merged 4 commits into from
Mar 6, 2023
Merged

first pass at example without screenshots #57

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
d2fd762
first pass at example without screenshots
Mar 3, 2023
1cb40dc
fixing arch typo
Mar 3, 2023
e7bb24c
clarifying running aperf-visualizer, fixing typos
Mar 3, 2023
5224188
updating localhost example
Mar 3, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 39 additions & 0 deletions EXAMPLE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Words say this is what to do on the x86 instance, but is running the aarch64 binary ;)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed.

```

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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

s/not the/note the/


```
./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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Probably want to lighten this up a bit so no-one thinks a linux machine with a GUI is required, but that the visualizer can be run on a different machine (but you'll have to do something like an ssh tunnel from a machine with any OS and a browser)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Isn't the only supported environment the visualizer runs on right now Linux? Or are you saying run the visualizer on the linux machine you ran the perf data on, and then ssh tunnel and point your browser at it?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You could run it on any linux machine, not just the one where you collected the data, and then use (just as one example) an SSH tunnel such that you can use a browser on your Mac/Windows laptop.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll note that.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed.


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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It will hopefully, soon, highlight differences. It doesn't do that currently.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed.


```
./aperf-v0.1.4-alpha-aarch64/aperf-visualizer --run-directory c7g_performance_run_1 --run-directory c6i_performance_run_1
```
2 changes: 2 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,8 @@ echo 100 | sudo tee /sys/devices/cpu/perf_event_mux_interval_ms
```
./aperf-visualizer -r <COLLECTOR_DIRECTORY> -p <PORT_NUMBER>
```
### Example
To see a step-by-step example, please see our example [here](./EXAMPLE.md)

### Configuration

Expand Down