You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+49-31
Original file line number
Diff line number
Diff line change
@@ -9,6 +9,7 @@ Intel® PerfSpect is a command-line tool designed to help you analyze and opt
9
9
We welcome bug reports and enhancement requests, which can be submitted via the [Issues](https://github.com/intel/PerfSpect/issues) section on GitHub. For those interested in contributing to the code, please refer to the guidelines outlined in the [CONTRIBUTING.md](CONTRIBUTING.md) file.
10
10
11
11
## Getting PerfSpect
12
+
Pre-built PerfSpect releases are available in the repository's [Releases](https://github.com/intel/PerfSpect/releases). Download and extract perfspect.tgz.
12
13
```
13
14
wget -qO- https://github.com/intel/PerfSpect/releases/latest/download/perfspect.tgz | tar xvz
14
15
cd perfspect
@@ -23,42 +24,42 @@ Usage:
23
24
### Commands
24
25
| Command | Description |
25
26
| ------- | ----------- |
26
-
|[`metrics`](#metrics-command)| Report core and uncore metrics |
27
-
|[`report`](#report-command)| Report configuration and health |
28
-
|[`telemetry`](#telemetry-command)| Report system telemetry |
|[`metrics`](#metrics-command)| CPU core and uncore metrics |
28
+
|[`report`](#report-command)| System configuration and health |
29
+
|[`telemetry`](#telemetry-command)| System telemetry |
30
+
|[`flame`](#flame-command)| Software call-stacks as flamegraphs |
31
+
|[`lock`](#lock-command)| Software hot spot, cache-to-cache and lock contention |
30
32
|[`config`](#config-command)| Modify system configuration |
31
-
|[`lock`](#lock-command)| Collect system wide hot spot, c2c and lock contention information |
32
33
33
34
> [!TIP]
34
35
> Run `perfspect [command] -h` to view command-specific help text.
35
36
36
37
#### Metrics Command
37
38
The `metrics` command generates reports containing CPU architectural performance characterization metrics in HTML and CSV formats. Run `perfspect metrics`.
38
39
39
-
40
+
40
41
41
42
##### Live Metrics
42
43
The `metrics` command supports two modes -- default and "live". Default mode behaves as above -- metrics are collected and saved into report files for review. The "live" mode prints the metrics to stdout where they can be viewed in the console and/or redirected into a file or observability pipeline. Run `perfspect metrics --live`.
43
44
44
-
45
+
45
46
46
47
##### Metrics Without Root Permissions
47
-
If sudo is not possible and running as the root user is not possible, the following configuration needs to be applied to the target system(s) by an administrator:
48
+
If neither sudo nor root access is available, an administrator must apply the following configuration to the target system(s):
48
49
- sysctl -w kernel.perf_event_paranoid=0
49
50
- sysctl -w kernel.nmi_watchdog=0
50
-
- write '125' to all perf_event_mux_interval_ms files found under /sys/devices/*, e.g., `for i in $(find /sys/devices -name perf_event_mux_interval_ms); do echo 125 > $i; done`
51
+
- write '125' to all perf_event_mux_interval_ms files found under /sys/devices/*, for example, `for i in $(find /sys/devices -name perf_event_mux_interval_ms); do echo 125 > $i; done`
51
52
52
-
Once the configuration changes are applied, use the `--noroot` flag on the command line, e.g., `perfspect metrics --noroot`.
53
+
Once the configuration changes are applied, use the `--noroot` flag on the command line, for example, `perfspect metrics --noroot`.
53
54
54
55
See `perfspect metrics -h` for the extensive set of options and examples.
55
56
56
57
#### Report Command
57
-
The `report` command generates system configuration reports in a variety of formats. By default, all categories of information are collected. See `perfspect report -h` for all options.
58
+
The `report` command generates system configuration reports in a variety of formats. All categories of information are collected by default. See `perfspect report -h` for all options.
58
59
59
-
60
+
60
61
61
-
It's possible to collect a subset of information by providing command line options. Note that by specifying only the `txt` format, it is printed to stdout, as well as written to a report file.
62
+
It's possible to report a subset of information by providing command line options. Note that by specifying only the `txt` format, it is printed to stdout, as well as written to a report file.
To assist in evaluating the health of target systems, the `report` command can run a series of micro-benchmarks by applying the `--benchmark` flag, e.g., `perfspect report --benchmark all` The benchmark results will be reported along with the target's configuration details.
72
+
To assist in evaluating the health of target systems, the `report` command can run a series of micro-benchmarks by applying the `--benchmark` flag, for example, `perfspect report --benchmark all` The benchmark results will be reported along with the target's configuration details.
72
73
73
74
> [!IMPORTANT]
74
-
> Benchmarks should be run on idle systems to measure accurately and to avoid interfering with active workloads.
75
+
> Benchmarks should be run on idle systems to ensure accurate measurements and to avoid interfering with active workloads.
75
76
76
77
| benchmark | Description |
77
78
| --------- | ----------- |
@@ -85,62 +86,79 @@ To assist in evaluating the health of target systems, the `report` command can r
85
86
| storage | runs [fio](https://github.com/axboe/fio) for 2 minutes in read/write mode with a single worker to measure single-thread read and write bandwidth. Use the --storage-dir flag to override the default location. Minimum 5GB disk space required to run test. |
86
87
87
88
#### Telemetry Command
88
-
The `telemetry` command reports CPU utilization, instruction mix, disk stats, network stats, and more on the specified target(s). By default, all telemetry types are collected. To choose telemetry types, see the additional command line options (`perfspect telemetry -h`).
89
+
The `telemetry` command reports CPU utilization, instruction mix, disk stats, network stats, and more on the specified target(s). All telemetry types are collected by default. To choose telemetry types, see the additional command line options (`perfspect telemetry -h`).
89
90
90
-
91
+
91
92
92
93
#### Flame Command
93
94
Software flamegraphs are useful in diagnosing software performance bottlenecks. Run `perfspect flame` to capture a system-wide software flamegraph.
94
95
95
96
> [!NOTE]
96
-
> Perl must be installed on the target system to process the data required for flamegraphs.
97
+
> Perl is required on the target system to process the data needed for flamegraphs.
97
98
98
-
99
+
100
+
101
+
#### Lock Command
102
+
As systems contain more and more cores, it can be useful to analyze the Linux kernel lock overhead and potential false-sharing that impacts system scalability. Run `perfspect lock` to collect system-wide hot spot, cache-to-cache and lock contention information. Experienced performance engineers can analyze the collected information to identify bottlenecks.
99
103
100
104
#### Config Command
101
105
The `config` command provides a method to view and change various system configuration parameters. Run `perfspect config -h` to view the parameters that can be modified.
102
106
103
107
> [!WARNING]
104
-
> It is possible to configure the system in a way that it will no longer operate. In some cases, a reboot will be required to return to default settings.
108
+
> Misconfiguring the system may cause it to stop functionining. In some cases, a reboot may be required to restore default settings.
As systems contain more and more cores, it can be useful to analyze the Linux kernel lock overhead and potential false-sharing that impacts system scalability. Run `perfspect lock` to collect system wide hot spot, cache-to-cache and lock contention information. Experienced performance engineers can analyze the collected information to identify bottlenecks.
114
-
115
116
### Common Command Options
116
117
117
118
#### Local vs. Remote Targets
118
-
By default, PerfSpect targets the local host, i.e., the host where PerfSpect is running. Remote system(s) can also be targetted when the remote systems are reachable through SSH from the local host.
119
+
By default, PerfSpect targets the local host, that is, the host where PerfSpect is running. Remote systems can also be targeted if they are reachable via SSH from the local host.
119
120
120
-
> [!NOTE]
121
+
> [!IMPORTANT]
121
122
> Ensure the remote user has password-less sudo access (or root privileges) to fully utilize PerfSpect's capabilities.
122
123
123
-
To target a single remote system using a pre-configured private key:
124
+
To target a single remote system with a pre-configured private key:
124
125
<pre>
125
126
$ ./perfspect report --target 192.168.1.42 --user fred --key ~/.ssh/fredkey
126
127
...
127
128
</pre>
128
-
To target a single remote system using a password:
129
+
To target a single remote system with a password:
129
130
<pre>
130
131
$ ./perfspect report --target 192.168.1.42 --user fred
To target more than one remote system, a YAML file with the necessary connection parameters is provided to PerfSpect. See the example YAML file [targets.yaml](targets.yaml).
135
+
To target more than one remote system, a YAML file with the necessary connection parameters is provided to PerfSpect. Refer to the example YAML file:[targets.yaml](targets.yaml).
135
136
<pre>
136
137
$ ./perfspect report --targets mytargets.yaml
137
138
...
138
139
</pre>
140
+
141
+
> [!NOTE]
142
+
> All PerfSpect commands support remote targets, but some command options are limited to the local target.
143
+
144
+
#### Output
145
+
##### Logging
146
+
By default, PerfSpect writes to a log file (perfspect.log) in the user's current working directory. Optionally, PerfSpect can direct logs to the local system's syslog daemon.
147
+
<pre>
148
+
$ ./perfspect metrics --syslog
149
+
</pre>
150
+
151
+
##### Report Files
152
+
By default, PerfSpect creates a unique directory in the user's current working directory to store output files. Users can specify a custom output directory, but the directory provided must exist; PerfSpect will not create it.
> Skip the build. Pre-built PerfSpect releases are available in the repository's [Releases](https://github.com/intel/PerfSpect/releases). Download and extract perfspect.tgz.
142
160
### 1st Build
143
-
`builder/build.sh`builds the dependencies and the app in Docker containers that provide the required build environments. Assumes you have Docker installed on your development system.
161
+
Use `builder/build.sh`to build the dependencies and the application in Docker containers with the required build environments. Ensure Docker is properly configured on your build system before running the script.
144
162
145
163
### Subsequent Builds
146
-
`make` builds the app. Assumes the dependencies have been built previously and that you have Go installed on your development system.
164
+
`make` builds the app. It assumes the dependencies have been built previously and that you have Go installed on your development system. See [go.mod](go.mod) for the minimum Go version.
0 commit comments