README.md

   1 # Tizen .NET Memory Profiler
   2
   3 (Original KDE Heaptrack's README can be found [here](docs/HEAPTRACK_README.md))
   4
   5 ## Brief contents of the Guide
   6
   7 ### Building and launching profiler in Docker
   8
   9 Prerequisites:
  10 * [Tizen SDK](https://developer.tizen.org/development/tizen-studio/download) is required to run the profiler.
  11 * Your host machine should have Docker installed. For Ubuntu instructions, please see [the manual](https://docs.docker.com/engine/installation/linux/docker-ce/ubuntu/).
  12
  13 Please, keep in mind:
  14
  15 > If you would like to use Docker as a non-root user, you should now consider
  16 > adding your user to the "docker" group with something like:
  17 >
  18 > `sudo usermod -aG docker your-user`
  19
  20 1. When building in Docker, the first thing you need to do is to create a `coreclr-devel` directory and put coreclr-devel rpms for the CoreCLR versions you use on your devices in this folder. You can find out which version of CoreCLR is installed on your device using `rpm -qa` command. Alternatively, you can let docker download the latest `coreclr-devel` package from download.tizen.org, or, if you are building CoreCLR yourself, point the build script to the compiled CoreCLR source folder. If you choose one of these two options, leave the `coreclr-devel` folder empty and proceed to step 2.
  21 2. Run
  22 ```
  23 sudo ./launch.sh org.tizen.example.HelloWorld.Tizen /opt/usr/home/owner/apps_rw/HelloWorld.Tizen/bin/HelloWorld.Tizen.exe
  24 ```
  25 to build the profiler and launch profiling of HelloWorld application. If you are running the profiler for the first time, you will be asked permission to move files around on the device in order to free up some disk space. You will also be asked to point the script to the location of "debuginfo" RPMs for the native libraries in which you want to see stack traces.
  26
  27 ### VM [[Details]](docs/DETAILED.md#download-and-unpack-vm-disk-image-from-this-page)
  28
  29 1\. Download and unpack VM image, start it in VirtualBox and connect with Tizen device
  30
  31 To unpack it on Linux, please, download the ubuntu-17.04.vdi.tar.bz2-* files to separate directory and run the following command in the directory:
  32
  33 ```
  34 cat ubuntu-17.04.vdi.tar.bz2-* | tar xjvf -
  35 ```
  36
  37
  38
  39 For unpacking on Windows, please see [the details](docs/DETAILED.md#download-and-unpack-vm-disk-image-from-this-page).
  40
  41 * [ubuntu-17.04.vdi.tar.bz2-31-08-17-aa](http://suprem.sec.samsung.net/confluence/download/attachments/81831470/ubuntu-17.04.vdi.tar.bz2-31-08-17-aa?api=v2)
  42 * [ubuntu-17.04.vdi.tar.bz2-31-08-17-ab](http://suprem.sec.samsung.net/confluence/download/attachments/81831470/ubuntu-17.04.vdi.tar.bz2-31-08-17-ab?api=v2)
  43 * [ubuntu-17.04.vdi.tar.bz2-31-08-17-ac](http://suprem.sec.samsung.net/confluence/download/attachments/81831470/ubuntu-17.04.vdi.tar.bz2-31-08-17-ac?api=v2)
  44 * [ubuntu-17.04.vdi.tar.bz2-31-08-17-ad](http://suprem.sec.samsung.net/confluence/download/attachments/81831470/ubuntu-17.04.vdi.tar.bz2-31-08-17-ad?api=v2)
  45 * [ubuntu-17.04.vdi.tar.bz2-31-08-17-ae](http://suprem.sec.samsung.net/confluence/download/attachments/81831470/ubuntu-17.04.vdi.tar.bz2-31-08-17-ae?api=v2)
  46 * [ubuntu-17.04.vdi.tar.bz2-31-08-17-af](http://suprem.sec.samsung.net/confluence/download/attachments/81831470/ubuntu-17.04.vdi.tar.bz2-31-08-17-af?api=v2)
  47 * [ubuntu-17.04.vdi.tar.bz2-31-08-17-ag](http://suprem.sec.samsung.net/confluence/download/attachments/81831470/ubuntu-17.04.vdi.tar.bz2-31-08-17-ag?api=v2)
  48 * [ubuntu-17.04.vdi.tar.bz2-31-08-17-ah](http://suprem.sec.samsung.net/confluence/download/attachments/81831470/ubuntu-17.04.vdi.tar.bz2-31-08-17-ah?api=v2)
  49 * [ubuntu-17.04.vdi.tar.bz2-31-08-17-ai](http://suprem.sec.samsung.net/confluence/download/attachments/81831470/ubuntu-17.04.vdi.tar.bz2-31-08-17-ai?api=v2)
  50
  51 [[SHA256 values for archive contents]](#checksums)
  52
  53 ### Initialization of device for measurements [[Details]](docs/DETAILED.md#prepare-tizen-device-for-measurements)
  54
  55 2\. Put Tizen RPMs to VM's /home/ubuntu/device-rpms for:
  56 - debuginfo packages
  57
  58 3\. Run /home/ubuntu/heaptrack-scripts/prepare-device.sh on VM
  59
  60 [Video tutorial](http://suprem.sec.samsung.net/confluence/download/attachments/81831470/How-to-prepare-Tizen-device-for-measurements.mp4?api=v2)
  61
  62
  63 ### Build profiler module for your CoreCLR version [[Details]](docs/DETAILED.md#build-profiler-module-for-your-coreclr-version)
  64
  65 By default the libprofiler.so is already built for coreclr-2.0.0.11992-11.1.armv7l, so if you use this version,
  66 then you don't need to rebuild it.
  67
  68 For details, see "Build profiler module" in full contents below (section 5)
  69
  70 [Video tutorial](http://suprem.sec.samsung.net/confluence/download/attachments/81831470/How-to-build-managed-profiling-module.mp4?api=v2)
  71
  72 ### Measurements [[Details]](docs/DETAILED.md#run-measurements)
  73
  74 8\. Make sure that "debuginfo" packages are installed for all libraries that you want to track by the profiler
  75
  76 9\. Run application using /home/ubuntu/heaptrack-scripts/heaptrack.sh with `[application ID]` and `[path to executable]` arguments on VM,
  77 like the following:
  78
  79 ```
  80 ./heaptrack-scripts/heaptrack.sh org.tizen.example.HelloWorld.Tizen /opt/usr/home/owner/apps_rw/HelloWorld.Tizen/bin/HelloWorld.Tizen.exe
  81 ```
  82
  83 [Video tutorial](http://suprem.sec.samsung.net/confluence/download/attachments/81831470/Profiling-memory-consumption.mp4?api=v2)
  84
  85 10\. Wait until a moment, in which you want to figure out the memory consumption.
  86
  87 Please, note that application runs significantly slower (30x to 100x slower) under profiling.
  88
  89 11\. Press 'c' on VM, wait for GUI to start and analyze the results
  90 The GUI will start separately for **Malloc** part, **Managed** part, **mmap Private_Dirty** part, **mmap Private_Clean** part and **mmap Shared_Clean** part
  91
  92 [[Profiling results description]](#profiling-results)
  93
  94 [[Some screenshots]](#screenshots)
  95
  96 [[Solutions for possible issues]](#troubleshooting)
  97
  98 ### Profiling results
  99
 100 The GUI viewer provides several views for the profiling results.
 101
 102 - If some functions are shown as `<unresolved function>` - most probably (with few exceptions, like libc internals) it means that "debuginfo" package for the corresponding library is missing or of wrong version.
 103
 104 - The functions, which are marked as `<untracked>` are the areas, for which locations is not known. This is a mark for areas, which were allocated before attaching profiler, or by ways, which are not trackable by current version of profiler (current profiler doesn't track allocations from ld-linux.so.3).
 105
 106 - The "leaks" in the interface are most probably not actual leaks - it is label for memory that wasn't freed when application was terminating. However, it is usual behaviour for many libraries, including CoreCLR to not free memory upon application termination, as kernel anyway frees it. So, "leaks" labels should be considered as labels for memory, which was consumed just before memory profiling stopped.
 107
 108 #### Summary view
 109 Peak contributions shows top functions that consumed memory at moment of highest memory consumption.
 110 Peak instances shows top functions that has most memory items allocated and not freed at moment of highest count of the memory items.
 111 Largest memory leaks - top functions that allocated memory, which wasn't deallocated up to moment of memory profiling stop.
 112 Most memory allocations - top functions that call allocation most number of times.
 113 Most temporary allocations - the same for allocations, in which deallocation is called very close to allocation, like `p = malloc(...); simple code; free (p)`.
 114 Most memory allocated - top functions, which allocated most memory (this doesn't account deallocations, so is not very useful for analysis of memory consumption causes).
 115
 116 #### Bottom-Up/Top-Down view
 117 Memory consumption details for each detected call stack.
 118
 119 #### Caller / Callee view
 120 Memory consumption statistics for each function for itself, and also inclusive (i.e. including statistics of other functions, which it called).
 121
 122 #### Flame Graph view
 123 Also represents memory consumption per call-stack (either top-down or bottom-down mode)
 124 Combobox allows to choose between different statistics (like in Summary view).
 125 The "leaks" here also are not the memory leaks: it is memory that was consumed at moment of profiling stop.
 126 So, the "leaks" view seems to be the most useful to investigate memory consumption details.
 127
 128 #### Other
 129 Next several views are graphs for different memory consumption statistics (also, like in Summary view), as they change in time of application execution.
 130 Here, the "consumed" is used instead of "leaks", which is more precise.
 131 The "consumed" view shows memory consumption graph for top memory consuming function (separately, as shown in color, and also total consumption - the topmost graph).
 132
 133 ## Troubleshooting
 134
 135 1\. The heaptrack is built for one of latest Tizen Unified TM1 system.
 136 If it can't be started on your Tizen device, because of missing dependencies, please recompile it from sources (see /home/ubuntu/heaptrack-common/build-armel).
 137 Recompilation is simple, like "mkdir build_dir; cd build_dir; cmake ..; make -j4" and should be performed on an armel system with compatible libraries or in a corresponding chroot.
 138
 139 2\. Managed memory consumption or managed call stacks data is missing
 140
 141 See [[Build profiler module]](docs/DETAILED.md#build-profiler-module-for-your-coreclr-version)
 142
 143 3\. Please, feel free to ask any questions, in case of the described or other issues ([https://github.sec.samsung.net/dotnet/profiler/issues/4](https://github.sec.samsung.net/dotnet/profiler/issues/4))
 144
 145 The profiling tool can show memory consumption of **Managed**, **Malloc** and **Mmap**-allocated regions.
 146
 147 ## Screenshots
 148
 149 ### malloc'ed memory over time
 150 ![malloc-Consumed-Graph.png](screenshots/malloc-Consumed-Graph.png)
 151 *   Each color shows different function (function name is shown when mouse is over a part of graph)
 152 *   The top part is sum of all malloc-allocated memory (for all allocating functions)
 153 *   The graph is useful to get overall picture of how memory consumption changed as program executed
 154 ### Functions and their statistics
 155 ![malloc-Plain-Statistics.png](screenshots/malloc-Plain-Statistics.png)
 156 *   Peak is memory consumption of particular function at overall maximum of application consumption (this considers only currently shown memory - i.e. only malloc, or mmap Private_Dirty, or mmap Private_Clean, etc.)
 157 *   Leaked is memory consumption just at application exit (not actually, leak, as most application do not free memory at their exit - so, it is just information about memory consumption just before application exit)
 158 *   Allocated is sum of all allocated memory sizes (doesn't account that some memory was already freed - counts only allocations)
 159 *   "Incl." mark is for the function and all functions that it calls; "Self" mark is for the function only
 160 ### Call stacks and memory consumption at each point of call stack
 161 ![malloc-FlameGraph-Details.png](screenshots/malloc-FlameGraph-Details.png)
 162 *   For example, "icu::Normalizer2Impl::ensureCanonIterData" calls "utrie2_enum" and "icu::CanonIterData::CanonIterData" and "utri2_freeze"
 163     *   The "utrie2_enum" and "icu::CanonIterData::CanonIterData" and "utri2_freeze" call other functions that in sum allocate 539, 283 and 80 kilobytes, correspondingly
 164     *   The consumption for "ensureCanonIterData" will be shown as 904 kB - it is sum of the three values
 165 *   In another places (another call stacks) the functions can also be called and that memory consumption will be accounted separately for these and those call stacks
 166 ### Reversed FlameGraph (if "Bottom-Down View" is checked)
 167 ![malloc-FlameGraph-Reversed.png](screenshots/malloc-FlameGraph-Reversed.png)
 168 *   A useful form of FlameGraph to show the call stacks reversed
 169     *   So, the bottom line will show the allocator functions - like malloc, calloc, realloc, etc. and lines above will be the functions that call the allocator functions
 170 ### Top-N lists of functions:
 171 ![malloc-Summary.png](screenshots/malloc-Summary.png)
 172 *   functions that consumed most when peak of malloc memory consumption occured ("peak contributions")
 173 *   functions that consumed most just before application exit ("largest memory leaks")
 174 *   functions that called allocators more than others ("most memory allocations")
 175 *   functions that called allocators more than others for temporary allocations ("most temporary allocations") - temporary is the case when malloc and free are called almost one after other (with no allocations between them)
 176 *   functions that allocated most memory at sum ("most memory allocated") - just sum of allocations, without accounting freeing of memory
 177 *   "peak RSS" is currently experimental and so is not precise
 178 ### Managed heap inspection
 179 ![managed-ReferenceTree.png](screenshots/managed-ReferenceTree.png)
 180 *   Objects are grouped by their type
 181 *   If type T2 is a child of type T1, it means that objects of type T2 reference objects of type T1
 182 *   Shallow Size is the total size of objects in the reference chain
 183 *   Referenced Size is the size of objects referenced by the parent object.
 184 For example, `System.AppDomainSetup` references 76 bytes of `System.String`s in the screenshot through `System.Object[]`->`System.String[]` chain and 32 bytes of `System.String`s directly.
 185 ### mmap-allocated memory graphs
 186 Most of the graphs listed above are also available for mmap-allocated memory.
 187 ![mmap-private-dirty-Plain-Statistics.png](screenshots/mmap-private-dirty-Plain-Statistics.png)
 188 ![mmap-private-dirty-Consumed-Graph.png](screenshots/mmap-private-dirty-Consumed-Graph.png)
 189 *   the mmap-allocated memory is divided into four groups (as in /proc/.../smaps): Private_Dirty, Private_Clean, Shared_Clean + Shared_Dirty
 190     *   Private_Dirty is process-local (not shared) memory that was modified by the process
 191     *   Private_Clean is process-local (not shared) memory that was loaded from disk and not modified by the process
 192     *   Shared_Clean is shared between processes memory, not modified by the process
 193     *   Shared_Clean is shared between processes memory, modified by the process
 194     *   the groups are chosen by --private_dirty, --private_clean, --shared keys of heaptrack_gui (--malloc is for malloc memory consumption and --managed is for managed memory consumption)
 195 *   there are two additional groups, which are accounted indirectly
 196     *   dlopen (memory, used for loaded libraries)
 197     *   sbrk (memory, used for "[heap]") - this includes:
 198         *   libc allocator (malloc-allocated memory, can be investigated through `heaptrack_gui --malloc` run)
 199         *   overhead of profiler
 200         *   possibly, other allocators if they use `sbrk` (this is unusual)
 201
 202 ## Checksums
 203
 204 SHA256SUM for unpacked VM image
 205
 206 ```
 207 1afcea540149f76fae6e243839b6a21666725cc1409b4c259be82533e2a21a24  ubuntu-17.04.vdi
 208 ```
 209
 210 SHA256SUM for archive
 211
 212 ```
 213 e8de003daa38880e37d847af462b86145ccf859f0af127e9a18dcc7c7cc04deb  ubuntu-17.04.vdi.tar.bz2
 214 ```
 215
 216 SHA256SUM for archive parts
 217 ```
 218 7da95143eb387f94d09c1a34a952bcdc05844cbf064ba971884b6107f2665e55  ubuntu-17.04.vdi.tar.bz2-31-08-17-aa
 219 34bec202f4521fc3857fa57c7acb07910f02df788add8a01dc03b09bc732895f  ubuntu-17.04.vdi.tar.bz2-31-08-17-ab
 220 a03cd105647fd225fcbc85310490032f96c23c9e55289fe88341daf8db560236  ubuntu-17.04.vdi.tar.bz2-31-08-17-ac
 221 788790f51a237273eff96e102a6ad39fdd0008dcfcbbe537d80a1ab543cbcd7c  ubuntu-17.04.vdi.tar.bz2-31-08-17-ad
 222 a165a9642e8d58536b4c944e12fe23bd666d77cd74b3fce1b050c01308a4b887  ubuntu-17.04.vdi.tar.bz2-31-08-17-ae
 223 7bf1495ae705a6a32577c4b1982c18230338eaa4b7cd5079b87a376d99b77b48  ubuntu-17.04.vdi.tar.bz2-31-08-17-af
 224 6fea617bf0833bb841317c56674e6b34c09a145fc5a95f4ce1ea202dc6f4b56a  ubuntu-17.04.vdi.tar.bz2-31-08-17-ag
 225 21389420ce2dcc0cd86d1b2c0872cb116e18ce226e1bab111e00536ed5be17f1  ubuntu-17.04.vdi.tar.bz2-31-08-17-ah
 226 58a3950e44c37f9b825d13ff738e75544a3a2e0bca8f5a74ce877cbbee7a141b  ubuntu-17.04.vdi.tar.bz2-31-08-17-ai
 227 ```