X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;f=doc%2Fman%2Fbabeltrace2-filter.lttng-utils.debug-info.7.txt;fp=doc%2Fman%2Fbabeltrace2-filter.lttng-utils.debug-info.7.txt;h=ca05d708e5ff50ba9f759db247c261082c6f3dc0;hb=a8be4294fc84cc1b81b1690412c22c9e06cdb8e3;hp=0000000000000000000000000000000000000000;hpb=3fadfbc0c91f82c46bd36e6e0657ea93570c9db1;p=babeltrace.git diff --git a/doc/man/babeltrace2-filter.lttng-utils.debug-info.7.txt b/doc/man/babeltrace2-filter.lttng-utils.debug-info.7.txt new file mode 100644 index 00000000..ca05d708 --- /dev/null +++ b/doc/man/babeltrace2-filter.lttng-utils.debug-info.7.txt @@ -0,0 +1,267 @@ +babeltrace2-filter.lttng-utils.debug-info(7) +=========================================== +:manpagetype: component class +:revdate: 5 October 2017 +:comp: compcls:filter.lttng-utils.debug-info +:defdebuginfoname: `debug_info` + + +NAME +---- +babeltrace2-filter.lttng-utils.debug-info - Babeltrace's debugging +information filter component class for LTTng traces + + +DESCRIPTION +----------- +The Babeltrace {comp} component class, provided by the the +man:babeltrace2-plugin-lttng-utils(7) plugin, once instantiated, receives +events from http://lttng.org/[LTTng] traces and creates new ones +which are copies of the original ones with extra debugging information +when it's available and possible. + +A {comp} component uses the LTTng state dump events as well as the event +context's `ip` (instruction pointer) field to locate and read the +corresponding debugging information. The component can find the extra +debugging information in an executable file or in a directory containing +debugging information created by the compiler. + +The new events contain the exact same fields as the original ones and, +when possible, a new event context's structure field (besides the `ip` +field) named {defdebuginfoname} by default. This structure field +contains the following fields: + +`bin` (string field):: + Executable path or name followed by `@ADDR` or `+ADDR`, where + `ADDR` is the address where it was loaded while being traced. + `@ADDR` means `ADDR` is an absolute address, and `+ADDR` means + `ADDR` is a relative address. ++ +Example: `my-program@0x401040`. + +[[field-func]]`func` (string field):: + Function name followed by `+OFFSET`, where `OFFSET` is the + offset from the beginning of the function symbol in the executable + file. ++ +Example: `load_user_config+0x194`. + +[[field-src]]`src` (string field):: + Source file path or name followed by `:LINE`, where `LINE` is the + line number in this source file at which the event occured. ++ +Example: `user-config.c:1025`. + +Any of those the previous fields can be an empty string if the +debugging information was not available for the analyzed original +LTTng event. + +When a filter component creates a new event with debugging +information, it discards the original event. If the component receives a +non-LTTng event, the component moves the event to its output port +without alteration. + + +Compile an executable for debugging information analysis +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +With GCC or Clang, you should compile the program or library source +files in debug mode with the nlopt:-g option. This option makes the +compiler generate debugging information in the operating system's native +format. This format is recognized by a {comp} component: it can +translate the instruction pointer field of an event's context to a +source file and line number, along with the name of the surrounding +function. + +NOTE: This component class only supports the debugging information in +DWARF format, version{nbsp}2 or later. Use the nlopt:-gdwarf or +nlopt:-gdwarf-VERSION (where `VERSION` is the DWARF version) compiler +options to explicitly generate DWARF debugging information. + +If you don't compile the executable's source files with the nlopt:-g +option or with an equivalent option, no DWARF information is available: +the component uses ELF symbols from the executable file instead. In this +case, the events that the component creates do not contain the source +file and line number (<>), but only the name of +the nearest function symbol with an offset in bytes to the location in +the executable from which the LTTng event occured (<>). + +If the executable file has neither ELF symbols nor DWARF information, +the {comp} component cannot map the event to +its source location: it emits the original LTTng event which has no +special {defdebuginfoname} context field. + + +LTTng prerequisites +~~~~~~~~~~~~~~~~~~~ +A {comp} component can only analyze user space events generated by +http://lttng.org[LTTng]{nbsp}2.8.0 or later. + +To get debugging information for LTTng-UST events which occur in +executables and libraries which the system's loader loads (what +you can see with man:ldd(1)): + +. Add the `ip` and `vpid` context fields to user space event records: ++ +-- +[role="term"] +---- +$ lttng add-context --userspace --type=ip --type=vpid +---- +-- ++ +See man:lttng-add-context(1) for more details. + +. Enable the LTTng-UST state dump events: ++ +-- +[role="term"] +---- +$ lttng enable-event --userspace 'lttng_ust_statedump:*' +---- +-- ++ +See man:lttng-enable-event(1) and man:lttng-ust(3) for more details. + +To get debugging information for LTTng-UST events which occur in +dynamically loaded objects, for example plugins: + +. Do the previous steps (add context fields and enable + the LTTng-UST state dump events). + +. Enable the LTTng-UST dynamic linker tracing helper events: ++ +-- +[role="term"] +---- +$ lttng enable-event --userspace 'lttng_ust_dl:*' +---- +-- ++ +See man:lttng-ust-dl(3) for more details. + +. When you are ready to trace, start your application with the + `LD_PRELOAD` environment variable set to `liblttng-ust-dl.so`: ++ +-- +[role="term"] +---- +$ LD_PRELOAD=liblttng-ust-dl.so my-app +---- +-- + + +Separate debugging information +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +It is possible to store DWARF debugging information outside the +executable itself, whether it is to reduce the executable's file size, +or simply to facilitate the sharing of the debugging information. + +This is usually achieved via one of two mechanisms, namely _build ID_ +and _debug link_. Their use and operation is described in the +https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html[Debugging +Information in Separate Files] section of GDB's documentation. + +A {comp} component can find separate debugging information files +automatically, as long as they meet the requirements stated in this man +page. + +The debugging information lookup order is the same as GDB's, namely: + +. Within the executable file itself. + +. Through the build ID method in the `/usr/lib/debug/.build-id` + directory. + +. In the various possible debug link locations. + +The component uses the first debugging information file that it finds. + +You can use the param:deubg-info-dir initialization parameter to +override the default `/usr/lib/debug` directory used in the build ID and +debug link methods. + +NOTE: It is currently not possible to make this component search for +debugging information in multiple directories. + + +Target prefix +~~~~~~~~~~~~~ +The debugging information analysis that a {comp} component performs uses +the paths to the executables as collected during tracing as the default +mechanism to resolve DWARF and ELF information. + +If the trace was recorded on a separate machine, however, you can use +the param:target-prefix parameter to specify a prefix directory, that +is, the root of the target file system. + +For example, if an instrumented executable's path is `/usr/bin/foo` on +the target system, you can place this file at +`/home/user/target/usr/bin/foo` on the system on which you use the +component. In this case, the target prefix to use is +`/home/user/target`. + + +INITIALIZATION PARAMETERS +------------------------- +The following parameters are optional. + +param:debug-info-dir='DIR' (string):: + Use 'DIR' as the directory from which to load debugging information + with the build ID and debug link methods instead of + `/usr/lib/debug`. + +param:debug-info-field-name='NAME' (string):: + Name the debugging information structure field in the context of + the created events 'NAME' instead of the default {defdebuginfoname}. + +param:full-path=`yes` (boolean):: + Use the full path when writing the executable name (`bin`) and + source file name (`src`) fields in the {defdebuginfoname} context + field of the created events. + +param:target-prefix='DIR' (string):: + Use 'DIR' as the root directory of the target file system instead of + `/`. + + +PORTS +----- +Input +~~~~~ +`in`:: + Single input port from which the component receives the + notifications to augment with debugging information. + + +Output +~~~~~~ +`out`:: + Single output port to which the component sends the augmented + or unaltered notifications. + + +QUERY OBJECTS +------------- +This component class has no objects to query. + + +ENVIRONMENT VARIABLES +--------------------- +include::common-common-compat-env.txt[] + +`BABELTRACE_FLT_LTTNG_UTILS_DEBUG_INFO_LOG_LEVEL`:: + Component class's log level. The available values are the + same as for the manopt:babeltrace2(1):--log-level option of + man:babeltrace2(1). + + +include::common-footer.txt[] + + +SEE ALSO +-------- +man:babeltrace2-plugin-lttng-utils(7), +man:lttng(1), +man:lttng-add-context(1), +man:babeltrace2-intro(7)