Adaptyst

Quick start

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

  1. 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. Profile a command of your choice by running this as root (no quoting required):
adaptyst -- <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 -- /bin/bash -c "program123 < test.txt".

Running Adaptyst as non-root

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

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 on a single NUMA memory node only.

  1. When Adaptyst finishes its job, switch to the Python environment where Adaptyst Analyser is installed and run this (where <path to results> is usually ./results if you haven’t changed your current directory):
adaptyst-analyser <path to 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 to learn how to use the produced website most effectively.

Prev
What is Adaptyst?
Next
Website navigation