Adaptyst

Quick start

Don’t know where to start? These seven steps will set you up quickly on Linux:

  1. Set up the linuxperf module in both Adaptyst and Adaptyst Analyser.

  2. Make sure that your profiled program is compiled with frame pointers (otherwise, you may get broken stack traces in the performance analysis results). If you use GCC, this can be done by using the -fno-omit-frame-pointer and -mno-omit-leaf-frame-pointer (if available) compilation flags.

Note

Although not strictly necessary, we recommend having everything in your system compiled with frame pointers. Some Linux distributions already ship frame-pointer-friendly packages by default, e.g. Fedora 38+, Ubuntu 24.04+, and Arch Linux.

  1. Run this command (it changes the kernel settings for an entire machine, so be careful if you use a shared computer!):
sysctl kernel.perf_event_max_stack=1024
  1. Save the content below to system.yml (or other name of your choice):
entities:
  entity1:
    options:
      handle_mode: local
      processing_threads: 1  # Change this to a higher number if you have multiple CPUs/cores
    nodes:
      cpu:
        modules:
          - name: linuxperf
  1. Profile a command of your choice by running this as root (no quoting required):
adaptyst -s system.yml -d -- <command to be profiled>

Using shell-specific syntax

If your command uses any shell-specific syntax (e.g. redirection using < or >), you need to pass it through your shell as Adaptyst uses direct system calls to run programs. For example, to profile program123 < test.txt run through bash, you need to execute adaptyst -s system.yml -d -- /bin/bash -c "program123 < test.txt".

Running Adaptyst as non-root

It is possible to run Adaptyst with linuxperf as non-root, but this requires some permission-related sysadmin steps since linuxperf needs higher privileges than a standard non-root user has (it is not necessary to grant full root rights though!). See here.

Warning

If you have NUMA (non-uniform memory access), you must either disable NUMA balancing for an entire machine by running sysctl kernel.numa_balancing=0 or run Adaptyst with linuxperf on a single NUMA memory node only.

  1. When Adaptyst finishes its job, move the produced results directory (by default: adaptyst_<UTC timestamp>__<positive integer>) to a new directory results (or other name of your choice), switch to the Python environment where Adaptyst Analyser is installed, and run this:
adaptyst-analyser results
  1. Open the indicated address in your browser (the output may differ, check your terminal window!):
[2024-10-12 13:57:52 +0200] [2192] [INFO] Listening at: http://127.0.0.1:8000 (2192)

Have fun! Consult the Adaptyst Analyser website navigation section along with the corresponding section for linuxperf to learn how to use the produced website most effectively.

Prev
nvgpu (NVIDIA GPUs)
Next
Running Adaptyst