// Overview / API / FAQ / Resources

prof: Profiling Wrapper library

https://en.wikipedia.org/wiki/Profiling_(computer_programming)

Overview

Single header/module profiling wrapper library with a common interface for:
linux-perf, intel-vtune, amd-uprof, gperftools, llvm-xray, callgrind

Requirements

C++20 (clang++13+, g++11+)

• linux-perf - apt get install linux-tools-common
• intel-vtune - apt get install intel-oneapi-vtune
• amd-uprof - https://www.amd.com/en/developer/uprof.html#downloads
• gperftools - apt get install google-perftools
• llvm-xray - apt-get install llvm
• callgrind - apt-get install valgrind

Dockerfile / setup

Overview

import prof;

int main() {
  prof::perf profiler{"/dev/shm/perf"};
  profiler.start();
  // ...
  profiler.stop();
}

$CXX -std=c++20 -O3 -g perf.cpp
perf record --control=fifo:/dev/shm/perf --delay=-1 ./a.out

import prof;

int main() {
  prof::vtune profiler{"domain", "task"};
  profiler.start();
  // ...
  profiler.stop();
}

$CXX -std=c++20 -O3 -g vtune.cpp -littnotify
vtune -collect performance-snapshot -start-paused -finalization-mode=full -r result \
-- ./a.out

import prof;

int main() {
  prof::uprof profiler{};
  profiler.start();
  // ...
  profiler.stop();
}

$CXX -std=c++20 -O3 -g uprof.cpp -lAMDProfileController
AMDuProfCLI collect --config tbp --start-paused ./a.out

import prof;

int main() {
  prof::gperf profiler{"gperf"};
  profiler.start();
  // ...
  profiler.stop();
  profiler.flush(); // optional
}

$CXX std=c++20 -O3 -g gperf.cpp -lprofiler
CPUPROFILE_FREQUENCY=1000 ./a.out
google-pprof a.out gperf.prof

import prof;

int main() {
  prof::xray profiler{"xray-fdr"};
  profiler.start();
  // ...
  profiler.stop();
  profiler.flush(); // optional
}

clang++ std=c++20 -O3 -g xray.cpp -fxray-instrument -fxray-instruction-threshold=1
./a.out
llvm-xray account xray-log.* --top=10 --sort=sum --sortorder=dsc --instr_map=./a.out

import prof;

int main() {
  prof::callgrind callgrind{"profile"};
  profiler.start();
  // ...
  profiler.stop();
  profiler.flush(); // optional
}

$CXX std=c++20 -O3 -g callgrind.cpp
valgrind --tool=callgrind --instr-atstart=no ./a.out
kcachegrind callgrind.*

API

• https://github.com/qlibs/prof/blob/main/prof.cppm

FAQ

• How to setup docker?

  docker build -t prof .

  docker run \
    -it \
    --privileged \
    --network=host \
    -e DISPLAY=${DISPLAY} \
    -v ${PWD}:${PWD} \
    -w ${PWD} \
    prof

  Dockerfile

• How to profile conditionally with callgrind?

  prof::callgrind profiler{"example"};
  
  while (true) {
    profiler.start(); // resets profile
  
    if (should_trigger()) {
      trigger();
      profiler.stop();
      proflier.flush(); // dumps `example` profile
    }
  }

  kcachegrind callgrind.* # opens all profiles combined

• How to instrument with llvm-xray?

  [[clang::xray_always_instrument]]
  void always_profile();
  
  [[clang::xray_always_instrument, clang::xray_log_args(1)]]
  void always_profile_and_log_i(int i);
  
  [[clang::xray_never_instrument]]
  void never_profile();

  # profiling threshold
  -fxray-instruction-threshold=1 # default 200 instructions

  # instrumentation info
  llvm-xray extract ./a.out --symbolize

  https://godbolt.org/z/WhsEYf9cc

• How to set custom handler with llvm-xray?

  void handler([[maybe_unused]] int32_t func_id, XRayEntryType entry) {
    if (entry == XRayEntryType::ENTRY) {
      // profiler.start();
    } else {
      // profiler.stop();
    }
  }

  int main() {
    __xray_set_handler(handler);
    __xray_patch();
  }

Resources

• https://perfwiki.github.io
• https://www.intel.com/content/www/us/en/developer/tools/oneapi/vtune-profiler.html
• https://www.amd.com/en/developer/uprof.html
• https://github.com/gperftools/gperftools
• https://llvm.org/docs/XRay.html
• https://valgrind.org/docs/manual/cl-manual.html

License

• MIT