Docs: add high-level debug info doc
[babeltrace.git] / doc / debuginfo.txt
1 Babeltrace Debug Info Analysis
2 -----------------------------
3
4 The babeltrace debug info analysis is a set of features which allow
5 mapping events from a trace to their location in source code or within
6 a binary file, based on their `ip` (instruction pointer) field.
7
8 Prerequisites
9 -------------
10
11 In order to install a version of babeltrace with debug info support,
12 the following libraries are required:
13
14 * libelf
15 * libdw
16
17 Both of them are provided by the elfutils project
18 (https://fedorahosted.org/elfutils/), and can be installed through the
19 elfutils package on Ubuntu, Debian, RHEL, and others.
20
21 Compiling for Debug Info Analysis
22 ---------------------------------
23
24 Traced programs on which debug info analysis is to be performed can be
25 compiled in a few different ways, and still lead to useful results.
26
27 Ideally, one should compile the program in debug mode, which is
28 achieved on gcc by simply using the `-g` flag. This generates debug
29 information in the operating system's native format, which is then
30 used by babeltrace to map an event's source location to a file and
31 line number, and the name of the surrounding function.
32
33 Do note that only debug information in DWARF format, version 2 or
34 later, is currently supported by babeltrace. Use the `-gdwarf` or
35 `-gdwarf-(VERSION)` to explicitly generate DWARF debug information.
36
37 If the executable is not compiled with `-g` or an equivalent option
38 enabled, and thus no DWARF information is available, babeltrace will
39 use ELF symbols from the executable. Instead of providing source file,
40 line number and function name, however, the analysis will provide the
41 name of the nearest function symbol, plus an offset in bytes to the
42 location in the executable from which the event originated.
43
44 If the executable has neither ELF symbols nor DWARF information,
45 babeltrace will be unable to map an event to its source location and
46 will simply display the instruction pointer (address), as in prior
47 versions of babeltrace.
48
49 Getting the Right Tracer
50 ------------------------
51
52 Debug info analysis is performed automatically by babeltrace, provided
53 the trace contains sufficient information. In order to be able to
54 trace all the necessary information, the following software is
55 required:
56
57 * lttng-ust version 2.8.0 or later
58 * lttng-tools, corresponding version
59
60 You can get these from source at:
61
62 * https://github.com/lttng/lttng-ust
63 * https://github.com/lttng/lttng-tools
64
65 Ubuntu users also have the option of installing via the LTTng daily
66 PPA:
67
68 * https://launchpad.net/~lttng/+archive/ubuntu/daily
69
70 Tracing for Debug Info Analysis
71 -------------------------------
72
73 Babeltrace needs some extra information from contexts, namely ip and
74 vpid, to perform its analysis. These can be enabled after the creation
75 of a tracing session as follows:
76
77 $ lttng add-context --userspace --type ip --type vpid
78
79 The tracing can then be performed as it normally would. Once the trace
80 is collected, it can the be read by babeltrace for analysis.
81
82 Analysing the Trace
83 -------------------
84
85 To perform the analysis, the trace can simply be read as it normally
86 would:
87
88 $ babeltrace <path/to/trace>
89
90 Debug info analysis is on by default and will automatically print the
91 extra source location information if it can find it. A sample output
92 may look like this:
93
94 [...]
95 [19:53:41.648394410] (+0.000022616) colossus my_provider:my_first_tracepoint: { cpu_id = 2 }, { ip = 0x7F75AEDFB4D4, debug_info = { func = "foo", source_loc = "/home/efficios/example/libhello.c:7" }, vpid = 25577 }, { my_string_field = "hello, tracer", my_integer_field = 42 }
96 [19:53:41.648423786] (+0.000029376) colossus my_provider:my_first_tracepoint: { cpu_id = 2 }, { ip = 0x7F75AEDFB5A6, debug_info = { func = "bar", source_loc = "/home/efficios/example/libhello.c:13" }, vpid = 25577 }, { my_string_field = "recoltes et semailles", my_integer_field = 57 }
97 [19:53:41.648435726] (+0.000011940) colossus my_provider:my_other_tracepoint: { cpu_id = 2 }, { ip = 0x7F75AEDFB66B, debug_info = { func = "baz", source_loc = "/home/efficios/example/libhello.c:20" }, vpid = 25577 }, { some_field = 1729 }
98 [...]
99
100 The interesting part is the debug_info section of the context:
101
102 debug_info = { func = "foo", source_loc = "/home/efficios/example/libhello.c:7" }
103
104 This is the expected output for events generated by an executable for
105 which DWARF information is available. It shows the name of the
106 function containing the tracepoint instance which generated the event
107 ("foo"), and its source location ("libhello.c", line 7).
108
109 The second event in the sample output is of the same type
110 ("my_first_tracepoint"), but it was generated by a different
111 tracepoint instance, hence the different source location (line 13) and
112 function ("bar").
113
114 The third event, of a different type, also shows debug information.
115
116 If DWARF info is absent, but ELF symbols are not stripped, the output
117 will instead look like this:
118
119 [...]
120 [19:53:41.648394410] (+0.000022616) colossus my_provider:my_first_tracepoint: { cpu_id = 2 }, { ip = 0x7F75AEDFB4D4, debug_info = { func = "foo+0xa9" }, vpid = 25577 }, { my_string_field = "hello, tracer", my_integer_field = 42 }
121 [19:53:41.648423786] (+0.000029376) colossus my_provider:my_first_tracepoint: { cpu_id = 2 }, { ip = 0x7F75AEDFB5A6, debug_info = { func = "bar+0xa9" }, vpid = 25577 }, { my_string_field = "recoltes et semailles", my_integer_field = 57 }
122 [19:53:41.648435726] (+0.000011940) colossus my_provider:my_other_tracepoint: { cpu_id = 2 }, { ip = 0x7F75AEDFB66B, debug_info = { func = "baz+0x9c" }, vpid = 25577 }, { some_field = 1729 }
123 [...]
124
125 The debug information now provides only the function name as given by
126 ELF symbols, plus an offset in bytes from the symbol to the actual
127 location of the tracepoint instance.
128
129 Debug Info and Dynamic Loading
130 ------------------------------
131
132 Babeltrace can resolve addresses of events originating from
133 dynamically loaded libraries, provided that some extra information is
134 collected at tracing time.
135
136 This can be achieved by preloading LTTng UST's libdl helper when
137 launching the program to be traced, like so:
138
139 $ LD_PRELOAD="liblttng-ust-dl.so" <path/to/executable>
140
141 The tracing and analysis can now be performed as described in prior
142 sections, and events from tracepoints in dlopened libraries will be
143 resolved automatically by babeltrace.
144
145 Separate Debug Info
146 -------------------
147
148 It is possible to store DWARF debug information separate from an
149 executable, whether for concerns of file size, or simply to facilitate
150 the sharing of the debug information.
151
152 This is usually achieved via one of two mechanisms, namely build ID
153 and debug link. Both methods permit separate executables and debug
154 information. Their use and operation is described in GDB's
155 documentation at:
156
157 https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html
158
159 Babeltrace will find separate debug files automatically, provided they
160 follow the requirements described in the documentation above. The
161 debug information lookup order is the same as GDB's, that is first
162 debug info is looked for within the executable, then through the build
163 ID method in the standard /usr/lib/debug/.build-id/ location, and
164 finally in the various possible debug link locations. The first debug
165 information file found is used.
166
167 Debug Info Directory
168 --------------------
169
170 When performing debug info analysis, babeltrace uses an executable's
171 path from when it was traced to resolve debug information. If,
172 however, the trace was taken on a different machine, or the executable
173 was simply moved since the trace was taken, it is possible to override
174 the base path from which to look for the debug information. To do so,
175 the --debug-info-dir babeltrace command-line flag is available.
176
177 If a --debug-info-dir value is given, it will replace the default
178 /usr/lib/debug path used in build ID and debug link lookups.
179
180 Note that multiple debug directories are not currently supported.
This page took 0.032314 seconds and 4 git commands to generate.