Commit | Line | Data |
---|---|---|
838dd456 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 | ||
100 | The filter component needs the LTTng-UST events to contain the | |
101 | `ip` and `vpid` fields in their context. | |
102 | ||
103 | To add those context fields with the man:lttng(1) command-line tool | |
104 | before the tracers are active (before `lttng start`): | |
105 | ||
106 | [role="term"] | |
107 | ---- | |
108 | $ lttng add-context --userspace --type=ip --type=vpid | |
109 | ---- | |
110 | ||
111 | See man:lttng-add-context(1) for more information. | |
112 | ||
113 | To get debugging information for LTTng-UST events which occur in | |
114 | dynamically loaded objects, for example plugins, start the application | |
115 | to trace with the LTTng-UST dynamic linking helper: | |
116 | ||
117 | [role="term"] | |
118 | ---- | |
119 | $ LD_PRELOAD=liblttng-ust-dl.so my-app | |
120 | ---- | |
121 | ||
122 | See man:lttng-ust-dl(3) for more information. | |
123 | ||
124 | ||
125 | Separate debugging information | |
126 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
127 | It is possible to store DWARF debugging information outside the | |
128 | executable itself, whether it is to reduce the executable's file size, | |
129 | or simply to facilitate the sharing of the debugging information. | |
130 | ||
131 | This is usually achieved via one of two mechanisms, namely _build ID_ | |
132 | and _debug link_. Their use and operation is described in the | |
133 | https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html[Debugging | |
134 | Information in Separate Files] section of GDB's documentation. | |
135 | ||
136 | A {comp} component can find separate debugging information files | |
137 | automatically, as long as they meet the requirements stated in this man | |
138 | page. | |
139 | ||
140 | The debugging information lookup order is the same as GDB's, namely: | |
141 | ||
142 | . Within the executable file itself. | |
143 | ||
144 | . Through the build ID method in the `/usr/lib/debug/.build-id` | |
145 | directory. | |
146 | ||
147 | . In the various possible debug link locations. | |
148 | ||
149 | The component uses the first debugging information file that it finds. | |
150 | ||
151 | You can use the param:deubg-info-dir initialization parameter to | |
152 | override the default `/usr/lib/debug` directory used in the build ID and | |
153 | debug link methods. | |
154 | ||
155 | NOTE: It is currently not possible to make this component search for | |
156 | debugging information in multiple directories. | |
157 | ||
158 | ||
159 | Target prefix | |
160 | ~~~~~~~~~~~~~ | |
161 | The debugging information analysis that a {comp} component performs uses | |
162 | the paths to the executables as collected during tracing as the default | |
163 | mechanism to resolve DWARF and ELF information. | |
164 | ||
165 | If the trace was recorded on a separate machine, however, you can use | |
166 | the param:target-prefix parameter to specify a prefix directory, that | |
167 | is, the root of the target file system. | |
168 | ||
169 | For example, if an instrumented executable's path is `/usr/bin/foo` on | |
170 | the target system, you can place this file at | |
171 | `/home/user/target/usr/bin/foo` on the system on which you use the | |
172 | component. In this case, the target prefix to use is | |
173 | `/home/user/target`. | |
174 | ||
175 | ||
176 | INITIALIZATION PARAMETERS | |
177 | ------------------------- | |
178 | The following parameters are optional. | |
179 | ||
180 | param:debug-info-dir='DIR' (string):: | |
181 | Use 'DIR' as the directory from which to load debugging information | |
182 | with the build ID and debug link methods instead of | |
183 | `/usr/lib/debug`. | |
184 | ||
185 | param:debug-info-field-name='NAME' (string):: | |
186 | Name the debugging information structure field in the context of | |
187 | the created events 'NAME' instead of the default {defdebuginfoname}. | |
188 | ||
189 | param:full-path=`yes` (boolean):: | |
190 | Use the full path when writing the executable name (`bin`) and | |
191 | source file name (`src`) fields in the {defdebuginfoname} context | |
192 | field of the created events. | |
193 | ||
194 | param:target-prefix='DIR' (string):: | |
195 | Use 'DIR' as the root directory of the target file system instead of | |
196 | `/`. | |
197 | ||
198 | ||
199 | PORTS | |
200 | ----- | |
201 | Input | |
202 | ~~~~~ | |
203 | `in`:: | |
204 | Single input port from which the component receives the | |
205 | notifications to augment with debugging information. | |
206 | ||
207 | ||
208 | Output | |
209 | ~~~~~~ | |
210 | `out`:: | |
211 | Single output port to which the component sends the augmented | |
212 | or unaltered notifications. | |
213 | ||
214 | ||
215 | QUERY OBJECTS | |
216 | ------------- | |
217 | This component class has no objects to query. | |
218 | ||
219 | ||
220 | ENVIRONMENT VARIABLES | |
221 | --------------------- | |
222 | include::common-common-compat-env.txt[] | |
223 | ||
224 | `BABELTRACE_FLT_LTTNG_UTILS_DEBUG_INFO_LOG_LEVEL`:: | |
225 | Component class's log level. The available values are the | |
226 | same as for the manopt:babeltrace(1):--log-level option of | |
227 | man:babeltrace(1). | |
228 | ||
229 | ||
230 | include::common-footer.txt[] | |
231 | ||
232 | ||
233 | SEE ALSO | |
234 | -------- | |
235 | man:babeltrace-plugin-lttng-utils(7), | |
236 | man:lttng(1), | |
237 | man:lttng-add-context(1), | |
238 | man:babeltrace-intro(7) |