perf2otf
========

The script provided in this package record a perf.data file (using "perf record") and convert it to
a trace in the Open Trace Format (OTF). The trace file can then be visualized using Vampir
(http://vampir.eu) or analyzed with other OTF capable tools.


Requirements:
=============

 * Python 2
   - For some versions of Linux, "python" and "python-config" must point to the python2 versions.

 * A Version of perf (linux/tools/perf) with our patches applied to the python scripting interface.
   - Should be available at kernel/git/acme/perf.git and later the mainline kernel soon
   - In the meantime apply the supplied patches in ../linux-perf-patches to
     the linux 3.15.5 release (https://www.kernel.org/pub/linux/kernel/v3.x/linux-3.15.5.tar.xz)
   - The patches only apply to the tools/perf folder and affect the userspace tool, 
     no re-installation of the actual kernel is needed
   - The patches apply with some offsets but have been tested
   - Proper build requires developer versions of: python, elfutils, (libunwind)
   - Build with:
     cd linux-<VERSION>/tools/perf
     make install O=<BUILDPATH> DESTDIR=<INSTALLPATH> NO_LIBPERL=yes
   - Must build with "libpython" enabled!
     
 * Swig (for the OTF python bindings)
 
 * The OTF library (open-trace-format), configured with python bindings
   - http://tu-dresden.de/zih/otf/dateien/OTF-1.12.4salmon.tar.gz
   - ./configure --enable-python-bindings --prefix=/opt/otf
   - PYTHONPATH needs to be set properly, e.g. including
     /opt/otf/lib/python2.7/site-packages
   - LD_LIBRARY_PATH needs to be set properly, e.g. including
     /opt/otf/lib
   Note: Do not use otf2.

 * PERF_EXEC_PATH set to the installation directory of perf and
   $PERF_EXEC_PATH/libexec/perf-core/scripts/python/Perf-Trace-Util/lib/Perf/Trace/ 
   must be added to the PYTHONPATH environment variable

 * Vampir for visualization of the trace: www.vampir.eu

 
How to use:
===========

 record.sh combines the recording and conversion, you should adapt it to your  specific needs. Any
 argument passed to record.sh is forwarded to perf record, e.g., the -e option to choose events to
 record. The argumenents passed can also include the application under analysis. 
 
 Manual use:
 1) perf record
    with your preferred events and options
    should include call graph (-g)
    may be system-wide (-a) or only for one application
 2) perf script -i $PERF_DATA -s $PERF2OTF


Runtime configuration (environment variables):
==============================================

Configuration of perf2otf (used via perf script):
  PERF_OTF_GROUP=
    CORE              group events by CORE (a cpu core equals an otf process)
    PROCESS           group events by PROCESS (a process equals an otf process)

  PERF_OTF_NAMESTUB   name prefix of the otf files
                      can include a directory component (must exist)

Configuration of record.sh:
  PERF_DATA           the prefix path of the perf data file
                      can include a directory
  PERF2OTF            the path to the "perf2otf.py" python script
  
Consider increasing the value of /proc/sys/kernel/perf_event_mlock_kb. This will allow to use more
pages as buffer so that the recording has to be interrupted less often, ideally never until the end.
Perf will report "Woken up 2 times to write data". The wakeups will perturb your measurement data.
If you increased the perf_event_mlock_kb, you can add the "-m" flag to perf record in record.sh
e.g. "-m 2048".

By default recording traces as unprivileged user is limited to processes owned by the user and
tracepoints are not available for security reasaons. If you want to record more detailed traces as
unprivileged user:

You may want to set the paranoia level to -1 or 0
  echo 0 > /proc/sys/kernel/perf_event_paranoid

To record tracepoints, access to /sys/kernel/debug/tracing/events/... is required.
Usually /sys/kernel/debug is not available to unprivileged users.


Authors:
========

Please contact the authors with any questions or suggestions.

Thomas Ilsche     <thomas.ilsche@tu-dresden.de>
Joseph Schuchart  <joseph.schuchart@tu-dresden.de>
Robert Schöne     <robert.schoene@tu-dresden.de>
Danny Rotscher    <danny.rotscher@tu-dresden.de>
Daniel Hackenberg <daniel.hackenberg@tu-dresden.de>
