1# Symbolizer
2
3This document outlines how to symbolize crashes and backtraces in Zircon.
4
5## Overview
6
7If you have some text that contains the required information, you can symbolize
8that text by piping it into `./scripts/symbolize`. You can run
9`./scripts/symbolize -h` to see how to use it.
10
11If you use `loglistener` on x64, this is quite simple. You can simply pipe
12directly into symbolize.
13
14```
15loglistener | ./scripts/symbolize
16```
17
18You can use the standard flags found in other scripts in Zircon to specify
19other builds than build-x64. For instance, if you want to symbolize an arm64
20build that was built with Clang you can run the following:
21
22```
23loglistener | ./scripts/symbolize -a arm64 -C
24```
25
26If you're familiar with what `ids.txt` is, and you know what you're doing you
27can also specify `ids.txt` directly.
28
29```
30loglistener | ./scripts/symbolize build-arm64-asan/ids.txt
31```
32
33## ASan with QEMU Example
34
35For a slightly more involved case we'll consider a complete workflow to compile
36and symbolize an ASan crash.
37
38First build (you can use `./scripts/build-zircon-x86 -A` as well):
39
40```
41make -j $JOBS USE_ASAN=true
42```
43
44Now you'll want to run this on QEMU, but if you just run it directly
45you'll be stuck copy pasting the output into a file. You can use `tee`
46to solve this:
47
48```
49./scripts/run-zircon-x86 -A | tee ~/log.txt
50```
51
52This will create a log.txt file in your home directory (feel free to place it
53anywhere) that will contain all output from your QEMU run. While QEMU is
54running, we'll need to create a crash. To get a handy ASan crash result we can
55use `crasher`
56
57```
58$ crasher use_after_free
59```
60
61Now just pipe the output thought the symbolizer
62
63```
64./scripts/symbolize -A < ~/log.txt
65```
66
67# TODO(TC-283): Remove this after TC-283 is solved.
68You might be wondering if you can just pipe QEMU directly into the symbolizer.
69Right now this won't cause an error but it is not really usable because the
70symbolizer buffers on a line by line basis. This may be possible in the future.
71