diff --git a/src/docs/analysis.md b/src/docs/analysis.md index 9feff1f64b..af0234786c 100644 --- a/src/docs/analysis.md +++ b/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 -------- diff --git a/src/docs/high_level_design.md b/src/docs/high_level_design.md index 7466e0c04f..fbe33ca3b8 100644 --- a/src/docs/high_level_design.md +++ b/src/docs/high_level_design.md @@ -15,5 +15,7 @@ The [Omniperf](https://github.com/AMDResearch/omniperf) Tool is architecturally - *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. diff --git a/src/docs/images/datasource_config.jpg b/src/docs/images/datasource_config.jpg new file mode 100644 index 0000000000..4210d9036b Binary files /dev/null and b/src/docs/images/datasource_config.jpg differ diff --git a/src/docs/images/datasource_config.png b/src/docs/images/datasource_config.png deleted file mode 100644 index 8e22ef7379..0000000000 Binary files a/src/docs/images/datasource_config.png and /dev/null differ diff --git a/src/docs/images/datasource_settings.jpg b/src/docs/images/datasource_settings.jpg new file mode 100644 index 0000000000..f472362544 Binary files /dev/null and b/src/docs/images/datasource_settings.jpg differ diff --git a/src/docs/images/datasource_settings.png b/src/docs/images/datasource_settings.png deleted file mode 100644 index 04cf1e54d1..0000000000 Binary files a/src/docs/images/datasource_settings.png and /dev/null differ diff --git a/src/docs/images/grafana_workload_selection.png b/src/docs/images/grafana_workload_selection.png new file mode 100644 index 0000000000..3ecdc35e72 Binary files /dev/null and b/src/docs/images/grafana_workload_selection.png differ diff --git a/src/docs/images/install_decision_tree.png b/src/docs/images/install_decision_tree.png new file mode 100644 index 0000000000..1c62fba87b Binary files /dev/null and b/src/docs/images/install_decision_tree.png differ diff --git a/src/docs/images/omniperf_server_vs_client_install.png b/src/docs/images/omniperf_server_vs_client_install.png new file mode 100644 index 0000000000..8c43dba9e2 Binary files /dev/null and b/src/docs/images/omniperf_server_vs_client_install.png differ diff --git a/src/docs/images/opening_dashboard.png b/src/docs/images/opening_dashboard.png new file mode 100644 index 0000000000..5e6c7ea625 Binary files /dev/null and b/src/docs/images/opening_dashboard.png differ diff --git a/src/docs/installation.md b/src/docs/installation.md index e550669b7e..0efee867e5 100644 --- a/src/docs/installation.md +++ b/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://\: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@\: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) \ No newline at end of file +![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. +