xuchen-amd
b774f28181
* Remove grafana and mongodb integration * Remove grafana documentation assets * clarify changelog --------- Co-authored-by: Vignesh Edithal <Vignesh.Edithal@amd.com>
216 baris
6.5 KiB
ReStructuredText
216 baris
6.5 KiB
ReStructuredText
.. 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, calls the
|
|
ROCProfiler API via the ``rocprof`` binary, and collects profile results for
|
|
the specified kernels, dispatches, and hardware components. If not
|
|
specified, ROCm Compute Profiler defaults to collecting all available counters for all
|
|
kernels and dispatches launched by the your executable.
|
|
|
|
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.
|
|
|
|
.. 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 ID.
|
|
|
|
``-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 <rocprofiler: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>``.
|
|
|
|
.. 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 ``--gui`` flag 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 ``--tui`` flag when running the analyze command:
|
|
|
|
.. code-block:: shell
|
|
|
|
$ rocprof-compute analyze --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``, ``-- <profile_cmd>``
|
|
|
|
* - :ref:`Standalone roofline analysis <standalone-roofline>`
|
|
- ``profile``
|
|
- ``--name``, ``--roof-only``, ``--roofline-data-type <data_type>``, ``-- <profile_cmd>``
|
|
|
|
* - :doc:`Launch standalone GUI from CLI </how-to/analyze/standalone-gui>`
|
|
- ``analyze``
|
|
- ``--path``, ``--gui``
|
|
|
|
* - :doc:`Interact with profiling results from CLI </how-to/analyze/cli>`
|
|
- ``analyze``
|
|
- ``--path``
|