Add 'projects/rocprofiler-compute/' from commit 'd2cec001161fc49761bd71a498474a447b1d6975'
git-subtree-dir: projects/rocprofiler-compute git-subtree-mainline:8a4d7262f8git-subtree-split:d2cec00116
This commit is contained in:
systems-assistant[bot]
@@ -0,0 +1,260 @@
|
||||
.. meta::
|
||||
:description: ROCm Compute Profiler installation and deployment
|
||||
:keywords: Omniperf, ROCm Compute Profiler, ROCm, tool, Instinct, accelerator, AMD,
|
||||
install, deploy, Grafana, client, configuration, modulefiles
|
||||
|
||||
**********************************************
|
||||
Installing and deploying ROCm Compute Profiler
|
||||
**********************************************
|
||||
|
||||
ROCm Compute Profiler consists of two installation components.
|
||||
|
||||
* :ref:`ROCm Compute Profiler core installation <core-install>` (client-side)
|
||||
|
||||
* Provides the core application profiling capability.
|
||||
* Allows the collection of performance counters, filtering by hardware
|
||||
block, dispatch, kernel, and more.
|
||||
* Provides a CLI-based analysis mode.
|
||||
* Provides a standalone web interface for importing analysis metrics.
|
||||
|
||||
* :doc:`Grafana server for ROCm Compute Profiler <grafana-setup>` (server-side) (*optional*)
|
||||
|
||||
* Hosts the MongoDB backend and Grafana instance.
|
||||
* Is packaged in a Docker container for easy setup.
|
||||
|
||||
Determine what you need to install based on how you would like to interact with
|
||||
ROCm Compute Profiler. See the following decision tree to help determine what installation is
|
||||
right for you.
|
||||
|
||||
.. image:: ../data/install/install-decision-tree.png
|
||||
:align: center
|
||||
:alt: Decision tree for installing and deploying ROCm Compute Profiler
|
||||
:width: 800
|
||||
|
||||
.. _core-install:
|
||||
|
||||
Core installation
|
||||
=================
|
||||
|
||||
The core ROCm Compute Profiler application requires the following basic software
|
||||
dependencies. As of ROCm 6.2, the core ROCm Compute Profiler is included with your ROCm
|
||||
installation.
|
||||
|
||||
* Python ``>= 3.8``
|
||||
* CMake ``>= 3.19``
|
||||
* ROCm ``>= 5.7.1``
|
||||
|
||||
.. note::
|
||||
|
||||
ROCm Compute Profiler will use the first version of ``python3`` found in your system's
|
||||
``PATH``. If the default version of Python is older than 3.8, you may need to
|
||||
update your system's ``PATH`` to point to a newer version.
|
||||
|
||||
ROCm Compute Profiler depends on a number of Python packages documented in the top-level
|
||||
``requirements.txt`` file. Install these *before* configuring ROCm Compute Profiler.
|
||||
|
||||
.. tip::
|
||||
|
||||
If looking to build ROCm Compute Profiler as a developer, consider these additional
|
||||
requirements.
|
||||
|
||||
.. list-table::
|
||||
|
||||
* - ``docs/sphinx/requirements.txt``
|
||||
- Python packages required to build this documentation from source.
|
||||
|
||||
* - ``requirements-test.txt``
|
||||
- Python packages required to run ROCm Compute Profiler's CI suite using PyTest.
|
||||
|
||||
The recommended procedure for ROCm Compute Profiler usage is to install into a shared file
|
||||
system so that multiple users can access the final installation. The
|
||||
following steps illustrate how to install the necessary Python dependencies
|
||||
using `pip <https://packaging.python.org/en/latest/>`_ and ROCm Compute Profiler into a
|
||||
shared location controlled by the ``INSTALL_DIR`` environment variable.
|
||||
|
||||
.. tip::
|
||||
|
||||
To always run ROCm Compute Profiler with a particular version of Python, you can create a
|
||||
bash alias. For example, to run ROCm Compute Profiler with Python 3.10, you can run the
|
||||
following command:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
alias rocprof-compute-mypython="/usr/bin/python3.10 /opt/rocm/bin/rocprof-compute"
|
||||
|
||||
.. _core-install-cmake-vars:
|
||||
|
||||
Configuration variables
|
||||
-----------------------
|
||||
The following installation example leverages several
|
||||
`CMake <https://cmake.org/cmake/help/latest>`_ project variables defined as
|
||||
follows.
|
||||
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
|
||||
* - CMake variable
|
||||
- Description
|
||||
|
||||
* - ``CMAKE_INSTALL_PREFIX``
|
||||
- Controls the install path for ROCm Compute Profiler files.
|
||||
|
||||
* - ``PYTHON_DEPS``
|
||||
- Specifies an optional path to resolve Python package dependencies.
|
||||
|
||||
* - ``MOD_INSTALL_PATH``
|
||||
- Specifies an optional path for separate ROCm Compute Profiler modulefile installation.
|
||||
|
||||
.. _core-install-steps:
|
||||
|
||||
Install from source
|
||||
-------------------
|
||||
|
||||
#. A typical install begins by downloading the latest release tarball available
|
||||
from `<https://github.com/ROCm/rocprofiler-compute/releases>`__. From there, untar and
|
||||
navigate into the top-level directory.
|
||||
|
||||
..
|
||||
{{ config.version }} substitutes the ROCm Compute Profiler version in ../conf.py
|
||||
|
||||
.. datatemplate:nodata::
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
tar xfz rocprofiler-compute-v{{ config.version }}.tar.gz
|
||||
cd rocprofiler-compute-v{{ config.version }}
|
||||
|
||||
#. Next, install Python dependencies and complete the ROCm Compute Profiler configuration and
|
||||
install process.
|
||||
|
||||
.. datatemplate:nodata::
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
# define top-level install path
|
||||
export INSTALL_DIR=<your-top-level-desired-install-path>
|
||||
|
||||
# install python deps
|
||||
python3 -m pip install -t ${INSTALL_DIR}/python-libs -r requirements.txt
|
||||
|
||||
# configure ROCm Compute Profiler for shared install
|
||||
mkdir build
|
||||
cd build
|
||||
cmake -DCMAKE_INSTALL_PREFIX=${INSTALL_DIR}/{{ config.version }} \
|
||||
-DPYTHON_DEPS=${INSTALL_DIR}/python-libs \
|
||||
-DMOD_INSTALL_PATH=${INSTALL_DIR}/modulefiles/rocprofiler-compute ..
|
||||
|
||||
# install
|
||||
make install
|
||||
|
||||
.. tip::
|
||||
|
||||
You might need to ``sudo`` the final installation step if you don't have
|
||||
write access for the chosen installation path.
|
||||
|
||||
#. Upon successful installation, your top-level installation directory should
|
||||
look like this.
|
||||
|
||||
.. datatemplate:nodata::
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
$ ls $INSTALL_DIR
|
||||
modulefiles {{ config.version }} python-libs
|
||||
|
||||
.. _core-install-modulefiles:
|
||||
|
||||
Execution using modulefiles
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The installation process includes the creation of an environment modulefile for
|
||||
use with `Lmod <https://lmod.readthedocs.io>`_. On systems that support Lmod,
|
||||
you can register the ROCm Compute Profiler modulefile directory and setup your environment
|
||||
for execution of ROCm Compute Profiler as follows.
|
||||
|
||||
.. datatemplate:nodata::
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
$ module use $INSTALL_DIR/modulefiles
|
||||
$ module load rocprofiler-compute
|
||||
$ which rocprof-compute
|
||||
/opt/apps/rocprofiler-compute/{{ config.version }}/bin/rocprof-compute
|
||||
|
||||
$ rocprof-compute --version
|
||||
ROC Profiler: /opt/rocm-5.1.0/bin/rocprof
|
||||
|
||||
rocprofiler-compute (v{{ config.version }})
|
||||
|
||||
.. tip::
|
||||
|
||||
If you're relying on an Lmod Python module locally, you may wish to customize
|
||||
the resulting ROCm Compute Profiler modulefile post-installation to include extra
|
||||
module dependencies.
|
||||
|
||||
Execution without modulefiles
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
To use ROCm Compute Profiler without the companion modulefile, update your ``PATH``
|
||||
settings to enable access to the command line binary. If you installed Python
|
||||
dependencies in a shared location, also update your ``PYTHONPATH``
|
||||
configuration.
|
||||
|
||||
.. datatemplate:nodata::
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
export PATH=$INSTALL_DIR/{{ config.version }}/bin:$PATH
|
||||
export PYTHONPATH=$INSTALL_DIR/python-libs
|
||||
|
||||
.. _core-install-package:
|
||||
|
||||
Install via package manager
|
||||
---------------------------
|
||||
|
||||
Once ROCm (minimum version 6.2.0) is installed, you can install ROCm Compute Profiler using
|
||||
your operating system's native package manager using the following commands.
|
||||
See :doc:`rocm-install-on-linux:index` for guidance on installing the ROCm
|
||||
software stack.
|
||||
|
||||
.. tab-set::
|
||||
|
||||
.. tab-item:: Ubuntu
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
$ sudo apt install rocprofiler-compute
|
||||
# Include rocprofiler-compute in your system PATH
|
||||
$ sudo update-alternatives --install /usr/bin/rocprof-compute rocprof-compute /opt/rocm/bin/rocprof-compute 0
|
||||
# Install Python dependencies
|
||||
$ python3 -m pip install -r /opt/rocm/libexec/rocprofiler-compute/requirements.txt
|
||||
|
||||
.. tab-item:: Red Hat Enterprise Linux
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
$ sudo dnf install rocprofiler-compute
|
||||
# Include rocprofiler-compute in your system PATH
|
||||
$ sudo update-alternatives --install /usr/bin/rocprof-compute rocprof-compute /opt/rocm/bin/rocprof-compute 0
|
||||
# Install Python dependencies
|
||||
$ python3 -m pip install -r /opt/rocm/libexec/rocprofiler-compute/requirements.txt
|
||||
|
||||
.. tab-item:: SUSE Linux Enterprise Server
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
$ sudo zypper install rocprofiler-compute
|
||||
# Include rocprofiler-compute in your system PATH
|
||||
$ sudo update-alternatives --install /usr/bin/rocprof-compute rocprof-compute /opt/rocm/bin/rocprof-compute 0
|
||||
# Install Python dependencies
|
||||
$ python3 -m pip install -r /opt/rocm/libexec/rocprofiler-compute/requirements.txt
|
||||
|
||||
.. _core-install-rocprof-var:
|
||||
|
||||
ROCProfiler
|
||||
-----------
|
||||
|
||||
ROCm Compute Profiler relies on :doc:`ROCProfiler <rocprofiler:index>`'s ``rocprof`` binary
|
||||
during the profiling process. Normally, the path to this binary is detected
|
||||
automatically, but you can override the path by the setting the optional
|
||||
``ROCPROF`` environment variable.
|
||||
@@ -0,0 +1,219 @@
|
||||
.. meta::
|
||||
:description: ROCm Compute Profiler Grafana server installation and deployment
|
||||
:keywords: ROCm Compute Profiler, ROCm, profiler, tool, Instinct, accelerator, AMD,
|
||||
install, deploy, Grafana, server, configuration, GUI
|
||||
|
||||
***************************************************
|
||||
Setting up Grafana server for ROCm Compute Profiler
|
||||
***************************************************
|
||||
|
||||
.. warning::
|
||||
|
||||
Grafana and MongoDB functionality is deprecated and will be removed in a future release.
|
||||
|
||||
A Grafana server is *not required* to profile or analyze performance data
|
||||
from the CLI. It's a supplementary mechanism to help you import performance
|
||||
data and examine it in a detailed
|
||||
`Grafana <https://github.com/grafana/grafana>`_ dashboard GUI.
|
||||
|
||||
Learn about installing and configuring the main ROCm Compute Profiler tool in
|
||||
:ref:`core-install`.
|
||||
|
||||
Setting up a Grafana instance for ROCm Compute Profiler requires the following basic software
|
||||
dependencies.
|
||||
|
||||
* `Docker Engine <https://docs.docker.com/engine/install/>`_
|
||||
|
||||
The recommended process for enabling the server-side of ROCm Compute Profiler is to use the
|
||||
provided ``Dockerfile`` to build the Grafana and MongoDB instance.
|
||||
|
||||
.. _grafana-mongodb-setup:
|
||||
|
||||
Set up Grafana and MongoDB
|
||||
==========================
|
||||
|
||||
Once you've decided where to host the Grafana and MongoDB instance, complete the
|
||||
the following setup instructions.
|
||||
|
||||
Install MongoDB utilities
|
||||
-------------------------
|
||||
|
||||
ROCm Compute Profiler uses the
|
||||
`mongoimport <https://www.mongodb.com/docs/database-tools/mongoimport/>`_
|
||||
utility to upload data to your Grafana instance's backend database.
|
||||
|
||||
Use the following commands to install MongoDB utilities for Ubuntu 20.04.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ wget https://fastdl.mongodb.org/tools/db/mongodb-database-tools-ubuntu2004-x86_64-100.6.1.deb
|
||||
$ sudo apt install ./mongodb-database-tools-ubuntu2004-x86_64-100.6.1.deb
|
||||
|
||||
.. note::
|
||||
|
||||
Find installation instructions for other distributions in
|
||||
`MongoDB Database Tools Downloads <https://www.mongodb.com/download-center/database-tools/releases/archive>`_.
|
||||
|
||||
.. _grafana-persistent-storage-setup:
|
||||
|
||||
Set up persistent storage
|
||||
-------------------------
|
||||
|
||||
Bind MongoDB to a directory on the host OS to create a local backup in case of a
|
||||
crash or reset. This is called *creating a persistent volume*.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ sudo mkdir -p /usr/local/persist && cd /usr/local/persist/
|
||||
$ sudo mkdir -p grafana-storage mongodb
|
||||
$ sudo docker volume create --driver local --opt type=none --opt device=/usr/local/persist/grafana-storage --opt o=bind grafana-storage
|
||||
$ sudo docker volume create --driver local --opt type=none --opt device=/usr/local/persist/mongodb --opt o=bind grafana-mongo-db
|
||||
|
||||
.. _grafana-docker-container:
|
||||
|
||||
Build and launch the Docker container
|
||||
-------------------------------------
|
||||
|
||||
You're now ready to build your ``Dockerfile``. Navigate to your ROCm Compute Profiler install
|
||||
directory to begin.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ cd grafana
|
||||
$ sudo docker-compose build
|
||||
$ sudo docker-compose up -d
|
||||
|
||||
.. note::
|
||||
|
||||
To troubleshoot Docker container build failures related to certificate verification, try
|
||||
disabling any network proxy services on the host system. These proxy services can interfere
|
||||
with OpenSSL's ability to retrieve a correct certificate chain when the container accesses
|
||||
external websites.
|
||||
|
||||
The TCP ports for Grafana (``4000``) and MongoDB (``27017``) in the Docker
|
||||
container are mapped to ``14000`` and ``27018``, respectively, on the host side.
|
||||
|
||||
.. tip::
|
||||
|
||||
In the event that either your Grafana or MongoDB instance crashes fatally,
|
||||
just restart the server. Navigate to your install directory and run:
|
||||
|
||||
.. code-block::
|
||||
|
||||
$ sudo docker-compose down
|
||||
$ sudo docker-compose up -d
|
||||
|
||||
.. _grafana-dashboard-setup:
|
||||
|
||||
Set up the Grafana dashboard
|
||||
----------------------------
|
||||
|
||||
Once you've launched your Docker container you should be able to reach Grafana
|
||||
at ``http://<host-ip>:14000``. The default login credentials for your first-time
|
||||
Grafana setup are:
|
||||
|
||||
* **Username**: ``admin``
|
||||
* **Password**: ``admin``
|
||||
|
||||
.. figure:: ../data/install/grafana_welcome.png
|
||||
:align: center
|
||||
:alt: Grafana dashboard welcome screen
|
||||
:width: 800
|
||||
|
||||
Grafana's welcome screen.
|
||||
|
||||
.. _grafana-datasource-setup:
|
||||
|
||||
Configure the MongoDB data source
|
||||
---------------------------------
|
||||
|
||||
You must configure your MongoDB data source in Grafana before first-time use.
|
||||
Navigate to Grafana's **Configuration** page to add the "Omniperf Data"
|
||||
connection.
|
||||
|
||||
.. figure:: ../data/install/datasource_config.jpg
|
||||
:align: center
|
||||
:alt: Grafana data source configuration
|
||||
:width: 800
|
||||
|
||||
Grafana's Configuration page.
|
||||
|
||||
Configure the following fields in the data source settings.
|
||||
|
||||
.. list-table::
|
||||
:stub-columns: 1
|
||||
|
||||
* - HTTP URL
|
||||
- ``http://localhost:3333``
|
||||
|
||||
* - MongoDB URL
|
||||
- ``mongodb://temp:temp123@\<host-ip>:27018/admin?authSource=admin``
|
||||
|
||||
* - Database Name
|
||||
- ``admin``
|
||||
|
||||
After configuring these fields, click **Save & test** to make sure your
|
||||
connection is successful.
|
||||
|
||||
.. figure:: ../data/install/datasource_settings.jpg
|
||||
:align: center
|
||||
:alt: Grafana data source settings
|
||||
:width: 800
|
||||
|
||||
Grafana data source settings.
|
||||
|
||||
.. note::
|
||||
|
||||
To avoid potential DNS issues, you might need to use the actual IP address
|
||||
for the host node in the MongoDB URL.
|
||||
|
||||
.. _grafana-import-dashboard-file:
|
||||
|
||||
Import the ROCm Compute Profiler dashboard file
|
||||
-----------------------------------------------
|
||||
|
||||
From the **Create** → **Import** page, upload the dashboard file,
|
||||
``/dashboards/Omniperf_v{__VERSION__}_pub.json`` from the
|
||||
:doc:`ROCm Compute Profiler tarball <core-install>`.
|
||||
|
||||
Edit both the dashboard **Name** and the **Unique identifier (UID)** fields to
|
||||
uniquely identify the dashboard. Click **Import** to complete the process.
|
||||
|
||||
.. figure:: ../data/install/import_dashboard.png
|
||||
:align: center
|
||||
:alt: Grafana's import dashboard
|
||||
:width: 800
|
||||
|
||||
Grafana's Import dashboard.
|
||||
|
||||
.. _grafana-select-workload:
|
||||
|
||||
Select and load the ROCm Compute Profiler workload
|
||||
--------------------------------------------------
|
||||
|
||||
Once you have imported a dashboard you're ready to begin. Start by browsing
|
||||
available dashboards and selecting the dashboard you have just imported.
|
||||
|
||||
.. figure:: ../data/install/opening_dashboard.png
|
||||
:align: center
|
||||
:alt: Opening your ROCm Compute Profiler dashboard in Grafana
|
||||
:width: 800
|
||||
|
||||
Opening your ROCm Compute Profiler profiling dashboard in Grafana.
|
||||
|
||||
Remember that you need to upload workload data to the MongoDB backend before
|
||||
analyzing in your Grafana interface. See a detailed example of this in
|
||||
:ref:`grafana-gui-import`.
|
||||
|
||||
After a workload has been successfully uploaded, you should be able to select it
|
||||
from the workload dropdown located at the top of your Grafana dashboard.
|
||||
|
||||
.. figure:: ../data/install/grafana_workload_selection.png
|
||||
:align: center
|
||||
:alt: ROCm Compute Profiler workload selection in Grafana
|
||||
:width: 800
|
||||
|
||||
Selecting your ROCm Compute Profiler workload in Grafana.
|
||||
|
||||
For more information on how to use the Grafana interface for analysis see
|
||||
:doc:`/how-to/analyze/grafana-gui`.
|
||||
Reference in New Issue
Block a user