4 The LTTng User Space Tracing (LTTng-UST) library allows any C/C++
5 application to be instrumented for and traced by
6 [LTTng](http://lttng.org/). LTTng-UST also includes a logging
7 back-end for Java applications and various dynamically loadable
8 user space tracing helpers for any application.
14 LTTng-UST depends on [liburcu](http://liburcu.org/) v0.7.2 at build and
23 This source tree is based on the Autotools suite from GNU to simplify
24 portability. Here are some things you should have on your system in order to
25 compile the Git repository tree:
27 - GNU Autotools (Automake >= 1.10, Autoconf >= 2.50, Autoheader >= 2.50;
28 make sure your system-wide `automake` points to a recent version!)
29 - [GNU Libtool](http://www.gnu.org/software/autoconf/) >= 2.2
30 - Perl (optional: needed for `make check` and tests)
32 Optional packages to build LTTng-tools man pages:
34 - **[AsciiDoc](http://www.methods.co.nz/asciidoc/) >= 8.4.5**
35 (previous versions may work, but were not tested)
36 - **[xmlto](https://fedorahosted.org/xmlto/) >= 0.0.21** (previous
37 versions may work, but were not tested)
39 Note that the man pages are already built in a distribution tarball.
40 In this case, you only need AsciiDoc and xmlto if you indend to modify
41 the AsciiDoc man page sources.
43 If you get the tree from the Git repository, you will need to run
47 in its root. It calls all the GNU tools needed to prepare the tree
50 To build LTTng-UST, do:
57 **Note:** the `configure` script sets `/usr/local` as the default prefix for
58 files it installs. However, this path is not part of most distributions'
59 default library path, which will cause builds depending on `liblttng-ust`
60 to fail unless `-L/usr/local/lib` is added to `LDFLAGS`. You may provide a
61 custom prefix to `configure` by using the `--prefix` switch
62 (e.g., `--prefix=/usr`). LTTng-UST needs to be a shared library, _even if_
63 the tracepoint probe provider is statically linked into the application.
69 First of all, create an instrumentation header following the
70 [tracepoint examples](doc/examples).
72 There are two ways to compile the tracepoint provider and link it with
73 your application: statically or dynamically. Please follow carefully one
79 This method links the tracepoint provider with the application,
80 either directly or through a static library (`.a`):
82 1. Into exactly one unit (C/C++ source file) of your _application_,
83 define `TRACEPOINT_DEFINE` and include the tracepoint provider
85 2. Include the tracepoint provider header into all C/C++ files using
86 the provider and insert tracepoints using the `tracepoint()` macro.
87 3. Use `-I.` when compiling the unit defining `TRACEPOINT_DEFINE`
89 4. Link the application with `-ldl` on Linux, or with `-lc` on BSD,
90 and with `-llttng-ust`.
97 gcc -o my-app tp.o some-source.o other-source.o -ldl -llttng-ust
99 Run the application directly:
103 Other relevant examples:
105 - [`doc/examples/easy-ust`](doc/examples/easy-ust)
106 - [`doc/examples/hello-static-lib`](doc/examples/hello-static-lib)
111 This method decouples the tracepoint provider from the application,
112 making it dynamically loadable.
114 1. Into exactly one unit of your _application_, define
115 `TRACEPOINT_DEFINE` _and_ `TRACEPOINT_PROBE_DYNAMIC_LINKAGE`,
116 then include the tracepoint provider header.
117 2. Include the tracepoint provider header into all C/C++ files using
118 the provider and insert tracepoints using the `tracepoint()` macro.
119 3. Use `-I.` and `-fpic` when compiling the tracepoint provider
121 4. Link the tracepoint provider with `-llttng-ust` and make it a
122 shared object with `-shared`.
123 5. Link the application with `-ldl` on Linux, or with `-lc` on BSD.
127 gcc -c -I. -fpic tp.c
128 gcc -o tp.so -shared tp.o -llttng-ust
129 gcc -o my-app some-source.c other-source.c -ldl
131 To run _without_ LTTng-UST support:
135 To run with LTTng-UST support (register your tracepoint provider,
138 LD_PRELOAD=./tp.so ./my-app
140 You could also use `libdl` directly in your application and `dlopen()`
141 your tracepoint provider shared object (`tp.so`) to make LTTng-UST
144 Other relevant examples:
146 - [`doc/examples/demo`](doc/examples/demo)
149 ### Controlling tracing and viewing traces
151 Use [LTTng-tools](https://lttng.org/download) to control the tracer.
152 Use [Babeltrace](https://lttng.org/babeltrace) to print traces as a
153 human-readable text log.
156 ### Environment variables and compile flags
158 - `liblttng-ust` debug can be activated by setting the environment
159 variable `LTTNG_UST_DEBUG` when launching the user application. It
160 can also be enabled at build time by compiling LTTng-UST with
162 - The environment variable `LTTNG_UST_REGISTER_TIMEOUT` can be used to
163 specify how long the applications should wait for the session
164 daemon _registration done_ command before proceeding to execute the
165 main program. The default is 3000 ms (3 seconds). The timeout value
166 is specified in milliseconds. The value 0 means _don't wait_. The
167 value -1 means _wait forever_. Setting this environment variable to 0
168 is recommended for applications with time constraints on the process
170 - The compilation flag `-DLTTNG_UST_DEBUG_VALGRIND` should be enabled
171 at build time to allow `liblttng-ust` to be used with Valgrind
172 (side-effect: disables per-CPU buffering).
179 Since LTTng-UST 2.3, both tracepoints and tracepoint providers can be
180 compiled in C++. To compile tracepoint probes in C++, you need
187 Maintainer: [Mathieu Desnoyers](mailto:mathieu.desnoyers@efficios.com)
189 Mailing list: [`lttng-dev@lists.lttng.org`](https://lttng.org/cgi-bin/mailman/listinfo/lttng-dev)
195 This package contains the following elements:
197 - `doc`: LTTng-UST documentation and examples.
198 - `include`: the public header files that will be installed on the
200 - `liblttng-ust`: the actual userspace tracing library that must be
201 linked to the instrumented programs.
202 - `liblttng-ust-comm`: a static library shared between `liblttng-ust`
203 and LTTng-tools, that provides functions that allow these components
204 to communicate together.
205 - `liblttng-ust-ctl`: a library to control tracing in other processes;
207 - `liblttng-ust-cyg-profile`: a library that can be preloaded (using
208 `LD_PRELOAD`) to instrument function entries and exits when the target
209 application is built with the GCC flag `-finstrument-functions`.
210 - `liblttng-ust-dl`: a library that can be preloaded to instrument
211 calls to `dlopen()` and `dlclose()`.
212 - `liblttng-ust-fork`: a library that is preloaded and that hijacks
213 calls to several system calls in order to trace across these calls.
214 It _has_ to be preloaded in order to hijack calls. In contrast,
215 `liblttng-ust` may be linked at build time.
216 - `liblttng-ust-java`: a simple library that uses JNI to allow tracing
218 - `liblttng-ust-jul`: a package that includes a JNI library and a JAR
219 library to provide an LTTng-UST logging back-end for Java application
220 using Java Util Logging.
221 - `liblttng-ust-libc-wrapper`: an example library that can be
222 preloaded to instrument some calls to libc (currently `malloc()` and
223 `free()`) and to POSIX threads (mutexes currently instrumented) in
224 any program without need to recompile it.
225 - `libringbuffer`: the ring buffer implementation used within LTTng-UST.
226 - `snprintf`: an asynchronous signal-safe version of `snprintf()`.
227 - `tests`: various test programs.
228 - `tools`: home of `lttng-gen-tp`.