-
Notifications
You must be signed in to change notification settings - Fork 49
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Signed-off-by: Peter Jun Park <peter.park@amd.com>
- Loading branch information
1 parent
32ebe6e
commit 95351a4
Showing
15 changed files
with
404 additions
and
200 deletions.
There are no files selected for viewing
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Empty file.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,191 @@ | ||
.. meta:: | ||
:description: Omniperf installation and deployment | ||
:keywords: Omniperf, ROCm, profiler, tool, Instinct, accelerator, AMD, | ||
install, deploy, Grafana, client, configuration, modulefiles | ||
|
||
********************************* | ||
Installing and deploying Omniperf | ||
********************************* | ||
|
||
Omniperf consists of two installation components. | ||
|
||
* :ref:`Omniperf core installation <core-install>` | ||
|
||
* 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 Omniperf <grafana-setup>` (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 | ||
Omniperf. 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 Omniperf | ||
|
||
.. _core-install: | ||
|
||
Core installation | ||
================= | ||
|
||
The core Omniperf application requires the following basic software | ||
dependencies. | ||
|
||
* Python ``>= 3.8`` | ||
* CMake ``>= 3.19`` | ||
* ROCm ``>= 5.7.1`` | ||
|
||
Omniperf depends on a number of Python packages documented in the top-level | ||
``requirements.txt`` file. Install these *before* configuring Omniperf. | ||
|
||
.. admonition:: Optional packages for developers | ||
|
||
For those looking to build Omniperf as a developer, consider these additional | ||
requirements. | ||
|
||
.. list-table:: | ||
:header-rows: 1 | ||
|
||
* - Requirements file | ||
- Description | ||
|
||
* - ``docs/sphinx/requirements.txt`` | ||
- Python packages required to build this documentation from source. | ||
|
||
* - ``requirements-test.txt`` | ||
- Python packages required to run Omniperf's CI suite using PyTest. | ||
|
||
The recommended procedure for Omniperf 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 Omniperf into a | ||
shared location controlled by the ``INSTALL_DIR`` environment variable. | ||
|
||
.. _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 Omniperf files. | ||
|
||
* - ``PYTHON_DEPS`` | ||
- Specifies an optional path to resolve Python package dependencies. | ||
|
||
* - ``MOD_INSTALL_PATH`` | ||
- Specifies an optional path for separate Omniperf modulefile installation. | ||
|
||
.. _core-install-steps: | ||
|
||
Installation steps | ||
------------------ | ||
|
||
#. A typical install begins by downloading the latest release tarball available | ||
from `<https://github.com/ROCm/omniperf/releases>`__. From there, untar and | ||
navigate into the top-level directory. | ||
|
||
.. code-block:: shell | ||
tar xfz omniperf-v{__VERSION__}.tar.gz | ||
cd omniperf-v{__VERSION__} | ||
#. Next, install Python dependencies and complete the Omniperf configuration and | ||
install process. | ||
|
||
.. 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 Omniperf for shared install | ||
mkdir build | ||
cd build | ||
cmake -DCMAKE_INSTALL_PREFIX=${INSTALL_DIR}/{__VERSION__} \ | ||
-DPYTHON_DEPS=${INSTALL_DIR}/python-libs \ | ||
-DMOD_INSTALL_PATH=${INSTALL_DIR}/modulefiles .. | ||
# 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. | ||
|
||
.. code-block:: shell | ||
$ ls $INSTALL_DIR | ||
modulefiles {__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 Omniperf modulefile directory and setup your environment | ||
for execution of Omniperf as follows. | ||
|
||
.. code-block:: shell | ||
$ module use $INSTALL_DIR/modulefiles | ||
$ module load omniperf | ||
$ which omniperf | ||
/opt/apps/omniperf/{__VERSION__}/bin/omniperf | ||
$ omniperf --version | ||
ROC Profiler: /opt/rocm-5.1.0/bin/rocprof | ||
omniperf (v{__VERSION__}) | ||
.. tip:: | ||
|
||
If you're relying on an Lmod Python module locally, you may wish to customize | ||
the resulting Omniperf modulefile post-installation to include extra | ||
module dependencies. | ||
|
||
Execution without modulefiles | ||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | ||
|
||
To use Omniperf 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. | ||
|
||
.. code-block:: shell | ||
export PATH=$INSTALL_DIR/{__VERSION__}/bin:$PATH | ||
export PYTHONPATH=$INSTALL_DIR/python-libs | ||
.. _core-install-rocprof-var: | ||
|
||
ROCProfiler | ||
----------- | ||
|
||
Omniperf relies on ROCProfiler'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. | ||
|
Oops, something went wrong.