1<a name="perf-counters" /> 2 3# User-Requested Performance Counters 4 5When running benchmarks, the user may choose to request collection of 6performance counters. This may be useful in investigation scenarios - narrowing 7down the cause of a regression; or verifying that the underlying cause of a 8performance improvement matches expectations. 9 10This 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/) be available at build 16 time 17 18The feature does not require modifying benchmark code. Counter collection is 19handled at the boundaries where timer collection is also handled. 20 21To opt-in: 22 23* Install `libpfm4-dev`, e.g. `apt-get install libpfm4-dev`. 24* Enable the cmake flag BENCHMARK_ENABLE_LIBPFM. 25 26To use, pass a comma-separated list of counter names through the 27`--benchmark_perf_counters` flag. The names are decoded through libpfm - meaning, 28they are platform specific, but some (e.g. `CYCLES` or `INSTRUCTIONS`) are 29mapped by libpfm to platform-specifics - see libpfm 30[documentation](http://perfmon2.sourceforge.net/docs.html) for more details. 31 32The counter values are reported back through the [User Counters](../README.md#custom-counters) 33mechanism, meaning, they are available in all the formats (e.g. JSON) supported 34by User Counters.