Quickstart

Quickstart#

This guide provides instructions for getting started and using ROCm Compute Profiler. It covers the steps required to profile GPU workloads and analyze performance data to identify bottlenecks and optimize applications.

There are two main phases to use the tool:

Profiling
Analysis

Prerequisites#

Ensure ROCm is installed and follow the steps:

Check the GPU and driver.

amd-smi          # Monitor GPU health, temperature, utilization
rocminfo         # Display ROCm platform and GPU properties

If these commands fail:

Verify that the GPU driver is loaded:

lsmod | grep amdgpu

Load the driver if needed:

sudo modprobe amdgpu

Verify that the device nodes exist:

ls /dev/kfd /dev/dri

Ensure that the user name is added to the render and video groups:

sudo usermod -aG render,video $USER
# Log out and back in for changes to take effect

If rocminfo or amd-smi commands are not found, set ROCm environment:

export PATH=/opt/rocm/bin:$PATH
export LD_LIBRARY_PATH=/opt/rocm/lib:${LD_LIBRARY_PATH}

Check the Python environment.
```
python3 --version
```
The required Python version depends on which mode you use:

Python version support#

Component

Supported Python versions

Profile mode (standard library only)

3.8 through 3.14

Analyze mode (numpy, pandas, dash, textual, etc.)

3.9 through 3.14

Analyze mode aborts with a clear message if launched on Python older than 3.9.
Install the analyze mode dependencies. Profile mode uses the standard library and needs no extra packages, so this step is only for analyze mode.

Install them into a virtual environment that is separate from the one your profiled application uses. Analyze mode pins versions of packages such as numpy and pandas, and installing them alongside a workload that has its own versions of torch, numpy, or similar packages can break either side.
```
python3 -m venv ~/.venvs/rocprof-compute-analyze
source ~/.venvs/rocprof-compute-analyze/bin/activate
pip install --extra-index-url https://<stable/nightly>.repo.amd.com/rocm/whl-next/ "rocm-profiler[compute-analyze]"
```
To check that the environment has everything analyze mode needs, run rocprof-compute analyze --verify-deps.

Profile your application with its own Python environment, then activate this environment to run analyze mode on the results. For the packaged ROCm installation and other ways to install these dependencies, see Install the analyze mode dependencies.

For detailed installation instructions, refer to Install ROCm Compute Profiler.

Profiling#

Profiling is the process of collecting performance counters from a GPU application during execution. ROCm Compute Profiler captures detailed metrics regarding kernel execution, memory usage, roofline analysis, and hardware utilization to facilitate performance understanding and optimization.

The following examples reference sample applications located in the samples folder of the GitHub repository: ROCm/rocm-systems

Compile HIP sample:: Build the HIP sample into an executable named ‘vcopy’

hipcc vcopy.cpp -o vcopy

Profile Command:

rocprof-compute profile --name <workload_name> [profile options] [roofline options] -- <workload_cmd>

Example:

rocprof-compute profile --name vcopy -- ./vcopy -n 1048576 -b 256

Explanation:

rocprof-compute profile: Starts a profiling session for a compute workload.
--name vcopy: Labels this run as ‘vcopy’ for easy identification and comparison.
--: Separates rocprof-compute options from the application arguments.
./vcopy -n 1048576 -b 256: Executes the application with the following parameters:
- -n 1048576: Number of elements.
- -b 256: Block size (threads per block).

What happens during profiling?#

The application runs multiple times to collect all required performance counters; it executes multiple times during profiling. Roofline analysis runs automatically unless you disable it using --no-roof.

After profiling, the generated files can be found inside:

workloads/vcopy/MI200/

For detailed information on all profiling options, refer to Profile mode.

During the profiling phase, roofline microbenchmarks also run to collect hardware peak data (saved as roofline.csv). To generate roofline HTML charts from this data, run rocprof-compute analyze on the output directory. For detailed information on roofline analysis, refer to Standalone roofline.

For more details and options, run:

rocprof-compute profile --help

Profiling examples#

Common use cases when profiling a workload are:

Collect roofline data and generate HTML charts#

Profile mode collects roofline microbenchmark data (roofline.csv). To generate interactive HTML roofline charts, run analyze mode on the output:

$ rocprof-compute profile --name vcopy --roof-only -- ./vcopy -n 1048576 -b 256
$ rocprof-compute analyze -p workloads/vcopy/MI200/ --roofline-data-type FP32

Collect the counters to compute the metric for compute throughput utilization, skipping roofline#

$ rocprof-compute profile --name vcopy --set compute_thruput_util --no-roof -- ./vcopy -n 1048576 -b 256

List the available blocks/metrics for profiling#

The blocks/metrics are listed by page, because the list is long. Note the index for each section.

$ rocprof-compute profile --list-available-metrics | more

Using block 2 for system speed-of-light profiling#

$ rocprof-compute profile --name vcopy -b 2 -- ./vcopy -n 1048576 -b 256

Attach to a running process for live profiling#

Dynamic process attachment can be performed with specific block IDs, verbose output, and no roofline data.

$ rocprof-compute profile -n try_live_attach_detach -b 3.1.1 4.1.1 5.1.1 --no-roof -VVV --attach-pid <process id>

Use multiple blocks (5 and 7) for detailed metric collection#

$ rocprof-compute profile --name vcopy -b 5 7 -- ./vcopy -n 1048576 -b 256

Analysis#

Analysis phase refers to the process of examining profiling data to understand GPU kernel performance, identify bottlenecks, and determine optimization opportunities. Multiple analysis options are available to accommodate different workflows.

Analysis option	When to Use
CLI (Command Line Interface)	Fast, scriptable insights; great for automation and quick checks.
GUI (Standalone Graphical Interface)	Interactive exploration, visual drill-down, and detailed charts.
TUI (Textual User Interface)	Lightweight, keyboard-driven experience for terminals.
ROCm Optiq	Interactive graphical exploration of generated ROCm Compute Profiler analysis databases.

Analysis Command:

rocprof-compute analyze -p <workloads_directory>