Title here
Summary here
Running Adaptyst
Starting performance analysis
After you set up modules and define your computer system, you can analyse your first program!
At the moment, Adaptyst supports commands only for performance analysis (more workflow types are coming soon). To analyse your program, please run the following command:
adaptyst -s <path to your system def file> -d <command to be run and analysed>Important
- If your command has whitespaces, you must run Adaptyst in one of these ways:
adaptyst -s <path to your system def file> -d "<command to be run and analysed>"oradaptyst -s <path to your system def file> -d -- <command to be run and analysed>. - 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 analyseprogram123 < test.txtrun through bash, you need to executeadaptyst -s <path to your system def file> -d -- /bin/bash -c "program123 < test.txt".
Permissions required to run Adaptyst
Depending on the modules used, Adaptyst may need to be run as root or with specific permission setup steps performed beforehand. See the documentation of your modules for more information.
If you want to see what extra options you can set, run adaptyst --help.Help message printed by
adaptyst --helpAdaptyst: a performance analysis tool
adaptyst [OPTIONS] [COMMAND/PATH...]
POSITIONALS:
COMMAND/PATH Path to a workflow to be analysed
(required). If -d is set, a command to be
analysed should be provided instead.
OPTIONS:
-h, --help Print this help message and exit
-v, --version Display program version information and exit
--modules List in detail all installed system modules
and exit
--plugins List in detail all installed workflow
plugins and exit
-m, --module-help MODULE Print the help message of a given module
and exit
-p, --plugin-help PLUGIN Print the help message of a given plugin
and exit
-d, --command Indicates that a command will be provided
for analysis rather than the path to a YAML
file defining a workflow to be analysed
-s, --system FILE Path to the definition file of a computer
system (required). See the documentation to
learn how to write a computer system
definition file.
-o, --output PATH Path to the directory where analysis
results should be saved (default:
adaptyst_<UTC timestamp>__<positive
integer>)
-l, --label TEXT Label of the performance analysis session
(default: adaptyst_<UTC
timestamp>__<positive integer>)
--no-format Do not use any non-standard terminal
formatting
If you want to change the paths of the system-wide and local Adaptyst
configuration files, set the environment variables ADAPTYST_CONFIG and
ADAPTYST_LOCAL_CONFIG respectively to values of your choice. Similarly,
you can set the ADAPTYST_MODULE_DIR environment variable to change the path
where Adaptyst looks for workflow plugins and system modules.
After performance analysis is completed, you can check the results inside adaptyst_<UTC timestamp>__<positive integer> (e.g. adaptyst_2025_08_12_13_05_43__1) unless you have
set the -o option (then you can check the folder you have specified via -o).
You can run adaptyst multiple times, all performance analysis results will be saved in separate folders inside the same working directory provided that you haven’t set the -o option.
Structure of results
- log: Logs produced by Adaptyst and entities/nodes/modules, structured into entities -> nodes -> modules. Additional files are provided below.
- <entity>_stdout.log: stdout of a user workflow in case it has been run in an entity.
- <entity>_stderr.log: stderr of a user workflow in case it has been run in an entity.
- system: Results produced by entities/nodes/modules, structured into entities -> nodes -> modules. The structure inside modules is module-dependent. Additional files are provided below.
- system.yml: The copy of a system definition file.
- <entity>/src.zip: Detected source code files of a user workflow within an entity.
- <entity>/dirmeta.json: User workflow execution metadata such as its exit code in case the workflow has been run in an entity. This file is optional.
- dirmeta.json: Session metadata such as its date and time.
Configuration files
If you haven’t provided a custom config file path when installing Adaptyst, the system-wide configuration file can be found in /etc/adaptyst.conf. Additionally, in case you want to provide your own local settings, any values set system-wide can be overridden and any other extra values can be added by a local config file in .adaptyst/adaptyst.conf inside your home directory. Both files follow exactly the same syntax.
If you want to use a different path for the system-wide config and/or local config at runtime, you can set the ADAPTYST_CONFIG and ADAPTYST_LOCAL_CONFIG environment variables respectively. Additionally, Adaptyst calls modules from inside /opt/adaptyst/modules by default, but this path can also be changed at runtime by setting the ADAPTYST_MODULE_DIR environment variable. Similarly, Adaptyst looks for its support files inside /opt/adaptyst, but this path can be changed at runtime through the ADAPTYST_MISC_DIR environment variable. It is possible to vary most of these paths permanently as well when compiling Adaptyst from source, see the installation guide.
The currently-supported settings in the configuration files are shown below:Config file format with supported settings
# The Adaptyst core doesn't use configuration files in the current version.
# However, any update in the future may introduce new settings here.
Containers
Adaptyst can run in a Docker or Apptainer/Singularity container. For a quick start, the ready-to-use images are provided by us (see Installation).
Module-specific container options
If you run Adaptyst in a containerised way, you must check if your modules should be set up in a specific way due to running in a container. See the documentation of your modules for more information. If the docs do not say anything, you can assume that the modules can run as usual in a container.
Analysed source code packaging
By default, Adaptyst looks for and packs source code files within entities where your analysed program is run.
Varying source code packaging
The current modular version of Adaptyst doesn’t support varying how source code files are listed/packed. This will change in the future. Sorry for any inconvenience caused!