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