third-party/benchmark/docs/perf_counters.md

   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.