Merge branch 'main' into dev

[ROCm/rocprofiler-compute commit: eec0323945]

projects/rocprofiler-compute/src/docs/analysis.md

@@ -497,7 +497,7 @@ Each workload is imported to a separate database with the following naming conve
 
 e.g., omniperf_asw_vcopy_mi200.
 
-Below is the sample command to import the *vcopy* profiling data.
+When using database mode, be sure to tailor the connection options to the machine hosting your [sever-side instance](./installation.md). Below is the sample command to import the *vcopy* profiling data, lets assuming our host machine is called "dummybox".
 
 ```shell-session
 $ omniperf database --help
@@ -545,7 +545,7 @@ Connection Options:
 
 **omniperf import for vcopy:**
 ```shell-session
-$ omniperf database --import -H pavii1 -u temp -t asw -w workloads/vcopy/mi200/
+$ omniperf database --import -H dummybox -u temp -t asw -w workloads/vcopy/mi200/
 ROC Profiler:  /usr/bin/rocprof
  
 --------

projects/rocprofiler-compute/src/docs/high_level_design.md

@@ -8,12 +8,14 @@
 
 The [Omniperf](https://github.com/AMDResearch/omniperf) Tool is architecturally composed of three major components, as shown in the following figure.
 
-- **Omniperf Profiling**: Acquire raw performance counters via application replay based on the [ROC Profiler](https://github.com/ROCm-Developer-Tools/rocprofiler).  The counters are stored in a comma-seperated value, for further analyis. A set of MI200 specific micro benchmarks are also run to acquire the hierarchical roofline data. The roofline model is not available on earlier accelerators.
+- **Omniperf Profiling**: Acquire raw performance counters via application replay based on the [rocProfiler](https://rocm.docs.amd.com/projects/rocprofiler/en/latest/rocprof.html).  The counters are stored in a comma-seperated value, for further analyis. A set of MI200 specific micro benchmarks are also run to acquire the hierarchical roofline data. The roofline model is not available on earlier accelerators.
 
 - **Omniperf Grafana Analyzer**: 
   - *Grafana database import*: All raw performance counters are imported into the backend MongoDB database for Grafana GUI analysis and visualization. Compatibility of previously generated data between Omniperf versions is not necessarily guarenteed.
   - *Grafana GUI Analyzer*: A Grafana dashboard is designed to retrieve the raw counters info from the backend database. It also creates the relevant performance metrics and visualization.
 - **Omniperf Standalone GUI Analyzer**: A standalone GUI is provided to enable performance analysis without importing data into the backend database.
 
-![Omniperf Architectual Diagram](images/omniperf_architecture.png)
+![Omniperf Architectual Diagram](images/omniperf_server_vs_client_install.png)
+
+> Note: To learn more about the client vs. server model of Omniperf and our install process please see the [Deployment section](./installation.md) of the docs.
 

projects/rocprofiler-compute/src/docs/installation.md

@@ -16,11 +16,15 @@ Omniperf is broken into two installation components:
 2. **Omniperf Server-side (_Optional_)**
    - Mongo DB backend + Grafana instance
 
+Determine what you need to install based on how you'd like to interact with Omniperf. See the decision tree below to help determine what installation is right for you.
+
+![Omniperf Installtion Decision Tree](images/install_decision_tree.png)
+
 ---
 
 ## Client-side Installation
 
-Omniperf requires the following basic software dependencies prior to usage:
+Omniperf client-side requires the following basic software dependencies prior to usage:
 
 * Python (>=3.7)
 * CMake (>= 3.19)
@@ -149,25 +153,28 @@ wishes to use instead.
 
 ## Server-side Setup
 
-Note: Server-side setup is not required to profile or analyze
-performance data from the CLI. It is provided as an additional mechanism to import performance
-data for examination within a detailed [Grafana](https://github.com/grafana/grafana) GUI.
+> Note: Server-side setup is not required to profile or analyze performance data from the CLI. It is provided as an additional mechanism to import performance data for examination within a detailed [Grafana](https://github.com/grafana/grafana) GUI.
 
-The recommended process for enabling the server-side of Omniperf is to
-use the provided Docker file to build the Grafana and MongoDB
-instance.
+Omniperf server-side requires the following basic software dependencies prior to usage:
 
-### Install MongoDB Utils
+* [Docker Engine](https://docs.docker.com/engine/install/)
+
+The recommended process for enabling the server-side of Omniperf is to use the provided Docker file to build the Grafana and MongoDB instance.
+
+Once you've decided which machine you'd like to use to host the Grafana and MongoDB instance, please follow the set up instructions below.
+
+### 1) Install MongoDB Utils
 Omniperf uses [mongoimport](https://www.mongodb.com/docs/database-tools/mongoimport/) to upload data to Grafana's backend database. Install for Ubuntu 20.04 is as follows:
+
 ```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
 ```
 > Installation instructions for alternative distributions can be found [here](https://www.mongodb.com/download-center/database-tools/releases/archive)
 
-### Persistent Storage
+### 2) Persistent Storage
 
-The user may also choose to bind MongoDB to a directory on the host OS to create a local backup in case of a crash or reset:
+The user will also bind MongoDB to a directory on the host OS to create a local backup in case of a crash or reset. In the Docker world, this is known as "creating a persistent volume":
 
 ```bash
 $ sudo mkdir -p /usr/local/persist && cd /usr/local/persist/
@@ -176,14 +183,16 @@ $ sudo docker volume create --driver local --opt type=none --opt device=/usr/loc
 $ sudo docker volume create --driver local --opt type=none --opt device=/usr/local/persist/mongodb --opt o=bind grafana-mongo-db
 ```
 
-### Build and Launch
+### 3) Build and Launch
+
+We're now ready to build our Docker file. Navigate to your Omniperf install directory to begin.
 ```bash
 $ sudo docker-compose build
 $ sudo docker-compose up -d
 ```
 > Note that TCP ports for Grafana (4000) and MongoDB (27017) in the docker container are mapped to 14000 and 27018, respectively, on the host side.
 
-### Setup Grafana Instance
+### 4) Setup Grafana Instance
 Once you've launced your docker container you should be able to reach Grafana at **http://\<host-ip>:14000**. The default login credentials for the first-time Grafana setup are:
 
 - Username: **admin**
@@ -193,26 +202,41 @@ Once you've launced your docker container you should be able to reach Grafana at
 
 MongoDB Datasource Configuration
 
-The MongoDB Datasource shall be configured prior to the first-time use. Navigate to Grafana's Configuration page (shown below) to add the **Omniperf Data** connection.
+The MongoDB Datasource must be configured prior to the first-time use. Navigate to Grafana's Configuration page (shown below) to add the **Omniperf Data** connection.
 
-![Omniperf Datasource Config](images/datasource_config.png)
+![Omniperf Datasource Config](images/datasource_config.jpg)
 
-Configure the following fields in the datasource:
+Configure the following fields in the datasource settings:
 
 - HTTP URL: set to *http://localhost:3333*
 - MongoDB URL: set to *mongodb://temp:temp123@\<host-ip>:27018/admin?authSource=admin*
 - Database Name: set to *admin*
 
-After properly configuring these fields click **Save & Test** to make sure your connection is successful.
+After properly configuring these fields click **Save & Test** (as shown below) to make sure your connection is successful.
 
 > Note to avoid potential DNS issue, one may need to use the actual IP address for the host node in the MongoDB URL.
 
-![Datasource Settings](images/datasource_settings.png)
+![Datasource Settings](images/datasource_settings.jpg)
 
 Omniperf Dashboard Import
 
-From *Create* → *Import*, (as seen below) upload the dashboard file, `/dashboards/Omniperf_v{__VERSION__}_pub.json`, from the Omniperf tarball.
+From *Create* → *Import*, (as shown below) upload the dashboard file, `/dashboards/Omniperf_v{__VERSION__}_pub.json`, from the Omniperf tarball.
 
 Edit both the Dashboard Name and the Unique Identifier (UID) to uniquely identify the dashboard he/she will use. Click Import to finish the process.
 
-![Import Dashboard](images/import_dashboard.png)
+![Import Dashboard](images/import_dashboard.png)
+
+Using your dashboard
+
+Once you've imported a dashboard you're ready to begin! Start by browsing availible dashboards and selecting the dashboard you've just imported.
+
+![Opening your dashboard](images/opening_dashboard.png)
+
+Remeber, you'll need to upload workload data to the DB backend before analyzing in your Grafana interface. We provide a detailed example of this in our [Analysis section](./analysis.md#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.
+
+![Selecting Grafana workload](images/grafana_workload_selection.png)
+
+For more information on how to use the Grafana interface for anlysis please see the [Grafana section](./analysis.md#grafana-based-gui) in the Analyze Mode tab.
+

projects/rocprofiler-compute/src/docs/introduction.md

@@ -10,7 +10,7 @@
 
 ## Scope
 
-MI Performance Profiler ([Omniperf](https://github.com/AMDResearch/omniperf)) is a system performance profiling tool for Machine Learning/HPC workloads running on AMD Instinct (tm) Accelerators. It is currently built on top of the [ROC Profiler](https://github.com/ROCm-Developer-Tools/rocprofiler) to monitor hardware performance counters. The Omniperf tool primarily targets accelerators in the MI100 and MI200 families. Development is in progress to support MI300 and Radeon (tm) RDNA (tm) GPUs.
+MI Performance Profiler ([Omniperf](https://github.com/AMDResearch/omniperf)) is a system performance profiling tool for Machine Learning/HPC workloads running on AMD Instinct (tm) Accelerators. It is currently built on top of the [rocProfiler](https://rocm.docs.amd.com/projects/rocprofiler/en/latest/rocprof.html) to monitor hardware performance counters. The Omniperf tool primarily targets accelerators in the MI100 and MI200 families. Development is in progress to support MI300 and Radeon (tm) RDNA (tm) GPUs.
 
 ## Features
 

projects/rocprofiler-compute/src/docs/profiling.md

@@ -232,20 +232,28 @@ drwxrwxr-x 2 colramos colramos  4096 Apr 11 16:42 perfmon
 ```
 
 ### Filtering
-To reduce profiling time and the counters collected one may use profiling filters.
+To reduce profiling time and the counters collected one may use profiling filters. Profiling filters and their functionality depend on the underlying profiler being used. While Omniperf is profiler agnostic, we've provided a detailed description of profiling filters available when using Omniperf with [rocProfiler](https://rocm.docs.amd.com/projects/rocprofiler/en/latest/rocprof.html) below.
+
+
 
 Filtering Options:
 
-- The `-k` \<kernel> flag allows for kernel filtering, which is compatible with the current rocprof utility.
+- The `-k` \<kernel> flag allows for kernel filtering. Useage is equivalent with the current rocprof utility (see details below).
 
-- The `-d` \<dispatch> flag allows for dispatch ID filtering,  which is compatible with the current rocprof utility. 
+- The `-d` \<dispatch> flag allows for dispatch ID filtering. Useage is equivalent with the current rocprof utility (see details below).
 
 - The `-b` \<ipblocks> allows system profiling on one or more selected IP blocks to speed up the profiling process. One can gradually incorporate more IP blocks, without overwriting performance data acquired on other IP blocks.
 
+```{note}
+Be cautious while combining different profiling filters in the same call. Conflicting filters may result in error.
+
+i.e. filtering dispatch X, but dispatch X does not match your kernel name filter
+```
+
 #### IP Block Filtering
 One can profile a selected IP Block to speed up the profiling process. All profiling results are accumulated in the same target directory, without overwriting those for other IP blocks, hence enabling the incremental profiling and analysis.
 
-The following example only profiles SQ and TCC, skipping all other IP Blocks.
+The following example only gathers hardware counters for SQ and TCC, skipping all other IP Blocks:
 ```shell
 $ omniperf profile --name vcopy -b SQ TCC -- ./sample/vcopy 1048576 256
 Resolving rocprof
@@ -283,7 +291,9 @@ Log:  /home/colramos/GitHub/omniperf-pub/workloads/vcopy/mi200/log.txt
 ```
 
 #### Kernel Filtering
-The following example demonstrates profiling on selected kernels:
+Kernel filtering is based on the name of the kernel(s) you'd like to isolate. Use a kernel name substring list to isolate desired kernels.
+
+The following example demonstrates profiling isolating the kernel matching substring "vecCopy":
 ```shell
 $ omniperf profile --name vcopy -k vecCopy -- ./vcopy 1048576 256
 Resolving rocprof
@@ -318,7 +328,9 @@ ROCProfiler: input from "/tmp/rpl_data_230411_170300_29696/input0.xml"
 ```
 
 #### Dispatch Filtering
-The following example demonstrates profiling on selected dispatches:
+Dispatch filtering is based on the *global* dispatch index of kernels in a run. 
+
+The following example profiles only the 0th dispatched kernel:
 ```shell-session
 $ omniperf profile --name vcopy -d 0 -- ./vcopy 1048576 256
 Resolving rocprof