tools/browse_trace.readme.md

   1 ### A debugging helper that lets you zoom in/out on a trace.
   2
   3 To try it out, first create an example trace:
   4
   5   ```shell
   6   $ cd linux
   7   $ bootstrap/bootstrap translate [01]*.subx factorial.subx -o factorial
   8   $ bootstrap/bootstrap --trace run factorial
   9   ```
  10
  11 This command will save a trace of its execution in a file called `last_run`.
  12 The trace consists of a series of lines, each starting with an integer depth
  13 and a single-word 'label', followed by a colon and whitespace.
  14
  15 Now browse this trace:
  16
  17   ```shell
  18   $ cd ..
  19   $ tools/browse_trace linux/last_run
  20   ```
  21
  22 You should now find yourself in a UI showing a subsequence of lines from the
  23 trace, each line starting with a numeric depth, and ending with a parenthetical
  24 count of trace lines hidden after it with greater depths.
  25
  26 For example, this line:
  27
  28   ```
  29   2 app: line1 (30)
  30   ```
  31
  32 indicates that it was logged with depth 2, and that 30 following lines have
  33 been hidden at a depth greater than 2.
  34
  35 (As an experiment, hidden counts of 1000 or more are highlighted in red.)
  36
  37 The UI provides the following hotkeys:
  38
  39 * `q` or `ctrl-c`: Quit.
  40
  41 * `Enter`: 'Zoom into' this line. Expand lines hidden after it that were at
  42   the next higher level.
  43
  44 * `Backspace`: 'Zoom out' on a line after zooming in, collapsing lines below
  45   expanded by some series of `Enter` commands.
  46
  47 * `j` or `down-arrow`: Move cursor down one line.
  48 * `k` or `up-arrow`: Move cursor up one line.
  49 * `J` or `ctrl-f` or `page-down`: Scroll cursor down one page.
  50 * `K` or `ctrl-b` or `page-up`: Scroll cursor up one page.
  51 * `h` or `left-arrow`: Scroll cursor left one character.
  52 * `l` or `right-arrow`: Scroll cursor right one character.
  53 * `H`: Scroll cursor left one screen-width.
  54 * `L`: Scroll cursor right one screen-width.
  55
  56 * `g` or `home`: Move cursor to start of trace.
  57 * `G` or `end`: Move cursor to end of trace.
  58
  59 * `t`: Move cursor to top line on screen.
  60 * `c`: Move cursor to center line on screen.
  61 * `b`: Move cursor to bottom line on screen.
  62 * `T`: Scroll line at cursor to top of screen.
  63
  64 * `/`: Search forward for a pattern.
  65 * `?`: Search backward for a pattern.
  66 * `n`: Repeat the previous `/` or `?`.
  67 * `N`: Repeat the previous `/` or `?` in the opposite direction.
  68
  69 After hitting `/`, the mini-editor on the bottom-most line supports the
  70 following hotkeys:
  71 * ascii characters: add the key to the pattern.
  72 * `Enter`: search for the pattern.
  73 * `Esc` or `ctrl-c`: cancel the current search, setting the screen back
  74   to its state before the search.
  75 * `left-arrow`: move cursor left.
  76 * `right-arrow`: move cursor right.
  77 * `ctrl-a` or `home`: move cursor to start of search pattern.
  78 * `ctrl-e` or `end`: move cursor to end of search pattern.
  79 * `ctrl-u`: clear search pattern before cursor
  80 * `ctrl-k`: clear search pattern at and after cursor
  81
  82 ## wish list
  83
  84 * Simple regular expression search: `.` and `*`.
  85 * Expand into lower depths as necessary when searching.
  86 * Zoom out everything.
  87 * Zoom out lines around the cursor to the highest (or specified) depth.
  88   Maybe a number followed by `]`?