lttng-ust-dl(3)

1LTTNG-UST-DL(3)                  LTTng Manual                  LTTNG-UST-DL(3)
2
3
4

NAME

6       lttng-ust-dl - Dynamic linker tracing (LTTng-UST helper)
7

SYNOPSIS

9       Launch your application by preloading liblttng-ust-dl.so:
10
11       $ LD_PRELOAD=liblttng-ust-dl.so my-app
12

DESCRIPTION

14       When the liblttng-ust-dl.so library is preloaded before a given
15       application starts, it causes all calls to dlopen(3) and dlclose(3) in
16       said application to be traced with LTTng-UST (see lttng-ust(3)).
17
18       See lttng(1) to learn more about how to control LTTng tracing sessions.
19
20           Important
21           This LTTng-UST helper can also emit shared library load/unload
22           events (see Shared library load/unload tracking in lttng-ust(3)).
23           You should NOT use the event records generated by this LTTng-UST
24           helper (prefixed with lttng_ust_dl:) to track the loading and
25           unloading of shared libraries, especially in situations where a
26           dynamically loaded library loads its own dependencies. Instead, do
27           preload liblttng-ust-dl.so, but use the shared library load/unload
28           event records, which are more reliable, for your tracking analysis.
29
30       The following LTTng-UST events are available when using this library.
31
32       lttng_ust_dl:dlopen
33           Emitted when dlopen(3) is called.
34
35           Fields:
36
37           ┌───────────────┬────────────────────────────┐
38           │Field name     │ Description                │
39           ├───────────────┼────────────────────────────┤
40           │baddr          │ Base address of loaded     │
41           │               │ library.                   │
42           ├───────────────┼────────────────────────────┤
43           │memsz          │ Size of loaded library in  │
44           │               │ memory.                    │
45           ├───────────────┼────────────────────────────┤
46           │flags          │ Flags passed to dlopen(3). │
47           ├───────────────┼────────────────────────────┤
48           │path           │ Path to loaded library     │
49           │               │ file.                      │
50           ├───────────────┼────────────────────────────┤
51           │has_build_id   │ Whether or not the loaded  │
52           │               │ library has a build ID. If │
53           │               │ this field is 1, you can   │
54           │               │ expect that an             │
55           │               │ lttng_ust_dl:build_id      │
56           │               │ event record follows this  │
57           │               │ one (not necessarily       │
58           │               │ immediately after).        │
59           ├───────────────┼────────────────────────────┤
60           │has_debug_link │ Whether or not the loaded  │
61           │               │ library has debug link     │
62           │               │ information. If this field │
63           │               │ is 1, you can expect that  │
64           │               │ an lttng_ust_dl:debug_link │
65           │               │ event record follows this  │
66           │               │ one (not necessarily       │
67           │               │ immediately after).        │
68           └───────────────┴────────────────────────────┘
69
70       lttng_ust_dl:dlmopen
71           Emitted when dlmopen(3) is called.
72
73           Fields:
74
75           ┌───────────────┬────────────────────────────┐
76           │Field name     │ Description                │
77           ├───────────────┼────────────────────────────┤
78           │baddr          │ Base address of loaded     │
79           │               │ library.                   │
80           ├───────────────┼────────────────────────────┤
81           │memsz          │ Size of loaded library in  │
82           │               │ memory.                    │
83           ├───────────────┼────────────────────────────┤
84           │nsid           │ ID of the namespace in     │
85           │               │ which the library is       │
86           │               │ loaded (as passed to       │
87           │               │ dlmopen(3)).               │
88           ├───────────────┼────────────────────────────┤
89           │flags          │ Flags passed to            │
90           │               │ dlmopen(3).                │
91           ├───────────────┼────────────────────────────┤
92           │path           │ Path to loaded library     │
93           │               │ file.                      │
94           ├───────────────┼────────────────────────────┤
95           │has_build_id   │ Whether or not the loaded  │
96           │               │ library has a build ID. If │
97           │               │ this field is 1, you can   │
98           │               │ expect that an             │
99           │               │ lttng_ust_dl:build_id      │
100           │               │ event record follows this  │
101           │               │ one (not necessarily       │
102           │               │ immediately after).        │
103           ├───────────────┼────────────────────────────┤
104           │has_debug_link │ Whether or not the loaded  │
105           │               │ library has debug link     │
106           │               │ information. If this field │
107           │               │ is 1, you can expect that  │
108           │               │ an lttng_ust_dl:debug_link │
109           │               │ event record follows this  │
110           │               │ one (not necessarily       │
111           │               │ immediately after).        │
112           └───────────────┴────────────────────────────┘
113
114       lttng_ust_dl:dlclose
115           Emitted when dlclose(3) is called.
116
117           Fields:
118
119           ┌───────────┬────────────────────────┐
120           │Field name │ Description            │
121           ├───────────┼────────────────────────┤
122           │baddr      │ Base address of loaded │
123           │           │ library.               │
124           └───────────┴────────────────────────┘
125
126       lttng_ust_dl:debug_link
127           Emitted when debug link information is found when loading a library
128           with dlopen(3). See Debugging Information in Separate Files
129           <https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-
130           Files.html> for more information about debug links.
131
132           Fields:
133
134           ┌───────────┬────────────────────────┐
135           │Field name │ Description            │
136           ├───────────┼────────────────────────┤
137           │baddr      │ Base address of loaded │
138           │           │ library.               │
139           ├───────────┼────────────────────────┤
140           │filename   │ Debug link file name.  │
141           ├───────────┼────────────────────────┤
142           │crc        │ Debug link file’s CRC. │
143           └───────────┴────────────────────────┘
144
145       lttng_ust_dl:build_id
146           Emitted when a build ID is found when loading a library with
147           dlopen(3). See Debugging Information in Separate Files
148           <https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-
149           Files.html> for more information about build IDs.
150
151           Fields:
152
153           ┌───────────┬────────────────────────┐
154           │Field name │ Description            │
155           ├───────────┼────────────────────────┤
156           │baddr      │ Base address of loaded │
157           │           │ library.               │
158           ├───────────┼────────────────────────┤
159           │build_id   │ Build ID.              │
160           └───────────┴────────────────────────┘
161

BUGS

163       If you encounter any issue or usability problem, please report it on
164       the LTTng bug tracker <https://bugs.lttng.org/projects/lttng-ust>.
165

RESOURCES

167       •   LTTng project website <http://lttng.org>
168
169       •   LTTng documentation <http://lttng.org/docs>
170
171       •   Git repositories <http://git.lttng.org>
172
173       •   GitHub organization <http://github.com/lttng>
174
175       •   Continuous integration <http://ci.lttng.org/>
176
177       •   Mailing list <http://lists.lttng.org> for support and development:
178           lttng-dev@lists.lttng.org
179
180       •   IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net
181

COPYRIGHTS

183       This library is part of the LTTng-UST project.
184
185       This library is distributed under the GNU Lesser General Public
186       License, version 2.1 <http://www.gnu.org/licenses/old-
187       licenses/lgpl-2.1.en.html>. See the COPYING
188       <https://github.com/lttng/lttng-ust/blob/v2.12.2/COPYING> file for more
189       details.
190

THANKS

192       Thanks to Ericsson for funding this work, providing real-life use
193       cases, and testing.
194
195       Special thanks to Michel Dagenais and the DORSAL laboratory
196       <http://www.dorsal.polymtl.ca/> at École Polytechnique de Montréal for
197       the LTTng journey.
198

AUTHORS

200       LTTng-UST was originally written by Mathieu Desnoyers, with additional
201       contributions from various other people. It is currently maintained by
202       Mathieu Desnoyers <mailto:mathieu.desnoyers@efficios.com>.
203