| 1 |
<a name="perf-counters" /> |
| 2 |
|
| 3 |
# User-Requested Performance Counters |
| 4 |
|
| 5 |
When running benchmarks, the user may choose to request collection of |
| 6 |
performance counters. This may be useful in investigation scenarios - narrowing |
| 7 |
down the cause of a regression; or verifying that the underlying cause of a |
| 8 |
performance improvement matches expectations. |
| 9 |
|
| 10 |
This feature is available if: |
| 11 |
|
| 12 |
* The benchmark is run on an architecture featuring a Performance Monitoring |
| 13 |
Unit (PMU), |
| 14 |
* The benchmark is compiled with support for collecting counters. Currently, |
| 15 |
this requires [libpfm](http://perfmon2.sourceforge.net/), which is built as a |
| 16 |
dependency via Bazel. |
| 17 |
|
| 18 |
The feature does not require modifying benchmark code. Counter collection is |
| 19 |
handled at the boundaries where timer collection is also handled. |
| 20 |
|
| 21 |
To opt-in: |
| 22 |
* If using a Bazel build, add `--define pfm=1` to your build flags |
| 23 |
* If using CMake: |
| 24 |
* Install `libpfm4-dev`, e.g. `apt-get install libpfm4-dev`. |
| 25 |
* Enable the CMake flag `BENCHMARK_ENABLE_LIBPFM` in `CMakeLists.txt`. |
| 26 |
|
| 27 |
To use, pass a comma-separated list of counter names through the |
| 28 |
`--benchmark_perf_counters` flag. The names are decoded through libpfm - meaning, |
| 29 |
they are platform specific, but some (e.g. `CYCLES` or `INSTRUCTIONS`) are |
| 30 |
mapped by libpfm to platform-specifics - see libpfm |
| 31 |
[documentation](http://perfmon2.sourceforge.net/docs.html) for more details. |
| 32 |
|
| 33 |
The counter values are reported back through the [User Counters](../README.md#custom-counters) |
| 34 |
mechanism, meaning, they are available in all the formats (e.g. JSON) supported |
| 35 |
by User Counters. |