How to use

Web server / Interactive website#

The main functionality of Adaptyst Analyser is a web server serving the interactive website for browsing performance analysis results produced e.g. by Adaptyst.

The server can be started by running adaptyst-analyser <path to results>, where <path to results> is the path to a results directory created e.g. by Adaptyst. For configuration options, see adaptyst-analyser --help.

$ adaptyst-analyser --help
usage: adaptyst-analyser [-h] [--version] [-a ADDR] [-o INT FROM 0 TO 100] PATH

Adaptyst Analyser web server

positional arguments:
  PATH                  path to a profiling results directory (relative or absolute)

optional arguments:
  -h, --help            show this help message and exit
  --version             print version and exit
  -a ADDR               address and port to bind to, default: 127.0.0.1:8000
  -o INT FROM 0 TO 100  default off-CPU timeline display scale for users (the value is an integer between 0 and 100 inclusive converted to the scale
                        between 0.0 and 1.0, where 0.0 means "do not display any off-CPU periods on the timeline", 1.0 means "display all off-CPU periods
                        on the timeline", and anything in-between means "sample off-CPU periods on the timeline in a similar way Adaptyst does during
                        profiling, with the sampling frequency being higher with higher values") (default: 100)

When adaptyst-analyser is run, look out for an output line similar to this:

[2024-10-12 13:57:52 +0200] [2192] [INFO] Listening at: http://127.0.0.1:8000 (2192)

The address points to the website where you can browse your profiling results.

Under the hood, Gunicorn and Flask are used (set up automatically when installing Adaptyst Analyser).

If you prefer not to use adaptyst-analyser or you cannot use it, set the FLASK_PROFILING_STORAGE environment variable to the path to a results directory and start the adaptystanalyser.app:app Flask app using a method of your choice.

Off-CPU timeline sampling#

If you have a profiling session with a huge number of off-CPU regions, rendering the timeline may become resource- and time-consuming for a web browser. In this case, you may want to enable off-CPU timeline sampling which samples captured off-CPU regions in a similar way Adaptyst samples off-CPU activity during profiling.

This can be done on the client side by setting the off-CPU timeline display scale to less than 1 in settings at the website (the smaller the value is than 1, the larger the sampling period is; the current period is shown when a profiling session is opened).

The default value of the display scale can be changed on the server side by running adaptyst-analyser -o <int from 0 to 100> <path to results> (where the integer from 0 to 100 is converted later to a number between 0.0 and 1.0 inclusive) or setting the FLASK_OFFCPU_SAMPLING environment variable to your value of choice between 0.0 and 1.0 inclusive in case you don’t use adaptyst-analyser.

Using results from other programs than Adaptyst#

While Adaptyst Analyser is designed with Adaptyst in mind, it can be used with any other profiler which produces result files in the Adaptyst format.

You can check the source code of Adaptyst for learning how it formats its profiling results.