Commit | Line | Data |
---|---|---|
e70712b3 | 1 | = babeltrace2-filter.lttng-utils.debug-info(7) |
0659f3af | 2 | :manpagetype: component class |
e70712b3 PP |
3 | :revdate: 14 September 2019 |
4 | :compcls: compcls:filter.lttng-utils.debug-info | |
0659f3af PP |
5 | :defdebuginfoname: `debug_info` |
6 | ||
7 | ||
e70712b3 PP |
8 | == NAME |
9 | ||
10 | babeltrace2-filter.lttng-utils.debug-info - Babeltrace 2's debugging | |
0659f3af PP |
11 | information filter component class for LTTng traces |
12 | ||
13 | ||
e70712b3 PP |
14 | == DESCRIPTION |
15 | ||
16 | A Babeltrace~2 {compcls} message iterator creates and emits copies of | |
17 | upstream messages, augmenting LTTng event messages with debugging | |
18 | information when it's available and possible. | |
19 | ||
20 | ---- | |
21 | Messages without | |
22 | debugging information | |
23 | | | |
24 | | +----------------------------+ | |
25 | | | flt.lttng-utils.debug-info | | |
26 | | | | | |
27 | '->@ in out @--> Messages with | |
28 | +----------------------------+ debugging information | |
29 | ---- | |
30 | ||
31 | include::common-see-babeltrace2-intro.txt[] | |
32 | ||
33 | A {compcls} message iterator uses the LTTng state dump events as well as | |
34 | the event common context's `ip` (instruction pointer) and `vpid` | |
35 | (process ID) fields to locate and read the corresponding debugging | |
36 | information. The message iterator can find the extra debugging | |
37 | information in an executable file or in a directory containing debugging | |
38 | information which the compiler creates. | |
39 | ||
40 | The new LTTng events (copies of the original ones with added debugging | |
41 | information) contain, when possible, a new event common context's | |
42 | structure field (besides the `ip` field) named {defdebuginfoname} by | |
43 | default (you can use the param:debug-info-field-name parameter to choose | |
44 | another name). This structure field contains the following fields: | |
45 | ||
46 | `bin` vtype:[string]:: | |
47 | Executable path or name followed with `@ADDR` or `+ADDR`, where | |
48 | `ADDR` is the address (hexadecimal) where it was loaded while being | |
49 | traced. | |
50 | + | |
51 | `@ADDR` means `ADDR` is an absolute address, and `+ADDR` means `ADDR` is | |
52 | a relative address. | |
0659f3af | 53 | + |
e70712b3 | 54 | Examples: `my-program@0x4b7fdd23`, `my-program+0x18d7c`. |
0659f3af | 55 | |
e70712b3 PP |
56 | [[field-func]]`func` vtype:[string]:: |
57 | Function name followed with `+OFFSET`, where `OFFSET` is the offset | |
58 | (hexadecimal) from the beginning of the function symbol in the | |
59 | executable file. | |
0659f3af PP |
60 | + |
61 | Example: `load_user_config+0x194`. | |
62 | ||
e70712b3 PP |
63 | [[field-src]]`src` vtype:[string]:: |
64 | Source file path or name followed with `:LINE`, where `LINE` is the | |
118ae153 | 65 | line number in this source file at which the event occurred. |
0659f3af PP |
66 | + |
67 | Example: `user-config.c:1025`. | |
68 | ||
e70712b3 PP |
69 | Any of the previous fields can be an empty string if the debugging |
70 | information was not available for the analyzed original LTTng event. | |
0659f3af | 71 | |
e70712b3 PP |
72 | A {compcls} message iterator systematically copies the upstream |
73 | messages, but it only augments compatible LTTng event classes. This | |
74 | means that the message iterator copies messages of non-LTTng trace (see | |
75 | <<lttng-prereq,``LTTng prerequisites''>>) without alteration. | |
0659f3af PP |
76 | |
77 | ||
e70712b3 PP |
78 | === Compile an executable for debugging information analysis |
79 | ||
80 | With GCC or Clang, you need to compile the program or library source | |
0659f3af PP |
81 | files in debug mode with the nlopt:-g option. This option makes the |
82 | compiler generate debugging information in the operating system's native | |
e70712b3 PP |
83 | format. This format is recognized by a {compcls} component: it can |
84 | translate the instruction pointer field of an event's common context to | |
85 | a source file and line number, along with the name of the surrounding | |
0659f3af PP |
86 | function. |
87 | ||
e70712b3 PP |
88 | IMPORTANT: This component class only supports the debugging information |
89 | in DWARF format, version~2 or later. Use the nlopt:-gdwarf or | |
0659f3af PP |
90 | nlopt:-gdwarf-VERSION (where `VERSION` is the DWARF version) compiler |
91 | options to explicitly generate DWARF debugging information. | |
92 | ||
93 | If you don't compile the executable's source files with the nlopt:-g | |
94 | option or with an equivalent option, no DWARF information is available: | |
e70712b3 PP |
95 | the message iterator uses ELF symbols from the executable file instead. |
96 | In this case, the events that the message iterator creates do not | |
97 | contain the source file and line number (see the <<field-src,`src` | |
98 | field>>), but only the name of the nearest function symbol with an | |
99 | offset in bytes to the location in the executable from which the LTTng | |
118ae153 | 100 | event occurred (see the <<field-func,`func` field>>). |
0659f3af PP |
101 | |
102 | If the executable file has neither ELF symbols nor DWARF information, | |
e70712b3 PP |
103 | the {compcls} message iterator cannot map the event to its source |
104 | location: the message iterator still copies the upstream messages but | |
105 | without altering them. | |
106 | ||
0659f3af | 107 | |
e70712b3 PP |
108 | [[lttng-prereq]] |
109 | === LTTng prerequisites | |
0659f3af | 110 | |
e70712b3 PP |
111 | A {compcls} message iterator can only analyze user space events which |
112 | https://lttng.org[LTTng]~2.8.0 or later generates. | |
0659f3af | 113 | |
a4c4205a PP |
114 | To get debugging information for LTTng-UST events which occur in |
115 | executables and libraries which the system's loader loads (what | |
116 | you can see with man:ldd(1)): | |
0659f3af | 117 | |
a4c4205a PP |
118 | . Add the `ip` and `vpid` context fields to user space event records: |
119 | + | |
120 | -- | |
0659f3af PP |
121 | [role="term"] |
122 | ---- | |
123 | $ lttng add-context --userspace --type=ip --type=vpid | |
124 | ---- | |
a4c4205a PP |
125 | -- |
126 | + | |
127 | See man:lttng-add-context(1) for more details. | |
0659f3af | 128 | |
a4c4205a PP |
129 | . Enable the LTTng-UST state dump events: |
130 | + | |
131 | -- | |
132 | [role="term"] | |
133 | ---- | |
134 | $ lttng enable-event --userspace 'lttng_ust_statedump:*' | |
135 | ---- | |
136 | -- | |
137 | + | |
138 | See man:lttng-enable-event(1) and man:lttng-ust(3) for more details. | |
0659f3af PP |
139 | |
140 | To get debugging information for LTTng-UST events which occur in | |
a4c4205a | 141 | dynamically loaded objects, for example plugins: |
0659f3af | 142 | |
a4c4205a PP |
143 | . Do the previous steps (add context fields and enable |
144 | the LTTng-UST state dump events). | |
145 | ||
146 | . Enable the LTTng-UST dynamic linker tracing helper events: | |
147 | + | |
148 | -- | |
0659f3af PP |
149 | [role="term"] |
150 | ---- | |
a4c4205a | 151 | $ lttng enable-event --userspace 'lttng_ust_dl:*' |
0659f3af | 152 | ---- |
a4c4205a PP |
153 | -- |
154 | + | |
155 | See man:lttng-ust-dl(3) for more details. | |
0659f3af | 156 | |
a4c4205a PP |
157 | . When you are ready to trace, start your application with the |
158 | `LD_PRELOAD` environment variable set to `liblttng-ust-dl.so`: | |
159 | + | |
160 | -- | |
161 | [role="term"] | |
162 | ---- | |
163 | $ LD_PRELOAD=liblttng-ust-dl.so my-app | |
164 | ---- | |
165 | -- | |
0659f3af PP |
166 | |
167 | ||
e70712b3 PP |
168 | === Separate debugging information |
169 | ||
170 | You can store DWARF debugging information outside the executable itself, | |
171 | whether it is to reduce the executable's file size or simply to | |
172 | facilitate sharing the debugging information. | |
0659f3af PP |
173 | |
174 | This is usually achieved via one of two mechanisms, namely _build ID_ | |
175 | and _debug link_. Their use and operation is described in the | |
176 | https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html[Debugging | |
177 | Information in Separate Files] section of GDB's documentation. | |
178 | ||
e70712b3 PP |
179 | A {compcls} message iterator can find separate debugging information |
180 | files automatically, as long as they meet the requirements stated in | |
181 | this manual page. | |
0659f3af PP |
182 | |
183 | The debugging information lookup order is the same as GDB's, namely: | |
184 | ||
185 | . Within the executable file itself. | |
186 | ||
187 | . Through the build ID method in the `/usr/lib/debug/.build-id` | |
188 | directory. | |
189 | ||
190 | . In the various possible debug link locations. | |
191 | ||
e70712b3 PP |
192 | The message iterator uses the first debugging information file that it |
193 | finds. | |
0659f3af | 194 | |
e70712b3 | 195 | You can use the param:debug-info-dir initialization parameter to |
0659f3af PP |
196 | override the default `/usr/lib/debug` directory used in the build ID and |
197 | debug link methods. | |
198 | ||
199 | NOTE: It is currently not possible to make this component search for | |
200 | debugging information in multiple directories. | |
201 | ||
202 | ||
e70712b3 PP |
203 | === Target prefix |
204 | ||
205 | The debugging information analysis that a {compcls} message iterator | |
206 | performs uses the paths to the executables as collected during tracing | |
207 | as the default mechanism to resolve DWARF and ELF information. | |
0659f3af PP |
208 | |
209 | If the trace was recorded on a separate machine, however, you can use | |
210 | the param:target-prefix parameter to specify a prefix directory, that | |
211 | is, the root of the target file system. | |
212 | ||
213 | For example, if an instrumented executable's path is `/usr/bin/foo` on | |
214 | the target system, you can place this file at | |
e70712b3 PP |
215 | `/home/user/target/usr/bin/foo` on the system on which you use a |
216 | {compcls} component. In this case, the target prefix to use is | |
0659f3af PP |
217 | `/home/user/target`. |
218 | ||
219 | ||
e70712b3 | 220 | == INITIALIZATION PARAMETERS |
0659f3af | 221 | |
e70712b3 | 222 | param:debug-info-dir='DIR' vtype:[optional string]:: |
0659f3af PP |
223 | Use 'DIR' as the directory from which to load debugging information |
224 | with the build ID and debug link methods instead of | |
225 | `/usr/lib/debug`. | |
226 | ||
e70712b3 PP |
227 | param:debug-info-field-name='NAME' vtype:[optional string]:: |
228 | Name the debugging information structure field in the common context | |
229 | of the created events 'NAME' instead of the default | |
230 | {defdebuginfoname}. | |
0659f3af | 231 | |
e70712b3 | 232 | param:full-path=`yes` vtype:[optional boolean]:: |
0659f3af PP |
233 | Use the full path when writing the executable name (`bin`) and |
234 | source file name (`src`) fields in the {defdebuginfoname} context | |
235 | field of the created events. | |
236 | ||
e70712b3 | 237 | param:target-prefix='DIR' vtype:[optional string]:: |
0659f3af PP |
238 | Use 'DIR' as the root directory of the target file system instead of |
239 | `/`. | |
240 | ||
241 | ||
e70712b3 | 242 | == PORTS |
0659f3af | 243 | |
e70712b3 PP |
244 | ---- |
245 | +----------------------------+ | |
246 | | flt.lttng-utils.debug-info | | |
247 | | | | |
248 | @ in out @ | |
249 | +----------------------------+ | |
250 | ---- | |
0659f3af | 251 | |
0659f3af | 252 | |
e70712b3 | 253 | === Input |
0659f3af | 254 | |
e70712b3 PP |
255 | `in`:: |
256 | Single input port. | |
0659f3af PP |
257 | |
258 | ||
e70712b3 | 259 | === Output |
0659f3af | 260 | |
e70712b3 PP |
261 | `out`:: |
262 | Single output port. | |
0659f3af PP |
263 | |
264 | ||
265 | include::common-footer.txt[] | |
266 | ||
267 | ||
e70712b3 PP |
268 | == SEE ALSO |
269 | ||
270 | man:babeltrace2-intro(7), | |
a8be4294 | 271 | man:babeltrace2-plugin-lttng-utils(7), |
0659f3af | 272 | man:lttng(1), |
e70712b3 | 273 | man:lttng-add-context(1) |