nvgpu (NVIDIA GPUs)

Introduction#

nvgpu is a system module for analysing activity of NVIDIA GPUs running CUDA-based programs. It looks into the runtime length of CUDA runtime and driver APIs of user-specified code regions at the moment, but the module will be improved over time.

Your feedback is more than welcome! Please see here how you can get in touch with us.

Installation#

Requirements#

First of all, make sure you satisfy the Adaptyst core requirements.

nvgpu requires CUDA with CUPTI (which should be included in CUDA by default). The earliest tested version is 12.5, but this is a guideline only: the module may work with older toolkits as well.

If you build from source, you also need:

• nlohmann-json
• CMake 3.20 or newer

Setup from source#

Short version:

git clone -b v0.1.0-dev.2026.03a https://github.com/adaptyst/adaptyst-nvgpu
cd adaptyst-nvgpu && mkdir build && cd build
cmake ..
cmake --build .
sudo cmake --install .

Long version:

Please clone the GitHub repository at the tag of your choice (it’s usually the newest one from here) and run cmake <path to your repository> in a separate directory (as either non-root or root, non-root recommended) followed by cmake --build . (as either non-root or root, non-root recommended) and cmake --install . (as root unless you run the installation for a non-system module directory).

Here are the CMake options you can use/change for nvgpu:

• INSTALL_PATH: indicates the path where nvgpu should be installed (default: the value provided by Adaptyst via ADAPTYST_MODULE_PATH in CMake, this is usually <user install prefix>/opt/adaptyst/modules)

Adaptyst Analyser module setup#

Short version:

git clone -b v0.1.0-dev.2026.07a https://github.com/adaptyst/adaptyst-analyser-nvgpu
adaptyst-analyser adaptyst-analyser-nvgpu

Long version:

The module for Adaptyst Analyser can be found on GitHub. As for all modules, the Adaptyst Analyser part is independent of the Adaptyst one and can be installed via adaptyst-analyser by cloning the repository at the tag of your choice (it’s usually the newest one from here) and running adaptyst-analyser <path to the cloned repository>.

Usage#

nvgpu utilises the code regionisation feature of Adaptyst to determine what parts of your program to analyse in terms of NVIDIA GPU activity. Once you define your code regions and add nvgpu to your system graph, the module should do its job automatically and produce results that can be inspected e.g. in Adaptyst Analyser.

Options#

Features for Adaptyst Analyser#

When you open the module window in Adaptyst Analyser, you will see the timeline of your code regions, where the time axis is synchronised with other modules so that you can make direct time-based comparisons.

Each region block contains a number describing the percentage of its runtime spent on CUDA API calls. When you right-click the block, you will see a breakdown of CUDA API function runtimes there arranged in a stack-like way (as some CUDA driver API calls are made inside CUDA runtime API functions).

Python API#

nvgpu results can be processed in Python without starting the Adaptyst Analyser web server. Read the Adaptyst Analyser Python API documentation and see the nvgpu Python API reference for more details.

In the current version of nvgpu, no windows can be exported programmatically. This will be supported in the future though, so stay tuned.

REST API#

The following module request types are supported by nvgpu via the REST API:

• Getting CUDA API tracing results in form of a summary JSON object

The subsections below indicate what fields should be provided, what the response format is, and what module-specific HTTP return codes are in each case (in addition to the standard Adaptyst Analyser HTTP return codes).

If invalid fields are provided, the HTTP return code is 400.

Getting CUDA API tracing results in form of a summary JSON object#

The only field you should provide is regions. Its value can be any non-empty text as it’s not read.

The return value is a JSON object in the following format:

{
  "<code region>": {
    "data": {
      "<CUDA API method name>": {
        "length": <exact method runtime in ns>,
        "children": <dictionary of CUDA API calls made
                     by the method: the format is the same
                     as for "data">
      }
    }
  }
}

If no CUDA API tracing data are available, the HTTP return code is 404.