Home

Awesome

pmu-tools

Python linting and testing Old Python linting and testing jevents test

pmu tools is a collection of tools and libraries for profile collection and performance analysis on Intel CPUs on top of Linux perf. This uses performance counters in the CPU.

Quick (non-) installation

pmu-tools doesn't really need to be installed. It's enough to clone the repository and run the respective tool (like toplev or ocperf) out of the source directory.

To run it from other directories you can use export PATH=$PATH:/path/to/pmu-tools or symlink the tool you're interested in to /usr/local/bin or ~/bin. The tools automatically find their python dependencies.

When first run, toplev / ocperf will automatically download the Intel event lists from https://github.com/intel/perfmon. This requires working internet access. Later runs can be done offline. It's also possible to download the event lists ahead, see pmu-tools offline

toplev works with both python 2.7 and python 3. However it requires an not too old perf tools and depending on the CPU an uptodate kernel. For more details see toplev kernel support

The majority of the tools also don't require any python dependencies and run in "included batteries only" mode. The main exception is generating plots or XLSX spreadsheets, which require external libraries.

If you want to use those run

  pip install -r requirements.txt

once, or follow the command suggested in error messages.

jevents is a C library. It has no dependencies other than gcc/make and can be built with

cd jevents
make

Quick examples

toplev -l2 program

measure whole system in level 2 while program is running

toplev -l1 --single-thread program

measure single threaded program. On hyper threaded systems with Skylake or older the system should be idle.

toplev -NB program

Measure program showing consolidated bottleneck view and extra information associated with bottlenecks. Note this will multiplex performance counters, so there may be measuring errors.

toplev -NB --run-sample program

Measure programing showing bottlenecks and extra nodes, and automatically sample for the location of bottlenecks in a second pass.

toplev --drilldown --only-bottleneck program

Rerun workload with minimal multiplexing until critical bottleneck is found. Only print critical bottleneck

toplev -l3 --no-desc -I 100 -x, sleep X

measure whole system for X seconds every 100ms, outputting in CSV format.

toplev --all --core C0 taskset -c 0,1 program

Measure program running on core 0 with all nodes and metrics enabled.

toplev --all --xlsx x.xlsx -a sleep 10

Generate spreadsheet with full system measurement for 10 seconds

For more details on toplev please see the toplev tutorial

What tool to use for what?

You want to:

For more details on the tools see TOOLS

All features:

Major tools/libraries

There are some obsolete tools which are not supported anymore, like simple-pebs. These are kept as PMU programming reference, but may need some updates to build on newer Linux kernels.

Recent new features:

TMA 5.01 release

TMA 4.8 release

TMA 4.7 release

TMA 4.6 release

TMA 4.4 release

TMA 4.3 release

TMA 4.2 release

TMA 4.1 release

Older changes in CHANGES

Help wanted

Mailing list

Please post to the linux-perf-users@vger.kernel.org mailing list. For bugs please open an issue on https://github.com/andikleen/pmu-tools/issues

Licenses

ocperf, toplev, ucevent, parser are under GPLv2, jevents is under the modified BSD license.

Andi Kleen