Added VTune on IDC setup (#2001)

Author: krisrak

DirectProgramming/C++SYCL/Jupyter/oneapi-essentials-training/06_Intel_VTune_Profiler/Intel_VTune_Profiler.ipynb

@@ -4,7 +4,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# VTune™ Profiling on Intel® DevCloud"
+    "# Intel VTune Profiler"
    ]
   },
   {
@@ -28,7 +28,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "- Profile a SYCL application using the VTune™ profiling tool on Intel® DevCloud\n",
+    "- Profile a SYCL application using the VTune™ profiling tool on Intel® Developer Cloud\n",
     "- Understand the basics of VTune™ command line options for collecting data and generating reports"
    ]
   },
@@ -45,7 +45,7 @@
    "source": [
     "VTune™ allows SYCL Profiling capabilities so you can tune for CPU, GPU, and FPGA.\n",
     "\n",
-    "![VTune UI](vtuneui.png)\n",
+    "![VTune UI](assets/vtuneui.png)\n",
     "\n",
     "__Analyze Data Parallell C++__ :\n",
     "See the lines of DPC++ that consume the most time\n",
@@ -104,11 +104,11 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "VTune™ Command-line is useful when on __Intel® DevCloud__ or you only have __SSH__ access to development system.\n",
+    "VTune™ Command-line is useful when on __Intel® Developer Cloud__ or you only have __SSH__ access to development system.\n",
     "\n",
     "However, it is recommended to install the __full VTune™ version__ on a local system and use the __UI rich experience__ of VTune Profiling Tool.\n",
     "\n",
-    "![VTune UI](vtuneui.png)\n"
+    "![VTune UI](assets/vtuneui.png)\n"
    ]
   },
   {
@@ -323,9 +323,9 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3.7 (Intel® oneAPI)",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
-   "name": "c009-intel_distribution_of_python_3_oneapi-beta05-python"
+   "name": "python3"
   },
   "language_info": {
    "codemirror_mode": {
@@ -337,7 +337,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.7"
+   "version": "3.11.5"
   },
   "toc": {
    "base_numbering": 1,

DirectProgramming/C++SYCL/Jupyter/oneapi-essentials-training/06_Intel_VTune_Profiler/VTune_on_IDC.ipynb

@@ -0,0 +1,221 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "4534a157-d01f-4be2-9ee9-153509e8872b",
+   "metadata": {},
+   "source": [
+    "# VTune Profiling on Intel Developer Cloud\n",
+    "\n",
+    "VTune Profiling can be accomplished on Intel Developer Cloud using one of two methods:\n",
+    "\n",
+    "1. [VTune Server Web UI for Collection and Analysis](#VTune-Server-Web-UI-for-Collection-and-Analysis)\n",
+    "2. [VTune Command Line for Collection and VTune GUI for Analysis](#VTune-Command-Line-for-Collection-and-VTune-GUI-for-Analysis)\n",
+    "\n",
+    "__Option 1__ requires you to __start VTune server on Intel Developer Cloud__ and you can __access the VTune UI in web browser__, it also requires you to __setup ssh reverse proxy from local machine__, VTune Web UI may be slow to load data since it is fetched from cloud. It does not require any local installation, but does have extra step of setting up SSH keys for Intel Developer Cloud so that you can start a reverse proxy to access VTune web UI.\n",
+    "\n",
+    "__Option 2__ requires you to __install Intel VTune Profiler on your local machine__ for analysis. VTune collection is done using __cmd line on Intel Developer Cloud__ and the data is copied to local machine for analysis. This option is faster to do analysis since the data and VTune application is installed on local machine."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "5c84fa7c-d4ee-4c3c-a0e9-4343b1001b71",
+   "metadata": {
+    "jp-MarkdownHeadingCollapsed": true
+   },
+   "source": [
+    "## VTune Server Web UI for Collection and Analysis\n",
+    "\n",
+    "For this setup, you have to __start VTune server on Intel Developer Cloud__, you will have to __setup ssh reverse proxy from local machine__ and you can __access the VTune UI in web browser__ as shown in the picture below.\n",
+    "\n",
+    "<img src=\"assets/vtune_server_block.png\" width=\"75%\">\n",
+    "\n",
+    "Quick setup instructions are for advanced users, refer to detailed setup instructions below for detailed step-by-step guide.\n",
+    "\n",
+    "### Quick Setup Instructions:\n",
+    "\n",
+    "1. Start VTune server on Intel Developer Cloud:\n",
+    "\n",
+    "   `$vtune-backend --allow-remote-access --enable-server-profiling`\n",
+    "\n",
+    "    Make a note of IP and PORT in the URL displayed\n",
+    "\n",
+    "2. In local machine terminal, create a reverse proxy:\n",
+    "\n",
+    "   `ssh uXXXXXXXXXXXXXXX@idcbetabatch.eglb.intel.com -L PORT:IP:PORT`\n",
+    "\n",
+    "3. In local machine browser, copy the URL from step 1 and replace IP with `127.0.0.1`\n",
+    "\n",
+    "   `https://127.0.0.1:PORT/?xxxx`\n",
+    "\n",
+    "    This will launch VTune Web UI\n",
+    "\n",
+    "4. Select \"Analysis Configuration\" in VTune Web UI, enter the \"Application\" full path of binary on Intel Developer Cloud (pwd), Select \"Performance Snapsot\" to \"GPU Hotspot\" and Run\n",
+    "\n",
+    "\n",
+    "### Detailed Setup Instructions:\n",
+    "Below are the steps to setup VTune server and VTune Web UI:\n",
+    "1. Start VTune server on Intel Developer Cloud\n",
+    "2. Create a reverse proxy from local machine\n",
+    "3. Launch VTune Web UI\n",
+    "4. Start VTune Analysis\n",
+    "\n",
+    "#### Start VTune server on Intel Developer Cloud\n",
+    "In Jupyter terminal (or SSH terminal), start vtune server:\n",
+    "```\n",
+    "$vtune-backend --allow-remote-access --enable-server-profiling\n",
+    "```\n",
+    "\n",
+    "The above command will display a URL to open in browser which will look like shown below, make note of IP_ADDRESS and PORT in the URL\n",
+    "<img src=\"assets/vtune_server.png\">\n",
+    "\n",
+    "\n",
+    "#### Create a reverse proxy from localhost\n",
+    "\n",
+    "In Intel Developer Cloud Console:\n",
+    "- select \"Training and Workshops\"\n",
+    "- click on title of any training, and select \"Options\" dropdown\n",
+    "- select \"Upload Key\" and add ssh key, if u have not added one before\n",
+    "- click \"Launch Using SSH\"\n",
+    "- Copy the ssh command\n",
+    "\n",
+    "In local machine terminal, setup reverse proxy:\n",
+    "\n",
+    "(ssh command copied above) +  `-L PORT:IP_ADDRESS:PORT`\n",
+    "```\n",
+    "ssh xxxx@xxxx.com -L PORT:IP_ADDRESS:PORT\n",
+    "```\n",
+    "Command should look like below:\n",
+    "```\n",
+    "ssh uXXXXXXXXXXXXXXX@idcbetabatch.eglb.intel.com -L 39317:10.10.10.32:45571\n",
+    "```\n",
+    "\n",
+    "#### Launch VTune Web UI\n",
+    "\n",
+    "Copy URL displayed in the Jupyter Terminal from earlier step.\n",
+    "\n",
+    "Open Browser on local machine and open the URL with IP_ADDRESS replaced with `127.0.0.1`, it should look similar to the one below:\n",
+    "```\n",
+    "https://127.0.0.1:45571/?xxxx\n",
+    "```\n",
+    "This should launch VTune Web UI\n",
+    "\n",
+    "#### Start VTune Analysis from Web UI\n",
+    "\n",
+    "- Click \"Configure Analysis\"\n",
+    "- In the \"Application\" field enter the full path to the binary you want to profile:\n",
+    "  - Compile any SYCL code to get binary like `a.out`\n",
+    "  - To get full path, `cd` to the location of binary in Jupyter terminal and enter `pwd`, copy the full path\n",
+    "  - example: `/home/uXXXXX/test/a.out`\n",
+    "- For \"Performance Snapshot\" select \"GPU Hotspots\"\n",
+    "- Click the Run button\n",
+    "<img src=\"assets/vtune_web_configure.png\">\n",
+    "- Wait for collection to complete and then UI will load for analysis\n",
+    "- Navigate to the \"Graphics\" tab and then \"Platform\" tab to analyze performance timeline and compute stats\n",
+    "- Refer to VTune Profiler documentation for more information\n",
+    "\n",
+    "\n",
+    "Instead of doing \"Configure Analysis\" from the VTune Web UI, you can also collect data using the vtune command line and then open the analysis on VTune Web UI:\n",
+    "- In a Jupyter terminal, run VTune command line to collect data:\n",
+    "```\n",
+    "vtune -collect gpu-hotspots -result-dir ~/intel/vtune/projects/vtune_data $(pwd)/a.out\n",
+    "```\n",
+    "Make sure to set the `-result-dir` value to ` ~/intel/vtune/projects/<name-for-project>`\n",
+    "\n",
+    "- The `vtune_data` will appear in \"Project Navigator\" panel in the left side of Web UI, click on it to open analysis"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "101605b5-172f-43be-ae03-4157dedc2d4f",
+   "metadata": {},
+   "source": [
+    "## VTune Command Line for Collection and VTune GUI for Analysis\n",
+    "\n",
+    "For this setup, you have start VTune collection using __vtune cmd line on Intel Developer Cloud__, the data has to be copied to local machine and you have to __install Intel VTune Profiler on your local machine__ for analysis of data as shown in picture below:\n",
+    "\n",
+    "<img src=\"assets/vtune_gui_block.png\" width=\"75%\">\n",
+    "\n",
+    "Quick setup instructions are for advanced users, refer to detailed setup instructions below for detailed step-by-step guide.\n",
+    "\n",
+    "### Quick Setup Instructions:\n",
+    "\n",
+    "1. Collect VTune data on Intel Developer Cloud:\n",
+    "\n",
+    "    `vtune -collect gpu-hotspots -result-dir vtune_data $(pwd)/a.out`\n",
+    "\n",
+    "2. Compress the `vtune_data` folder\n",
+    "\n",
+    "   `tar -cvf vtune_data.tgz vtune_data`\n",
+    "\n",
+    "3. Download `vtune_data.tgz` to local computer and uncompress\n",
+    "\n",
+    "   `tar -xvf vtune_data.tgz`\n",
+    "\n",
+    "4. Open results in local installation of VTune\n",
+    "\n",
+    "    Install VTune on oneAPI Base Toolkit on local machine and launch VTune\n",
+    "\n",
+    "    Select \"Open Results\" and point to the `*.vtune` file in `vtune_data` folder\n",
+    "\n",
+    "\n",
+    "### Detailed Setup Instructions:\n",
+    "Below are steps to run vtune cmd line and download data for analysis on local machine.\n",
+    "   1. Use vtune command line to collect vtune profiling data\n",
+    "   2. Compress vtune data\n",
+    "   3. Download vtune data to local computer\n",
+    "   4. Install VTune Profiler on local computer and open vtune data for analysis\n",
+    "\n",
+    "#### Collect VTune data using command line\n",
+    "- Modify the module's example code and then \"Build and Run\", this will generate the binary `a.out`\n",
+    "- Then in \"Terminal\", go to the current module directory and run the following vtune command (change the `-result-dir` value from `vtune_data` to something that identifies your code) \n",
+    "```\n",
+    "vtune -collect gpu-hotspots -result-dir vtune_data $(pwd)/a.out\n",
+    "```\n",
+    "\n",
+    "#### Compress vtune data\n",
+    "- Compress the vtune results directory to copy to your location computer (GUI)\n",
+    "```\n",
+    "tar -cvf vtune_data.tgz vtune_data\n",
+    "```\n",
+    "#### Download and Uncompress vtune data\n",
+    "- Download the compressed vtune results:\n",
+    "    -  If using Jupyter, right click on the `*.tgz` file and select \"Download\"\n",
+    "    -  If using `ssh`, use `scp` to copy the `*.tgz` to your GUI computer\n",
+    "- Uncompress the vtune results files:\n",
+    "```\n",
+    "tar -xvf vtune_data.tgz\n",
+    "```\n",
+    "\n",
+    "#### VTune Analysis on local machine\n",
+    "- On your computer, install \"Intel VTune Profiler\" from [__Intel oneAPI Base Toolkit__](https://www.intel.com/content/www/us/en/developer/tools/oneapi/base-toolkit-download.html)\n",
+    "- Open __Intel VTune Profiler__ and select the option to \"Open Results\" in the \"Welcome\" tab and select the vtune results directory that was downloaded, select the *.vtune file.\n",
+    "- Navigate to the \"Graphics\" tab and then \"Platform\" tab to analyze performance timeline and compute stats\n",
+    "- Refer to VTune Profiler documentation for more information\n",
+    "\n",
+    "<img src=\"assets/vtune_profiler.png\">"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.11.5"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}