TheRock/rocm-systems/projects/rocprofiler-compute/docs/how-to/use.rst

.. meta::
   :description: ROCm Compute Profiler basic usage
   :keywords: ROCm Compute Profiler, ROCm, profiler, tool, Instinct, accelerator, AMD,
              basics, usage, operations

***********
Basic usage
***********

The following section outlines basic ROCm Compute Profiler workflows, modes, options, and
operations.

Command line profiler
=====================

Launch and profile the target application using the command line profiler.

The command line profiler launches the target application and collects
hardware performance counter data for the specified kernels, dispatches, and
hardware components. By default, ROCm Compute Profiler collects all available
counters for all kernels and dispatches launched by the executable. Profiling
is performed using :doc:`ROCprofiler-SDK <rocprofiler-sdk:index>`; see
:ref:`core-install-rocprof-var` for details on backend selection and the
native counter collection tool.

To collect the default set of data for all kernels in the target
application, launch, for example:

.. code-block:: shell

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

This runs the app, launches each kernel, and generates profiling results. By
default, results are written to a subdirectory with your accelerator's name;
for example, ``./workloads/vcopy_data/MI200/``, where name is configurable
via the ``-n`` argument. When an MPI rank is detected, the default output
directory appends the rank (``./workloads/vcopy_data/<rank>/``) instead of
the gpu model. Use ``--output-directory`` to override the output location.

.. note::

   To collect all requested profile information, ROCm Compute Profiler might replay kernels
   multiple times.

.. _basic-filter-data-collection:

Customize data collection
-------------------------

Options are available to specify for which kernels and metrics data should be
collected. Note that you can apply filtering in either the profiling or
analysis stage. Filtering at profiling collection often speeds up your
aggregate profiling run time.

Common filters to customize data collection include:

``-k``, ``--kernel``
   Enables filtering kernels by name.

``-d``, ``--dispatch``
   Enables filtering based on dispatch iteration.

``-b``, ``--block``
   Enables collection metrics for only the specified analysis report blocks.

See :ref:`Filtering <filtering>` for an in-depth walkthrough.

To view available metrics by hardware block, use the ``--list-metrics``
option with a system architecture argument or ``--list-available-metrics``
to view the metrics for current system architecture:

.. code-block:: shell

   $ rocprof-compute --list-metrics <sys_arch>
   $ rocprof-compute profile --list-available-metrics

To view available aliases by hardware block, use the ``--list-blocks``
option with a system architecture argument

.. code-block:: shell

   $ rocprof-compute --list-blocks <sys_arch>

.. _basic-analyze-cli:

Analyze in the command line
---------------------------

After generating a local output folder (for example,
``./workloads/vcopy_data/MI200``), use the command line tool to quickly
interface with profiling results. View different metrics derived from your
profiled results and get immediate access all metrics organized by hardware
blocks.

If you don't apply kernel, dispatch, or analysis report block filters at this stage,
analysis is reflective of the entirety of the profiling data.

To interact with profiling results from a different session, provide the
workload path.

``-p``, ``--path``
   Enables you to analyze existing profiling data in the ROCm Compute Profiler CLI.

See :doc:`analyze/cli` for more detailed information.

.. _modes:

Modes
=====

Modes change the fundamental behavior of the ROCm Compute Profiler command line tool.
Depending on which mode you choose, different command line options become
available.

.. _modes-profile:

Profile mode
------------

``profile``
   Launches the target application on the local system using
   :doc:`ROCprofiler-SDK <rocprofiler-sdk:index>`. Depending on the profiling options
   chosen, selected kernels, dispatches, and or hardware components used by the
   application are profiled. It stores results locally in an output folder:
   ``./workloads/\<name>`` (or rank-specific subdirectories when using MPI).

   .. code-block:: shell

      $ rocprof-compute profile --help

See :doc:`profile/mode` to learn about this mode in depth and to get started
profiling with ROCm Compute Profiler.

.. _modes-analyze:

Analyze mode
------------

``analyze``
   Loads profiling data from the ``--path`` (``-p``) directory into the ROCm Compute Profiler
   CLI analyzer where you have immediate access to profiling results and
   generated metrics. It generates metrics from the entirety of your profiled
   application or a subset identified through the ROCm Compute Profiler CLI analysis filters.

   To generate a lightweight GUI interface, you can add the ``--experimental --gui`` flags to your
   analysis command.

   .. code-block:: shell

      $ rocprof-compute analyze --help

   Analyze mode now supports a lightweight Text-based User Interface (TUI) that
   provides an interactive terminal experience for enhanced usability. To enable TUI mode,
   use the ``--experimental --tui`` flags when running the analyze command:

   .. code-block:: shell

      $ rocprof-compute analyze --experimental --tui

See :doc:`analyze/mode` to learn about these modes in depth and to get started
with analysis using ROCm Compute Profiler.

.. _global-options:

Global options
==============

The ROCm Compute Profiler command line tool has a set of *global* utility options that are
available across all modes.

``-v``, ``--version``
   Prints the ROCm Compute Profiler version and exits.

``-V``, ``--verbose``
   Increases output verbosity. Use multiple times for higher levels of
   verbosity.

``-q``, ``--quiet``
   Reduces output verbosity and runs quietly.

``-s``, ``--specs``
   Prints system specs and exits.

.. note::

   ROCm Compute Profiler also recognizes the project variable, ``ROCPROFCOMPUTE_COLOR`` should you
   choose to disable colorful output. To disable default colorful behavior, set
   this variable to ``0``.

.. _basic-operations:

Basic operations
================

The following table lists ROCm Compute Profiler's basic operations, their
:ref:`modes <modes>`, and required arguments.

.. list-table::
   :header-rows: 1

   * - Operation description
     - Mode
     - Required arguments

   * - :doc:`Profile a workload </how-to/profile/mode>`
     - ``profile``
     - ``--name`` or ``--output-directory``, ``-- <profile_cmd>``

   * - :ref:`Standalone roofline analysis <standalone-roofline>`
     - ``profile``
     - ``--name`` or ``--output-directory``, ``--roof-only``, ``--roofline-data-type <data_type>``, ``-- <profile_cmd>``

   * - :doc:`Launch standalone GUI from CLI </how-to/analyze/standalone-gui>`
     - ``analyze``
     - ``--path``, ``--experimental``, ``--gui``

   * - :doc:`Interact with profiling results from CLI </how-to/analyze/cli>`
     - ``analyze``
     - ``--path``