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