Installation

Thank you for considering Adaptyst! Please note that the current version is in an early development phase, which means that updates are deployed often and bugs are to be expected. Your feedback is very welcome as it will help guide our development efforts.

Adaptyst is a pack of command-line tools (adaptyst which is what you should start with as a beginner, adaptyst-server, and adaptyst-code) performing the proper performance analysis and saving its results in a non-encrypted format. They can be then inspected in a variety of ways, e.g. by our dedicated program called Adaptyst Analyser, which produces an interactive website similarly to how Jupyter works.

To benefit fully from Adaptyst, we recommend setting up both utilities. The installation instructions are here: Adaptyst and Adaptyst Analyser.

Adaptyst#

The full source code of Adaptyst can be found on GitHub: https://github.com/adaptyst/adaptyst.

Requirements#

By default, the full suite is installed, i.e. adaptyst, adaptyst-server, and adaptyst-code. For this, you need:

• Linux 5.8 or newer compiled with:
  • CONFIG_DEBUG_INFO_BTF=y (or equivalent, you can check this by seeing if /sys/kernel/btf exists in your system)
  • CONFIG_FTRACE_SYSCALLS=y (or equivalent, you can check this by seeing if /sys/kernel/tracing/events/syscalls exists in your system and is not empty, but you may need to mount /sys/kernel/tracing first)
  • If you want complete kernel debug symbols, CONFIG_KALLSYMS=y and CONFIG_KALLSYMS_ALL=y (or equivalent) should also be set.
  • Kernel recompilation may NOT be needed! If you have /sys/kernel/btf and /sys/kernel/tracing/events/syscalls as explained above and you don’t care about having kernel debug symbols, you’re already good to go here!
• Python 3.6 or newer (3.7 or newer for adaptyst-code)
• addr2line (part of binutils, tested with 2.35.2 and 2.42.0)
• CMake 3.20 or newer (if building from source)
• pkg-config (if building from source, tested with 2.3.0)
• GCC (if building from source, tested with 11.5 and 13.3.1, Clang will not compile Adaptyst except for the patched “perf”!)
• libnuma (if a machine with your profiled application has NUMA, tested with 2.0.18 and 2.0.19)
• CLI11 (if building from source, tested with 2.2.0 and 2.4.2)
• nlohmann-json (if building from source, tested with 3.11.3)
• PocoNet + PocoFoundation (tested with 1.12.2 and 1.14.0)
• Boost (header-only libraries and the program_options module, tested with 1.75.0 and 1.85.0)
• libarchive (tested with 3.5.3 and 3.7.7)
• The patched “perf” dependencies:
  • Clang (if building from source, can be removed after installing Adaptyst, tested with 17.0.6 and 18.1.8)
  • libtraceevent (tested with 1.5.3 and 1.8.3)
  • libelf (tested with 0.191)
  • flex (tested with 2.6.4)
  • Bison (tested with 3.7.4)
  • libbpf (tested with 1.4.0 and 1.5.0)
  • libpython (corresponding to Python 3.6 or newer)

If you install adaptyst-server alone, the requirements are different. You only need:

• CMake 3.20 or newer (if building from source)
• CLI11 (if building from source, tested with 2.2.0 and 2.4.2)
• nlohmann-json (if building from source, tested with 3.11.3)
• PocoNet + PocoFoundation (tested with 1.12.2 and 1.14.0)
• Boost (header-only libraries, tested with 1.75.0 and 1.85.0)

The tested dependency versions are a guideline only, Adaptyst may compile and run without issues with older versions (there have been problems with some older versions of nlohmann-json, CLI11, and libarchive though). However, it is recommended to use the newest versions available for your distribution (or for installing from source if distribution versions don’t solve e.g. compilation errors).

If you want to enable tests (see the documentation for contributors), you don’t have to install the GoogleTest framework beforehand, this is done automatically during the compilation.

Adaptyst uses the patched “perf”, temporarily available at https://gitlab.cern.ch/adaptyst/linux (inside tools/perf). However, you don’t have to download and install it manually, this is handled automatically by the installation scripts (see the “Manually” section below). If there are extra dependencies actually needed by the patched “perf” and not listed above, please let us know.

A profiled program along with dependencies should be compiled with frame pointers (i.e. in case of gcc, with the -fno-omit-frame-pointer flag along with -mno-omit-leaf-frame-pointer if available). If you can, it is recommended to have everything in the system compiled with frame pointers (this can be achieved e.g. in Gentoo and Fedora 38+).

Manually#

Please clone the GitHub repository and run cmake <path to your repository> in a separate directory (as either non-root or root, non-root recommended) followed by cmake --install . (as root unless you run the installation for a non-system prefix).

By default, the installation directory of Adaptyst is determined by CMake (e.g. /usr/local), but its support files along with the bundled patched “perf” are installed in /opt/adaptyst, and the configuration file of Adaptyst is installed in /etc/adaptyst.conf. The patched “perf” is downloaded and set up automatically by the build system (in a way not conflicting with any existing “perf” installations by default).

• If you want to specify the installation directory, you can run CMake with -DCMAKE_INSTALL_PREFIX=<path> or run cmake --install . --prefix <path>.
• If you want to change /opt/adaptyst, run CMake with -DADAPTYST_SCRIPT_PATH=<path>.
• If you want to change /etc/adaptyst.conf, run CMake with -DADAPTYST_CONFIG_PATH=<path including the filename>.
• If you want to change how “perf” is set up, see Advanced CMake options.

Please note that the /opt/adaptyst and /etc/adaptyst.conf paths can also be varied at runtime through the environment variables, see here.

adaptyst-server only#

If you want to install just adaptyst-server, please clone the GitHub repository and run cmake <path to your repository> -DSERVER_ONLY=ON in a separate directory (as either non-root or root, non-root recommended) followed by cmake --install . (as root unless you run the installation for a non-system prefix).

In case of a custom installation prefix, this can be set in the same way as indicated in the Manually section. adaptyst-server does not require the patched “perf” and should be compilable for various operating systems (the setup is only tested on Linux though).

Advanced CMake options#

• PERF: indicates whether the patched “perf” should be compiled and installed (default: ON). If this option is set to OFF, no other PERF_* values will be considered and the path to a local “perf” installation needs to be set manually in the Adaptyst configuration file: see here.
• PERF_DIR: indicates the path to a local “perf” installation to be used by Adaptyst. If this is set, the Adaptyst configuration file is updated automatically and no other “perf”-setup-related activities are performed.
• PERF_REPOSITORY_DIR: indicates the path to a local (not remote) patched “perf” repository which should be used for setting up “perf” (as a reminder, the patched “perf” is available at https://gitlab.cern.ch/adaptyst/linux). If this is set, “perf” will not be downloaded.
• PERF_TAG: indicates the git tag in the Adaptyst patched “perf” repository to be cloned/downloaded when setting up “perf”.

Gentoo-based virtual machine image with frame pointers#

Container image#

To ease the deployment of Adaptyst, we also provide Docker and Apptainer/Singularity images. x86-64 only is available at the moment, with more architectures coming soon.

There are two Adaptyst container variants:

• Gentoo (default): based on Gentoo with everything compiled with frame pointers and debug symbols.
• AlmaLinux 9: based on AlmaLinux 9 with glibc, GCC (including libstdc++ and libgcc), and Python 3 compiled with frame pointers and debug symbols.

Docker#

Please use:

• gitlab-registry.cern.ch/adaptyst/adaptyst:latest for the latest development version.
• gitlab-registry.cern.ch/adaptyst/adaptyst:<git tag> for a development version of your choice as indicated by a git tag (see here for the tag list; older tags may no longer be available as a Docker image though).

If you want to use the AlmaLinux 9 variant, use any of the tags above prefixed by alma9- (e.g. gitlab-registry.cern.ch/adaptyst/adaptyst:alma9-latest).

All images are public (no CERN login required), so no deployment to a non-CERN registry is planned.

Apptainer/Singularity#

The images are denoted by development versions as indicated by git tags (see here for the tag list; older tags may no longer be available as an Apptainer/Singularity image though) and can be downloaded from https://cernbox.cern.ch/s/XVwsHPOjvyb2YpU. Similarly to the Docker images, the AlmaLinux 9 variant is prefixed by alma9- there.

Adaptyst Analyser#

The full source code of Adaptyst Analyser can be found on GitHub: https://github.com/adaptyst/adaptyst-analyser.

Requirements#

Python 3.8 or newer. Also, you must have npm and Node.js 18 or newer during the installation process (you will not need these later). All other dependencies are installed automatically when setting up Adaptyst Analyser.

Setup#

This is a Python package, so you can install it with pip:

pip install git+https://github.com/adaptyst/adaptyst-analyser@<git tag>

where <git tag> is one of the git tags listed here (if you don’t know which one to choose, pick the latest one starting with “v”).

Windows#

At the moment, Adaptyst Analyser can be installed only on Unix-like systems such as Linux and macOS. Because these should also include WSL (Windows Subsystem for Linux), you should still be able to use the tool on Windows, with extra steps needed to set up WSL.

Getting started#

Once again, welcome to Adaptyst! Click here to see the quick start guide.