The LTTng User Space Tracing (LTTng-UST) library allows any C/C++ application to be instrumented for and traced by LTTng. LTTng-UST also includes a logging back-end for Java applications and various dynamically loadable user space tracing helpers for any application.
LTTng-UST depends on liburcu v0.7.2 at build and run times.
This source tree is based on the Autotools suite from GNU to simplify portability. Here are some things you should have on your system in order to compile the Git repository tree:
- GNU Autotools (Automake >= 1.10, Autoconf >= 2.50, Autoheader >= 2.50;
make sure your system-wide
automakepoints to a recent version!) - GNU Libtool >= 2.2
- Perl (optional: needed for
make checkand tests)
If you get the tree from the Git repository, you will need to run
./bootstrap
in its root. It calls all the GNU tools needed to prepare the tree configuration.
To build LTTng-UST, do:
./configure
make
sudo make install
sudo ldconfig
Note: the configure script sets /usr/local as the default prefix for
files it installs. However, this path is not part of most distributions'
default library path, which will cause builds depending on liblttng-ust
to fail unless -L/usr/local/lib is added to LDFLAGS. You may provide a
custom prefix to configure by using the --prefix switch
(e.g., --prefix=/usr). LTTng-UST needs to be a shared library, even if
the tracepoint probe provider is statically linked into the application.
First of all, create an instrumentation header following the tracepoint examples.
There are two ways to compile the tracepoint provider and link it with your application: statically or dynamically. Please follow carefully one or the other method.
This method links the tracepoint provider with the application,
either directly or through a static library (.a):
- Into exactly one unit (C/C++ source file) of your application,
define
TRACEPOINT_DEFINEand include the tracepoint provider header. - Include the tracepoint provider header into all C/C++ files using
the provider and insert tracepoints using the
tracepoint()macro. - Use
-I.when compiling the unit definingTRACEPOINT_DEFINE(e.g.,tp.c). - Link the application with
-ldlon Linux, or with-lcon BSD, and with-llttng-ust.
Example:
gcc -c -I. tp.c
gcc -c some-source.c
gcc -c other-source.c
gcc -o my-app tp.o some-source.o other-source.o -ldl -llttng-ust
Run the application directly:
./my-app
Other relevant examples:
This method decouples the tracepoint provider from the application, making it dynamically loadable.
- Into exactly one unit of your application, define
TRACEPOINT_DEFINEandTRACEPOINT_PROBE_DYNAMIC_LINKAGE, then include the tracepoint provider header. - Include the tracepoint provider header into all C/C++ files using
the provider and insert tracepoints using the
tracepoint()macro. - Use
-I.and-fpicwhen compiling the tracepoint provider (e.g.,tp.c). - Link the tracepoint provider with
-llttng-ustand make it a shared object with-shared. - Link the application with
-ldlon Linux, or with-lcon BSD.
Example:
gcc -c -I. -fpic tp.c
gcc -o tp.so -shared tp.o -llttng-ust
gcc -o my-app some-source.c other-source.c -ldl
To run without LTTng-UST support:
./my-app
To run with LTTng-UST support (register your tracepoint provider,
tp.so):
LD_PRELOAD=./tp.so ./my-app
You could also use libdl directly in your application and dlopen()
your tracepoint provider shared object (tp.so) to make LTTng-UST
tracing possible.
Other relevant examples:
Use LTTng-tools to control the tracer. Use Babeltrace to print traces as a human-readable text log.
liblttng-ustdebug can be activated by setting the environment variableLTTNG_UST_DEBUGwhen launching the user application. It can also be enabled at build time by compiling LTTng-UST with-DLTTNG_UST_DEBUG.- The environment variable
LTTNG_UST_REGISTER_TIMEOUTcan be used to specify how long the applications should wait for the session daemon registration done command before proceeding to execute the main program. The default is 3000 ms (3 seconds). The timeout value is specified in milliseconds. The value 0 means don't wait. The value -1 means wait forever. Setting this environment variable to 0 is recommended for applications with time constraints on the process startup time. - The compilation flag
-DLTTNG_UST_DEBUG_VALGRINDshould be enabled at build time to allowliblttng-ustto be used with Valgrind (side-effect: disables per-CPU buffering).
Since LTTng-UST 2.3, both tracepoints and tracepoint providers can be compiled in C++. To compile tracepoint probes in C++, you need G++ >= 4.7 or Clang.
Maintainer: Mathieu Desnoyers
Mailing list: lttng-dev@lists.lttng.org
This package contains the following elements:
doc: LTTng-UST documentation and examples.include: the public header files that will be installed on the system.liblttng-ust: the actual userspace tracing library that must be linked to the instrumented programs.liblttng-ust-comm: a static library shared betweenliblttng-ustand LTTng-tools, that provides functions that allow these components to communicate together.liblttng-ust-ctl: a library to control tracing in other processes; used by LTTng-tools.liblttng-ust-cyg-profile: a library that can be preloaded (usingLD_PRELOAD) to instrument function entries and exits when the target application is built with the GCC flag-finstrument-functions.liblttng-ust-dl: a library that can be preloaded to instrument calls todlopen()anddlclose().liblttng-ust-fork: a library that is preloaded and that hijacks calls to several system calls in order to trace across these calls. It has to be preloaded in order to hijack calls. In contrast,liblttng-ustmay be linked at build time.liblttng-ust-java: a simple library that uses JNI to allow tracing in Java programs.liblttng-ust-jul: a package that includes a JNI library and a JAR library to provide an LTTng-UST logging back-end for Java application using Java Util Logging.liblttng-ust-libc-wrapper: an example library that can be preloaded to instrument some calls to libc (currentlymalloc()andfree()) and to POSIX threads (mutexes currently instrumented) in any program without need to recompile it.libringbuffer: the ring buffer implementation used within LTTng-UST.snprintf: an asynchronous signal-safe version ofsnprintf().tests: various test programs.tools: home oflttng-gen-tp.