bolt/docs/Heatmaps.md

   1 # Code Heatmaps
   2
   3 BOLT has gained the ability to print code heatmaps based on
   4 sampling-based profiles generated by `perf`, either with `LBR` data or not.
   5 The output is produced in colored ASCII to be displayed in a color-capable
   6 terminal. It looks something like this:
   7
   8 ![](./Heatmap.png)
   9
  10 Heatmaps can be generated for BOLTed and non-BOLTed binaries. You can
  11 use them to compare the code layout before and after optimizations.
  12
  13 To generate a heatmap, start with running your app under `perf`:
  14
  15 ```bash
  16 $ perf record -e cycles:u -j any,u -- <executable with args>
  17 ```
  18 or if you want to monitor the existing process(es):
  19 ```bash
  20 $ perf record -e cycles:u -j any,u [-p PID|-a] -- sleep <interval>
  21 ```
  22
  23 Running with LBR (`-j any,u` or `-b`) is recommended. Heatmaps can be generated
  24 from basic events by using the llvm-bolt-heatmap option `-nl` (no LBR) but
  25 such heatmaps do not have the coverage provided by LBR and may only be useful
  26 for finding event hotspots at larger code block granularities.
  27
  28 Once the run is complete, and `perf.data` is generated, run llvm-bolt-heatmap:
  29
  30 ```bash
  31 $ llvm-bolt-heatmap -p perf.data <executable>
  32 ```
  33
  34 By default the heatmap will be dumped to *stdout*. You can change it
  35 with `-o <heatmapfile>` option.
  36
  37
  38 If you prefer to look at the data in a browser (or would like to share
  39 it that way), then you can use an HTML conversion tool. E.g.:
  40
  41 ```bash
  42 $ aha -b -f <heatmapfile> > <heatmapfile>.html
  43 ```
  44
  45 ---
  46
  47 ## Background on heatmaps:
  48 A heatmap is effectively a histogram that is rendered into a grid for better
  49 visualization.
  50 In theory we can generate a heatmap using any binary and a perf profile.
  51
  52 Each block/character in the heatmap shows the execution data accumulated for
  53 corresponding 64 bytes of code. You can change this granularity with a
  54 `-block-size` option.
  55 E.g. set it to 4096 to see code usage grouped by 4K pages.
  56
  57
  58 When a block is shown as a dot, it means that no samples were found for that
  59 address.
  60 When it is shown as a letter, it indicates a captured sample on a particular
  61 text section of the binary.
  62 To show a mapping between letters and text sections in the legend, use
  63 `-print-mappings`.
  64 When a sampled address does not belong to any of the text sections, the
  65 characters 'o' or 'O' will be shown.
  66
  67 The legend shows by default the ranges in the heatmap according to the number
  68 of samples per block.
  69 A color is assigned per range, except the first two ranges that distinguished by
  70 lower and upper case letters.
  71
  72 On the Y axis, each row/line starts with an actual address of the binary.
  73 Consecutive lines in the heatmap advance by the same amount, with the binary
  74 size covered by a line dependent on the block size and the line size.
  75 An empty new line is inserted for larger gaps between samples.
  76
  77 On the X axis, the horizontally emitted hex numbers can help *estimate* where
  78 in the line the samples lie, but they cannot be combined to provide a full
  79 address, as they are relative to both the bucket and line sizes.
  80
  81 In the example below, the highlighted `0x100` column is not an offset to each
  82 row's address, but instead, it points to the middle of the line.
  83 For the generation, the default bucket size was used with a line size of 128.
  84
  85
  86 ![](./HeatmapHeader.png)
  87
  88
  89 Some useful options are:
  90
  91 ```
  92 -line-size=<uint>   - number of entries per line (default 256)
  93 -max-address=<uint> - maximum address considered valid for heatmap (default 4GB)
  94 -print-mappings     - print mappings in the legend, between characters/blocks and text sections (default false)
  95 ```