babeltrace2-filter.lttng-utils.debug-info(7)

1BABELTRACE2-FILTER()                                      BABELTRACE2-FILTER()
2
3
4

NAME

6       babeltrace2-filter.lttng-utils.debug-info - Babeltrace 2's debugging
7       information filter component class for LTTng traces
8

DESCRIPTION

10       A Babeltrace 2 filter.lttng-utils.debug-info message iterator creates
11       and emits copies of upstream messages, augmenting LTTng event messages
12       with debugging information when it’s available and possible.
13
14           Messages without
15           debugging information
16             |
17             |  +----------------------------+
18             |  | flt.lttng-utils.debug-info |
19             |  |                            |
20             '->@ in                     out @--> Messages with
21                +----------------------------+    debugging information
22
23       See babeltrace2-intro(7) to learn more about the Babeltrace 2 project
24       and its core concepts.
25
26       A filter.lttng-utils.debug-info message iterator uses the LTTng state
27       dump events as well as the event common context’s ip (instruction
28       pointer) and vpid (process ID) fields to locate and read the
29       corresponding debugging information. The message iterator can find the
30       extra debugging information in an executable file or in a directory
31       containing debugging information which the compiler creates.
32
33       The new LTTng events (copies of the original ones with added debugging
34       information) contain, when possible, a new event common context’s
35       structure field (besides the ip field) named debug_info by default (you
36       can use the debug-info-field-name parameter to choose another name).
37       This structure field contains the following fields:
38
39       bin [string]
40           Executable path or name followed with @ADDR or +ADDR, where ADDR is
41           the address (hexadecimal) where it was loaded while being traced.
42
43           @ADDR means ADDR is an absolute address, and +ADDR means ADDR is a
44           relative address.
45
46           Examples: my-program@0x4b7fdd23, my-program+0x18d7c.
47
48       func [string]
49           Function name followed with +OFFSET, where OFFSET is the offset
50           (hexadecimal) from the beginning of the function symbol in the
51           executable file.
52
53           Example: load_user_config+0x194.
54
55       src [string]
56           Source file path or name followed with :LINE, where LINE is the
57           line number in this source file at which the event occurred.
58
59           Example: user-config.c:1025.
60
61       Any of the previous fields can be an empty string if the debugging
62       information was not available for the analyzed original LTTng event.
63
64       A filter.lttng-utils.debug-info message iterator systematically copies
65       the upstream messages, but it only augments compatible LTTng event
66       classes. This means that the message iterator copies messages of
67       non-LTTng trace (see “LTTng prerequisites”) without alteration.
68
69   Compile an executable for debugging information analysis
70       With GCC or Clang, you need to compile the program or library source
71       files in debug mode with the -g option. This option makes the compiler
72       generate debugging information in the operating system’s native format.
73       This format is recognized by a filter.lttng-utils.debug-info component:
74       it can translate the instruction pointer field of an event’s common
75       context to a source file and line number, along with the name of the
76       surrounding function.
77
78           Important
79           This component class only supports the debugging information in
80           DWARF format, version 2 or later. Use the -gdwarf or -gdwarf-
81           VERSION (where VERSION is the DWARF version) compiler options to
82           explicitly generate DWARF debugging information.
83
84       If you don’t compile the executable’s source files with the -g option
85       or with an equivalent option, no DWARF information is available: the
86       message iterator uses ELF symbols from the executable file instead. In
87       this case, the events that the message iterator creates do not contain
88       the source file and line number (see the src field), but only the name
89       of the nearest function symbol with an offset in bytes to the location
90       in the executable from which the LTTng event occurred (see the func
91       field).
92
93       If the executable file has neither ELF symbols nor DWARF information,
94       the filter.lttng-utils.debug-info message iterator cannot map the event
95       to its source location: the message iterator still copies the upstream
96       messages but without altering them.
97
98   LTTng prerequisites
99       A filter.lttng-utils.debug-info message iterator can only analyze user
100       space events which LTTng (see <https://lttng.org>) 2.8.0 or later
101       generates.
102
103       To get debugging information for LTTng-UST events which occur in
104       executables and libraries which the system’s loader loads (what you can
105       see with ldd(1)):
106
107        1. Add the ip and vpid context fields to user space event records:
108
109               $ lttng add-context --userspace --type=ip --type=vpid
110
111           See lttng-add-context(1) for more details.
112
113        2. Enable the LTTng-UST state dump events:
114
115               $ lttng enable-event --userspace 'lttng_ust_statedump:*'
116
117           See lttng-enable-event(1) and lttng-ust(3) for more details.
118
119       To get debugging information for LTTng-UST events which occur in
120       dynamically loaded objects, for example plugins:
121
122        1. Do the previous steps (add context fields and enable the LTTng-UST
123           state dump events).
124
125        2. Enable the LTTng-UST dynamic linker tracing helper events:
126
127               $ lttng enable-event --userspace 'lttng_ust_dl:*'
128
129           See lttng-ust-dl(3) for more details.
130
131        3. When you are ready to trace, start your application with the
132           LD_PRELOAD environment variable set to liblttng-ust-dl.so:
133
134               $ LD_PRELOAD=liblttng-ust-dl.so my-app
135
136   Separate debugging information
137       You can store DWARF debugging information outside the executable
138       itself, whether it is to reduce the executable’s file size or simply to
139       facilitate sharing the debugging information.
140
141       This is usually achieved via one of two mechanisms, namely build ID and
142       debug link. Their use and operation is described in the Debugging
143       Information in Separate Files (see
144       <https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html>)
145       section of GDB’s documentation.
146
147       A filter.lttng-utils.debug-info message iterator can find separate
148       debugging information files automatically, as long as they meet the
149       requirements stated in this manual page.
150
151       The debugging information lookup order is the same as GDB’s, namely:
152
153        1. Within the executable file itself.
154
155        2. Through the build ID method in the /usr/lib/debug/.build-id
156           directory.
157
158        3. In the various possible debug link locations.
159
160       The message iterator uses the first debugging information file that it
161       finds.
162
163       You can use the debug-info-dir initialization parameter to override the
164       default /usr/lib/debug directory used in the build ID and debug link
165       methods.
166
167           Note
168           It is currently not possible to make this component search for
169           debugging information in multiple directories.
170
171   Target prefix
172       The debugging information analysis that a filter.lttng-utils.debug-info
173       message iterator performs uses the paths to the executables as
174       collected during tracing as the default mechanism to resolve DWARF and
175       ELF information.
176
177       If the trace was recorded on a separate machine, however, you can use
178       the target-prefix parameter to specify a prefix directory, that is, the
179       root of the target file system.
180
181       For example, if an instrumented executable’s path is /usr/bin/foo on
182       the target system, you can place this file at
183       /home/user/target/usr/bin/foo on the system on which you use a
184       filter.lttng-utils.debug-info component. In this case, the target
185       prefix to use is /home/user/target.
186

INITIALIZATION PARAMETERS

188       debug-info-dir=DIR [optional string]
189           Use DIR as the directory from which to load debugging information
190           with the build ID and debug link methods instead of /usr/lib/debug.
191
192       debug-info-field-name=NAME [optional string]
193           Name the debugging information structure field in the common
194           context of the created events NAME instead of the default
195           debug_info.
196
197       full-path=yes [optional boolean]
198           Use the full path when writing the executable name (bin) and source
199           file name (src) fields in the debug_info context field of the
200           created events.
201
202       target-prefix=DIR [optional string]
203           Use DIR as the root directory of the target file system instead of
204           /.
205

PORTS

207           +----------------------------+
208           | flt.lttng-utils.debug-info |
209           |                            |
210           @ in                     out @
211           +----------------------------+
212
213   Input
214       in
215           Single input port.
216
217   Output
218       out
219           Single output port.
220

BUGS

222       If you encounter any issue or usability problem, please report it on
223       the Babeltrace bug tracker (see
224       <https://bugs.lttng.org/projects/babeltrace>).
225

RESOURCES

227       The Babeltrace project shares some communication channels with the
228       LTTng project (see <https://lttng.org/>).
229
230       •   Babeltrace website (see <https://babeltrace.org/>)
231
232       •   Mailing list (see <https://lists.lttng.org>) for support and
233           development: lttng-dev@lists.lttng.org
234
235       •   IRC channel (see <irc://irc.oftc.net/lttng>): #lttng on
236           irc.oftc.net
237
238       •   Bug tracker (see <https://bugs.lttng.org/projects/babeltrace>)
239
240       •   Git repository (see <https://git.efficios.com/?p=babeltrace.git>)
241
242       •   GitHub project (see <https://github.com/efficios/babeltrace>)
243
244       •   Continuous integration (see
245           <https://ci.lttng.org/view/Babeltrace/>)
246
247       •   Code review (see <https://review.lttng.org/q/project:babeltrace>)
248

AUTHORS

250       The Babeltrace 2 project is the result of hard work by many regular
251       developers and occasional contributors.
252
253       The current project maintainer is Jérémie Galarneau
254       <mailto:jeremie.galarneau@efficios.com>.
255

COPYRIGHT

257       This component class is part of the Babeltrace 2 project.
258
259       Babeltrace is distributed under the MIT license (see
260       <https://opensource.org/licenses/MIT>).
261