Update with Command Line Tracy usage. (#8080)
diff --git a/docs/developers/developing_iree/profiling_with_tracy.md b/docs/developers/developing_iree/profiling_with_tracy.md index 516b049..5b3e27e 100644 --- a/docs/developers/developing_iree/profiling_with_tracy.md +++ b/docs/developers/developing_iree/profiling_with_tracy.md
@@ -21,32 +21,24 @@ or [preview it](https://docs.google.com/viewer?url=https://github.com/wolfpld/tracy/releases/latest/download/tracy.pdf). -## Building the Tracy UI (the "server") - -This is explained in section 2.3 of the [manual](#the-tracy-manual) for Windows -and Linux. Here we give some more detailed instructions for some systems. - -The IREE repository contains its own clone of the Tracy repository in -`third_party/tracy`, so there is no need to make a separate clone of it. You can -use one if you want, but be aware that the Tracy client/server protocol gets -updated sometimes. Building both sides from the same `iree/third_party/tracy` -lowers the risk of running into a protocol version mismatch. - +## Install dependencies ### Linux Install dependencies (Debian-based distributions): -``` +```shell sudo apt install libcapstone-dev libtbb-dev libglfw3-dev libfreetype6-dev libgtk-3-dev ``` -Build (from your `iree/` clone root directory): -``` -make -C third_party/tracy/profiler/build/unix -j12 release +If you only build the command line tool you can install: +```shell +sudo apt install libcapstone-dev libtbb-dev libzstd-dev ``` ### Mac +```shell +brew install capstone glfw freetype +``` -TODO write this (Kojo?) ## Building IREE with Tracy instrumentation (the "client") @@ -72,64 +64,51 @@ `ON`. Compiler tracing is less stable, particularly on Linux with MLIR threading enabled (https://github.com/google/iree/issues/6404). -## Permissions issues -The profiled application (i.e. the Tracy client) needs to have appropriate -permissions so perform the special I/O required to collect the profile -information. This is OS-specific. +## Building the Tracy Command Line Capture (the alternative "server") -### Desktop Linux - -On desktop Linux, the profiled application must be run as root, e.g. with -`sudo`. Otherwise, profile data will lack important components. - -### Android - -On Android it is not necessary to run as root and in fact, Android graphical -applications never run as root, so it's advisable to run all programs as -non-root for consistency. - -The Android device must be prepared as follows to enable Tracy profiling. -* The device must be rooted. - * That means that in `adb shell`, the command `su` must succeed. - * That does NOT mean doing `adb root`. The effect of `adb root` is to have the - `adbd` daemon itself run as root, which causes `adb shell` to give you a - root shell by default. If you are in that case, consider doing `adb unroot` - to restart the `adbd` server as non-root. Not mandatory, but again, running - anything as root on Android is a deviation from normal user conditions. -* Execute the following commands in a root shell on the device (i.e. `adb - shell`, then `su`, then the following commands). These are from the - [manual](#the-tracy-manual), but hard to find there, and copy-pasting from PDF - introduces unwanted whitespace. These settings normally persist until the next - reboot of the device. - * `setenforce 0` - * `mount -o remount,hidepid=0 /proc` - * `echo 0 > /proc/sys/kernel/perf_event_paranoid` - -## Port forwarding - -The Tracy client and server communicate by default over port `8086`. When they -run on different machines, e.g. with embedded/Android profiling or remote -profiling, port forwarding must be set up. - -### Between a computer and a local Android device connected to it by USB - -Run this command. You might need to run it again more a little frequently than -you reboot the device. When experiencing connection issues, try that first. +Optionally build the command capture tool with `-DIREE_BUILD_TRACY=ON ` ```shell -adb forward tcp:8086 tcp:8086 +$ cmake \ + -DIREE_BUILD_TRACY=ON \ + -DIREE_ENABLE_RUNTIME_TRACING=ON \ + -DCMAKE_BUILD_TYPE=RelWithDebInfo \ + ... # other cmake arguments as usual ``` -### Between two computers over the network +The built command line tool will be found at `./build/tracy/iree-tracy-capture` -TODO write this (`ssh` stuff...) +## Building the Tracy UI (the "server") + +This is explained in "Building the server" section 2.3 of the [manual](#the-tracy-manual) for Windows +and Linux. Here we give some more detailed instructions for some systems. + +This is built as part of the IREE build above if you have installed the dependencies. +The tool would be located at `./build/tracy/iree-tracy-profiler` + +If you would like to build the "server" for your desktop to connect remotely follow along. + +The IREE repository contains its own clone of the Tracy repository in +`third_party/tracy`, so there is no need to make a separate clone of it. You can +use one if you want, but be aware that the Tracy client/server protocol gets +updated sometimes. Building both sides from the same `iree/third_party/tracy` +lowers the risk of running into a protocol version mismatch. + + +### Build on Mac and Linux + +Build (from your `iree/` clone root directory): +``` +make -C third_party/tracy/profiler/build/unix -j12 release +``` + ## Running the profiled program -Tracing doesn't work properly on VMs (see section 2.1.6.4 of the -[manual](#the-tracy-manual)). To get sampling, you should run the profiled -program on bare metal. +Tracing doesn't work properly on VMs (see "Problematic Platforms / Virtual Machines" +section 2.1.6.4 of the [manual](#the-tracy-manual)). To get sampling, you should +run the profiled program on bare metal. Run your IREE workload as you normally would: now that it's been built with Tracy instrumentation enabled, it should do all the right things automatically. @@ -154,11 +133,34 @@ --function_input=1x384xi32 ``` + +## Running the Tracy Capture CLI, connecting and saving profiles + +While the program that you want to profile is still running (thanks to +`TRACY_NO_EXIT=1`), start the Tracy capture tool in another terminal / ttyl. +From the IREE root directory: +```shell +./build/tracy/iree-tracy-capture -o myprofile.tracy +Connecting to 127.0.0.1:8086... +``` + +It should connect to the IREE client and save the output to myprofile.tracy that +can be visualized by the client below. You can start the capture tool first to +make sure you don't miss any capture events. + + ## Running the Tracy profiler UI, connecting and visualizing While the program that you want to profile is still running (possibly thanks to `TRACY_NO_EXIT=1`), start the Tracy profiler UI which we had built above. From the IREE root directory: + +If you built it part of IREE: +```shell +./build/tracy/iree-tracy-profiler +``` + +If you built the standalone "server" on MAC or Linux: ```shell ./third_party/tracy/profiler/build/unix/Tracy-release ``` @@ -247,6 +249,63 @@ the Ghost zone saw into the IREE compiled module that that calls into, with the source view pointing to the `.mlir` file. +## Permissions issues + +The profiled application (i.e. the Tracy client) needs to have appropriate +permissions so perform the special I/O required to collect the profile +information. This is OS-specific. + +### Desktop Linux + +On desktop Linux, the profiled application must be run as root, e.g. with +`sudo`. Otherwise, profile data will lack important components. + +### Android + +On Android it is not necessary to run as root and in fact, Android graphical +applications never run as root, so it's advisable to run all programs as +non-root for consistency. + +The Android device must be prepared as follows to enable Tracy profiling. +* The device must be rooted. + * That means that in `adb shell`, the command `su` must succeed. + * That does NOT mean doing `adb root`. The effect of `adb root` is to have the + `adbd` daemon itself run as root, which causes `adb shell` to give you a + root shell by default. If you are in that case, consider doing `adb unroot` + to restart the `adbd` server as non-root. Not mandatory, but again, running + anything as root on Android is a deviation from normal user conditions. +* Execute the following commands in a root shell on the device (i.e. `adb + shell`, then `su`, then the following commands). These are from the + [manual](#the-tracy-manual), but hard to find there, and copy-pasting from PDF + introduces unwanted whitespace. These settings normally persist until the next + reboot of the device. + * `setenforce 0` + * `mount -o remount,hidepid=0 /proc` + * `echo 0 > /proc/sys/kernel/perf_event_paranoid` + +## Port forwarding + +The Tracy client and server communicate by default over port `8086`. When they +run on different machines, e.g. with embedded/Android profiling or remote +profiling, port forwarding must be set up. + +### Between a computer and a local Android device connected to it by USB + +Run this command. You might need to run it again more a little frequently than +you reboot the device. When experiencing connection issues, try that first. + +```shell +adb forward tcp:8086 tcp:8086 +``` + +### Between two computers over the network + +Setup you [ssh tunnel](https://linuxize.com/post/how-to-setup-ssh-tunneling/) +Make sure you can telnet to your local port and you can hit the remote server +port 8086. Once that is done supply the port address for the caputre tool +to connect to. + + ## Configuring Tracy instrumentation Set IREE's `IREE_TRACING_MODE` value (defined in