2 SPDX-FileCopyrightText: 2023 EfficiOS, Inc.
4 SPDX-License-Identifier: CC-BY-4.0
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.
20 LTTng-UST depends on **[liburcu](http://liburcu.org/) >= 0.12** at build
21 time. It also optionally depends on libnuma.
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:
33 - [GNU Autotools](http://www.gnu.org/software/autoconf/)
34 (**Automake >= 1.12**, **Autoconf >= 2.69**,
35 **Autoheader >= 2.69**;
36 make sure your system-wide `automake` points to a recent version!)
37 - **[GNU Libtool](https://www.gnu.org/software/libtool/) >= 2.2**
38 - **[pkg-config](https://www.freedesktop.org/wiki/Software/pkg-config/)**
41 ### Optional dependencies
43 Optional packages to build LTTng-ust man pages:
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)
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.
54 Needed for `make check` and tests:
56 - **[Perl](https://www.perl.org/)**
61 If you get the tree from the Git repository, you will need to run
65 in its root. It calls all the GNU tools needed to prepare the tree
68 To build LTTng-UST, do:
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.
87 First of all, create an instrumentation header following the
88 [tracepoint examples](doc/examples).
90 There are two ways to compile the tracepoint provider and link it with
91 your application: statically or dynamically. Please follow carefully one
97 This method links the tracepoint provider with the application,
98 either directly or through a static library (`.a`):
100 1. Into exactly one unit (C/C++ source file) of your _application_,
101 define `LTTNG_UST_TRACEPOINT_DEFINE` and include the tracepoint provider
103 2. Include the tracepoint provider header into all C/C++ files using
104 the provider and insert tracepoints using the `tracepoint()` macro.
105 3. Use `-I.` when compiling the unit defining `LTTNG_UST_TRACEPOINT_DEFINE`
107 4. Link the application with `-ldl` on Linux, or with `-lc` on BSD,
108 and with `-llttng-ust`.
114 gcc -c other-source.c
115 gcc -o my-app tp.o some-source.o other-source.o -ldl -llttng-ust
117 Run the application directly:
121 Other relevant examples:
123 - [`doc/examples/easy-ust`](doc/examples/easy-ust)
124 - [`doc/examples/hello-static-lib`](doc/examples/hello-static-lib)
129 This method decouples the tracepoint provider from the application,
130 making it dynamically loadable.
132 1. Into exactly one unit of your _application_, define
133 `LTTNG_UST_TRACEPOINT_DEFINE` _and_ `LTTNG_UST_TRACEPOINT_PROBE_DYNAMIC_LINKAGE`,
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
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.
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
149 To run _without_ LTTng-UST support:
153 To run with LTTng-UST support (register your tracepoint provider,
156 LD_PRELOAD=./tp.so ./my-app
158 You could also use `libdl` directly in your application and `dlopen()`
159 your tracepoint provider shared object (`tp.so`) to make LTTng-UST
162 Other relevant examples:
164 - [`doc/examples/demo`](doc/examples/demo)
167 ### Controlling tracing and viewing traces
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.
174 ### Environment variables and compile flags
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
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`.
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
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).
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
203 G++ >= 4.7 or Clang >= 4.0. The C++ compilers need to support C++11.
209 Maintainer: [Mathieu Desnoyers](mailto:mathieu.desnoyers@efficios.com)
211 Mailing list: [`lttng-dev@lists.lttng.org`](https://lttng.org/cgi-bin/mailman/listinfo/lttng-dev)
213 Code review: [_lttng-ust_ project](https://review.lttng.org/q/project:lttng-ust) on LTTng Review
218 This package contains the following elements:
220 - `doc`: LTTng-UST documentation and examples.
221 - `include`: the public header files that will be installed on the
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;
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
240 in Java programs. (Configure with `--enable-jni-interface`).
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
243 applications using Java Util Logging or Log4j. (Configure with
244 `--enable-java-agent-jul` or `--enable-java-agent-log4j` or
245 `--enable-java-agent-log4j2` or `--enable-java-agent-all`).
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.
250 - `liblttng-ust-python-agent`: a library used by python-lttngust to allow
251 tracing in Python applications. (Configure with `--enable-python-agent`)
252 - `libringbuffer`: the ring buffer implementation used within LTTng-UST.
253 - `python-lttngust`: a package to provide an LTTng-UST logging back-end
254 for Python applications using the standard logging framework.
255 - `snprintf`: an asynchronous signal-safe version of `snprintf()`.
256 - `tests`: various test programs.
257 - `tools`: home of `lttng-gen-tp`.