Commit | Line | Data |
---|---|---|
e03d7c66 MJ |
1 | <!-- |
2 | SPDX-FileCopyrightText: 2023 EfficiOS, Inc. | |
3 | ||
4 | SPDX-License-Identifier: CC-BY-4.0 | |
5 | --> | |
6 | ||
28ed9628 PP |
7 | LTTng-UST |
8 | ========= | |
9 | ||
10 | The LTTng User Space Tracing (LTTng-UST) library allows any C/C++ | |
11 | application to be instrumented for and traced by | |
12 | [LTTng](http://lttng.org/). LTTng-UST also includes a logging | |
13 | back-end for Java applications and various dynamically loadable | |
14 | user space tracing helpers for any application. | |
15 | ||
16 | ||
17 | Prerequisites | |
18 | ------------- | |
19 | ||
a610548a MD |
20 | LTTng-UST depends on **[liburcu](http://liburcu.org/) >= 0.12** at build |
21 | time. It also optionally depends on libnuma. | |
28ed9628 PP |
22 | |
23 | ||
24 | Building | |
25 | -------- | |
26 | ||
27 | ### Prerequisites | |
28 | ||
29 | This source tree is based on the Autotools suite from GNU to simplify | |
30 | portability. Here are some things you should have on your system in order to | |
31 | compile the Git repository tree: | |
32 | ||
6f9466c5 | 33 | - [GNU Autotools](http://www.gnu.org/software/autoconf/) |
90e5d8e4 MJ |
34 | (**Automake >= 1.12**, **Autoconf >= 2.69**, |
35 | **Autoheader >= 2.69**; | |
28ed9628 | 36 | make sure your system-wide `automake` points to a recent version!) |
6f9466c5 | 37 | - **[GNU Libtool](https://www.gnu.org/software/libtool/) >= 2.2** |
ff1ee9bc | 38 | - **[pkg-config](https://www.freedesktop.org/wiki/Software/pkg-config/)** |
c5123a13 PP |
39 | |
40 | ||
41 | ### Optional dependencies | |
28ed9628 | 42 | |
b49b04f4 | 43 | Optional packages to build LTTng-ust man pages: |
4ddbd0b7 PP |
44 | |
45 | - **[AsciiDoc](http://www.methods.co.nz/asciidoc/) >= 8.4.5** | |
46 | (previous versions may work, but were not tested) | |
47 | - **[xmlto](https://fedorahosted.org/xmlto/) >= 0.0.21** (previous | |
48 | versions may work, but were not tested) | |
49 | ||
50 | Note that the man pages are already built in a distribution tarball. | |
51 | In this case, you only need AsciiDoc and xmlto if you indend to modify | |
52 | the AsciiDoc man page sources. | |
53 | ||
c5123a13 PP |
54 | Needed for `make check` and tests: |
55 | ||
56 | - **[Perl](https://www.perl.org/)** | |
57 | ||
58 | ||
59 | ### Building steps | |
60 | ||
28ed9628 PP |
61 | If you get the tree from the Git repository, you will need to run |
62 | ||
63 | ./bootstrap | |
64 | ||
65 | in its root. It calls all the GNU tools needed to prepare the tree | |
66 | configuration. | |
67 | ||
68 | To build LTTng-UST, do: | |
69 | ||
70 | ./configure | |
71 | make | |
72 | sudo make install | |
73 | sudo ldconfig | |
74 | ||
75 | **Note:** the `configure` script sets `/usr/local` as the default prefix for | |
76 | files it installs. However, this path is not part of most distributions' | |
77 | default library path, which will cause builds depending on `liblttng-ust` | |
78 | to fail unless `-L/usr/local/lib` is added to `LDFLAGS`. You may provide a | |
79 | custom prefix to `configure` by using the `--prefix` switch | |
80 | (e.g., `--prefix=/usr`). LTTng-UST needs to be a shared library, _even if_ | |
81 | the tracepoint probe provider is statically linked into the application. | |
82 | ||
83 | ||
84 | Using | |
85 | ----- | |
86 | ||
87 | First of all, create an instrumentation header following the | |
88 | [tracepoint examples](doc/examples). | |
89 | ||
90 | There are two ways to compile the tracepoint provider and link it with | |
91 | your application: statically or dynamically. Please follow carefully one | |
92 | or the other method. | |
93 | ||
94 | ||
95 | ### Static linking | |
96 | ||
97 | This method links the tracepoint provider with the application, | |
98 | either directly or through a static library (`.a`): | |
99 | ||
100 | 1. Into exactly one unit (C/C++ source file) of your _application_, | |
88c7c4ea | 101 | define `LTTNG_UST_TRACEPOINT_DEFINE` and include the tracepoint provider |
28ed9628 PP |
102 | header. |
103 | 2. Include the tracepoint provider header into all C/C++ files using | |
104 | the provider and insert tracepoints using the `tracepoint()` macro. | |
88c7c4ea | 105 | 3. Use `-I.` when compiling the unit defining `LTTNG_UST_TRACEPOINT_DEFINE` |
28ed9628 PP |
106 | (e.g., `tp.c`). |
107 | 4. Link the application with `-ldl` on Linux, or with `-lc` on BSD, | |
108 | and with `-llttng-ust`. | |
109 | ||
110 | Example: | |
111 | ||
112 | gcc -c -I. tp.c | |
113 | gcc -c some-source.c | |
114 | gcc -c other-source.c | |
115 | gcc -o my-app tp.o some-source.o other-source.o -ldl -llttng-ust | |
116 | ||
117 | Run the application directly: | |
118 | ||
119 | ./my-app | |
120 | ||
121 | Other relevant examples: | |
122 | ||
123 | - [`doc/examples/easy-ust`](doc/examples/easy-ust) | |
124 | - [`doc/examples/hello-static-lib`](doc/examples/hello-static-lib) | |
125 | ||
126 | ||
127 | ### Dynamic loading | |
128 | ||
129 | This method decouples the tracepoint provider from the application, | |
130 | making it dynamically loadable. | |
131 | ||
132 | 1. Into exactly one unit of your _application_, define | |
88c7c4ea | 133 | `LTTNG_UST_TRACEPOINT_DEFINE` _and_ `LTTNG_UST_TRACEPOINT_PROBE_DYNAMIC_LINKAGE`, |
28ed9628 PP |
134 | then include the tracepoint provider header. |
135 | 2. Include the tracepoint provider header into all C/C++ files using | |
136 | the provider and insert tracepoints using the `tracepoint()` macro. | |
137 | 3. Use `-I.` and `-fpic` when compiling the tracepoint provider | |
138 | (e.g., `tp.c`). | |
139 | 4. Link the tracepoint provider with `-llttng-ust` and make it a | |
140 | shared object with `-shared`. | |
141 | 5. Link the application with `-ldl` on Linux, or with `-lc` on BSD. | |
142 | ||
143 | Example: | |
144 | ||
145 | gcc -c -I. -fpic tp.c | |
146 | gcc -o tp.so -shared tp.o -llttng-ust | |
147 | gcc -o my-app some-source.c other-source.c -ldl | |
148 | ||
149 | To run _without_ LTTng-UST support: | |
150 | ||
151 | ./my-app | |
152 | ||
153 | To run with LTTng-UST support (register your tracepoint provider, | |
154 | `tp.so`): | |
155 | ||
156 | LD_PRELOAD=./tp.so ./my-app | |
157 | ||
158 | You could also use `libdl` directly in your application and `dlopen()` | |
159 | your tracepoint provider shared object (`tp.so`) to make LTTng-UST | |
160 | tracing possible. | |
161 | ||
162 | Other relevant examples: | |
163 | ||
164 | - [`doc/examples/demo`](doc/examples/demo) | |
165 | ||
166 | ||
167 | ### Controlling tracing and viewing traces | |
168 | ||
169 | Use [LTTng-tools](https://lttng.org/download) to control the tracer. | |
170 | Use [Babeltrace](https://lttng.org/babeltrace) to print traces as a | |
171 | human-readable text log. | |
172 | ||
173 | ||
174 | ### Environment variables and compile flags | |
175 | ||
176 | - `liblttng-ust` debug can be activated by setting the environment | |
177 | variable `LTTNG_UST_DEBUG` when launching the user application. It | |
178 | can also be enabled at build time by compiling LTTng-UST with | |
179 | `-DLTTNG_UST_DEBUG`. | |
9ff107a9 MJ |
180 | - `liblttng-ust` abort on critical can be activated by setting the |
181 | environment variable `LTTNG_UST_ABORT_ON_CRITICAL` when launching the user | |
182 | application. It can also be enabled at build time by compiling LTTng-UST with | |
183 | `-DLTTNG_UST_ABORT_ON_CRITICAL`. | |
28ed9628 PP |
184 | - The environment variable `LTTNG_UST_REGISTER_TIMEOUT` can be used to |
185 | specify how long the applications should wait for the session | |
186 | daemon _registration done_ command before proceeding to execute the | |
187 | main program. The default is 3000 ms (3 seconds). The timeout value | |
188 | is specified in milliseconds. The value 0 means _don't wait_. The | |
189 | value -1 means _wait forever_. Setting this environment variable to 0 | |
190 | is recommended for applications with time constraints on the process | |
191 | startup time. | |
192 | - The compilation flag `-DLTTNG_UST_DEBUG_VALGRIND` should be enabled | |
193 | at build time to allow `liblttng-ust` to be used with Valgrind | |
194 | (side-effect: disables per-CPU buffering). | |
195 | ||
196 | ||
197 | ### Notes | |
198 | ||
199 | #### C++ support | |
200 | ||
201 | Since LTTng-UST 2.3, both tracepoints and tracepoint providers can be | |
202 | compiled in C++. To compile tracepoint probes in C++, you need | |
7850c5cc | 203 | G++ >= 4.7 or Clang >= 4.0. The C++ compilers need to support C++11. |
28ed9628 PP |
204 | |
205 | ||
206 | Contact | |
207 | ------- | |
208 | ||
209 | Maintainer: [Mathieu Desnoyers](mailto:mathieu.desnoyers@efficios.com) | |
210 | ||
211 | Mailing list: [`lttng-dev@lists.lttng.org`](https://lttng.org/cgi-bin/mailman/listinfo/lttng-dev) | |
212 | ||
d6c33741 | 213 | Code review: [_lttng-ust_ project](https://review.lttng.org/q/project:lttng-ust) on LTTng Review |
28ed9628 PP |
214 | |
215 | Package contents | |
216 | ---------------- | |
217 | ||
218 | This package contains the following elements: | |
219 | ||
220 | - `doc`: LTTng-UST documentation and examples. | |
221 | - `include`: the public header files that will be installed on the | |
222 | system. | |
223 | - `liblttng-ust`: the actual userspace tracing library that must be | |
224 | linked to the instrumented programs. | |
225 | - `liblttng-ust-comm`: a static library shared between `liblttng-ust` | |
226 | and LTTng-tools, that provides functions that allow these components | |
227 | to communicate together. | |
228 | - `liblttng-ust-ctl`: a library to control tracing in other processes; | |
229 | used by LTTng-tools. | |
230 | - `liblttng-ust-cyg-profile`: a library that can be preloaded (using | |
231 | `LD_PRELOAD`) to instrument function entries and exits when the target | |
232 | application is built with the GCC flag `-finstrument-functions`. | |
233 | - `liblttng-ust-dl`: a library that can be preloaded to instrument | |
234 | calls to `dlopen()` and `dlclose()`. | |
235 | - `liblttng-ust-fork`: a library that is preloaded and that hijacks | |
236 | calls to several system calls in order to trace across these calls. | |
237 | It _has_ to be preloaded in order to hijack calls. In contrast, | |
238 | `liblttng-ust` may be linked at build time. | |
239 | - `liblttng-ust-java`: a simple library that uses JNI to allow tracing | |
380a81f4 | 240 | in Java programs. (Configure with `--enable-jni-interface`). |
b49b04f4 MJ |
241 | - `liblttng-ust-java-agent`: a package that includes a JNI library and a |
242 | JAR library to provide an LTTng-UST logging back-end for Java | |
380a81f4 GB |
243 | applications using Java Util Logging or Log4j. (Configure with |
244 | `--enable-java-agent-jul` or `--enable-java-agent-log4j` or | |
464c4756 | 245 | `--enable-java-agent-log4j2` or `--enable-java-agent-all`). |
28ed9628 PP |
246 | - `liblttng-ust-libc-wrapper`: an example library that can be |
247 | preloaded to instrument some calls to libc (currently `malloc()` and | |
248 | `free()`) and to POSIX threads (mutexes currently instrumented) in | |
249 | any program without need to recompile it. | |
b49b04f4 | 250 | - `liblttng-ust-python-agent`: a library used by python-lttngust to allow |
380a81f4 | 251 | tracing in Python applications. (Configure with `--enable-python-agent`) |
28ed9628 | 252 | - `libringbuffer`: the ring buffer implementation used within LTTng-UST. |
b49b04f4 MJ |
253 | - `python-lttngust`: a package to provide an LTTng-UST logging back-end |
254 | for Python applications using the standard logging framework. | |
28ed9628 PP |
255 | - `snprintf`: an asynchronous signal-safe version of `snprintf()`. |
256 | - `tests`: various test programs. | |
257 | - `tools`: home of `lttng-gen-tp`. |