Skip to content

Commit da2483b

Browse files
TitoReinhart-AmpereTitoReinhart-Ampere
committed
feat: initial commit to opensource Ampere System Profiler
0 parents  commit da2483b

19 files changed

Lines changed: 2677 additions & 0 deletions

File tree

‎.github/workflows/ci.yml‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
name: Build & Testing
2+
on:
3+
push:
4+
branches:
5+
- main
6+
pull_request:
7+
8+
jobs:
9+
test-on-ampere:
10+
runs-on: [self-hosted, linux, arm64]
11+
steps:
12+
- name: Cleanup previous workspace
13+
run: sudo rm -rf /home/asp/actions-runner/_work/ampere-system-profiler/ampere-system-profiler/*
14+
continue-on-error: true
15+
16+
- name: Checkout code
17+
uses: actions/checkout@v4
18+
19+
- name: Set up Poetry
20+
uses: abatilo/actions-poetry@v2
21+
with:
22+
poetry-version: "1.8.2"
23+
24+
- name: Install dependencies
25+
run: poetry install
26+
27+
- name: Link poetry scripts
28+
run: sudo ln -sf $(poetry env info --path)/bin/asp /usr/local/bin/asp && sudo ln -sf $(poetry env info --path)/bin/postprocess /usr/local/bin/postprocess
29+
30+
- name: check format
31+
run: poetry run black --check src
32+
33+
- name: check type error
34+
run: poetry run mypy src --ignore-missing-imports
35+
36+
- name: check linting
37+
run: poetry run ruff check src
38+
39+
- name: Run pytest
40+
run: poetry run pytest --cov=tests --cov=src/cli/collectors --cov-report=html

‎.gitignore‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
dist/
2+
venv/
3+
**/__pycache__/
4+
data/
5+
.coverage/

‎LICENSE.txt‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
BSD 3-Clause License
2+
3+
Copyright (c) 2025 Ampere Computing LLC
4+
5+
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
6+
7+
1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
8+
9+
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
10+
11+
3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
12+
13+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
14+
PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
15+
OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
16+
IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
17+

‎README.md‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
# Ampere System Profiler
2+
3+
The Ampere System Profiler (ASP) is a system-level analysis profiler that can be used to look for common platform-level problems while running workloads. It also includes a visualizer in the form of Plotly graphs and tables in an HTML report.
4+
ASP can be used for workload characterization at a system level, a first step towards a balanced platform.
5+
6+
## System pre-Requisites
7+
Required Commands
8+
- sar
9+
- sensors
10+
- route
11+
- numastat
12+
- perf
13+
- python3
14+
15+
YUM Packages for RHEL based systems:
16+
```shell
17+
sudo yum install lm_sensors perf sysstat numactl net-tools python3
18+
```
19+
20+
APT Packages for Ubuntu or Debian:
21+
```shell
22+
sudo apt install lm-sensors sysstat numactl net-tools linux-tools-common linux-tools-$(uname -r) python3
23+
```
24+
25+
Python Modules:
26+
```shell
27+
sudo python3 -m pip install plotly pandas argparse
28+
```
29+
30+
## Output
31+
ASP will generate a html format report under the root directory of ASP.
32+
The report includes:
33+
- CPU Utilization
34+
- Per-Core Utilization
35+
- CPU Power
36+
- CPU Frequencies
37+
- Disk I/O
38+
- Network Utilization
39+
- NUMA Stats
40+
- Top CPU Hotspots
41+
42+
## Getting Started
43+
44+
### 1. Clone the Repository
45+
46+
## 2. Run Setup
47+
```bash
48+
source setup.sh
49+
```
50+
51+
## Building the Wheel
52+
This project uses Poetry for packaging and dependency management.
53+
54+
### Step 1: Build the Wheel
55+
```bash
56+
poetry build
57+
```
58+
This will generate a .whl file and .tar.gz source distribution in the dist/ directory.
59+
60+
## Installing the Package Locally
61+
After building the wheel:
62+
63+
```bash
64+
pip install dist/system_metrics_collector-<version>-py3-none-any.whl
65+
```
66+
Replace <version> with the actual version number shown in the wheel filename.
67+
68+
## Usage
69+
```bash
70+
asp [OPTIONS]
71+
```
72+
73+
### Examples
74+
75+
#### Output Help Message
76+
```bash
77+
asp --help
78+
```
79+
80+
#### Sample Commands
81+
82+
```bash
83+
#Supported Collectors:
84+
#cpu,cpu_freq,cpu_power,io,irq_affinity,network,numastat,perf
85+
86+
# generate 20 samples at 2 seconds interval, all collectors
87+
asp -n 20 -i 2 -N $NETWORK_INTERFACE
88+
89+
# generate 20 samples at 1 seconds interval, only collect cpu utilization,cpu_freq and cpu_power
90+
asp -n 20 -i 1 -c cpu,cpu_freq,cpu_power
91+
92+
93+
# generate 20 samples at 2 seconds interval, all collectors execept perf
94+
asp -n 20 -i 2 -f
95+
96+
97+
# generate 20 samples at 1 seconds interval, only collect cpu utilization, cpu_freq, io, network, and perf with lower frequency rate of 99
98+
asp -n 20 -i 1 -c cpu,cpu_freq,io,network,perf -F 99
99+
```
100+
101+
## CLI Options
102+
| Option | Description |
103+
| ------------ | ---------------------------------------------------------- |
104+
| `-n INTEGER` | Number of samples to take |
105+
| `-i INTEGER` | Interval in seconds between samples |
106+
| `-o TEXT` | Output directory for collected data |
107+
| `-c TEXT` | Comma-separated list of collectors to use |
108+
| `-f` | Disable `perf` collection |
109+
| `-p` | Disable plotting of results |
110+
| `-F INTEGER` | Sampling frequency for `perf` collector (default: 4000 Hz) |
111+
| `-N TEXT` | Network interface to monitor (e.g., eth0) |
112+
| `-h, --help` | Show help message and exit |
113+
114+
## Output
115+
- Data is stored as .dat files in the specified output directory.
116+
- If plotting is enabled, an report.html file is generated after collection.
117+
118+
## Tested on
119+
- Ubuntu 20.04
120+
- Ubuntu 22.04
121+
- Ubuntu 24.04
122+
- Ubuntu 25.04
123+
- Fedora 40
124+
- Fedora 41
125+
- Fedora 42
126+
- Debian 12
127+
- Debian 13
128+
- Oracle Linux 9
129+
130+
## FAQ
131+
- For non standard kernels, ensure perf is installed to see hotspots.
132+
- For runs on the cloud, readings from Frequency and Perf Hotspots might not show up.
133+
- Cloud runs will not show power.

0 commit comments

Comments
 (0)