This repo is a mirror of the official lttng-ust git found at git://git.lttng.org/lttng-ust.git. LTTng-UST, the Linux Trace Toolkit Next Generation Userspace Tracer, is port of the low-overhead tracing capabilities of the LTTng kernel tracer to user-space. The library "liblttng-ust" enables tracing of applications and libraries.
C Java M4 Shell Python Makefile C++
vitlav and compudj Fix: add liblttng-ust dependency to liblttng-ust-fd
Signed-off-by: Vitaly Lipatov <lav@etersoft.ru>
Signed-off-by: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
Latest commit 60b488d Jun 30, 2018
Permalink
Failed to load latest commit information.
config Move m4 scripts to m4 dir May 9, 2017
doc Fix: build example SO when PIE is enabled Feb 20, 2018
include Filter: index array, sequences, implement bitwise binary operators Jun 6, 2018
liblttng-ust-comm Rename lttng_ust_enum_get to lttng_ust_enum_get_from_desc Feb 9, 2018
liblttng-ust-ctl Introduce LTTNG_UST_ALLOW_BLOCKING env. var. Jun 12, 2017
liblttng-ust-cyg-profile Fix: Don't override user variables within the build system May 9, 2017
liblttng-ust-dl Fix: Don't override user variables within the build system May 9, 2017
liblttng-ust-fd Fix: add liblttng-ust dependency to liblttng-ust-fd Jun 30, 2018
liblttng-ust-fork Fix: ustfork: save and restore errno in syscall wrappers Mar 5, 2018
liblttng-ust-java-agent Fix: build jni libs with openjdk >= 10 May 3, 2018
liblttng-ust-java Fix: build jni libs with openjdk >= 10 May 3, 2018
liblttng-ust-libc-wrapper Revert "Use initial-exec TLS model" Nov 7, 2017
liblttng-ust-python-agent Fix: Don't override user variables within the build system May 9, 2017
liblttng-ust Fix: use LIBDL/LIBC_DL to select either libdl or libc Jun 30, 2018
libringbuffer Fix: numa: dynamically check that numa is available Dec 19, 2017
m4 Rework configure script May 9, 2017
python-lttngust Fix: specify SONAME in python-lttngust LoadLibrary Nov 21, 2017
snprintf Fix: Don't override user variables within the build system May 9, 2017
tests Revert "Use initial-exec TLS model" Nov 7, 2017
tools lttng-gen-tp: formatting Sep 19, 2017
.gitignore Move m4 scripts to m4 dir May 9, 2017
CONTRIBUTING.md Add CONTRIBUTING.md Feb 20, 2016
COPYING Update COPYING Mar 19, 2012
ChangeLog Version 2.10.0-rc1 May 6, 2017
CodingStyle Add coding style document May 30, 2012
LICENSE Filter code relicensing to MIT license Nov 28, 2016
Makefile.am Move m4 scripts to m4 dir May 9, 2017
README.md Update readme to document opt dep on numa Nov 5, 2017
bootstrap bootstrap: Standardize on autoreconf -vi May 12, 2016
configure.ac Fix: AM_CONDITIONAL should be outside AS_IF block May 3, 2018
gpl-2.0.txt Update license text Dec 5, 2012
lgpl-2.1.txt Add LGPLv2.1 license text Sep 1, 2010
lttng-ust.pc.in Fix: lttng-ust.pc needs to specify -ldl Apr 25, 2012
mit-license.txt Update license text Dec 5, 2012

README.md

LTTng-UST

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.

Prerequisites

LTTng-UST depends on liburcu v0.7.2 at build and run times. It also optionally depends on libnuma.

Building

Prerequisites

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 automake points to a recent version!)
  • GNU Libtool >= 2.2

Optional dependencies

Optional packages to build LTTng-ust man pages:

  • AsciiDoc >= 8.4.5 (previous versions may work, but were not tested)
  • xmlto >= 0.0.21 (previous versions may work, but were not tested)

Note that the man pages are already built in a distribution tarball. In this case, you only need AsciiDoc and xmlto if you indend to modify the AsciiDoc man page sources.

Needed for make check and tests:

Building steps

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.

Using

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.

Static linking

This method links the tracepoint provider with the application, either directly or through a static library (.a):

  1. Into exactly one unit (C/C++ source file) of your application, define TRACEPOINT_DEFINE and include the tracepoint provider header.
  2. Include the tracepoint provider header into all C/C++ files using the provider and insert tracepoints using the tracepoint() macro.
  3. Use -I. when compiling the unit defining TRACEPOINT_DEFINE (e.g., tp.c).
  4. Link the application with -ldl on Linux, or with -lc on 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:

Dynamic loading

This method decouples the tracepoint provider from the application, making it dynamically loadable.

  1. Into exactly one unit of your application, define TRACEPOINT_DEFINE and TRACEPOINT_PROBE_DYNAMIC_LINKAGE, then include the tracepoint provider header.
  2. Include the tracepoint provider header into all C/C++ files using the provider and insert tracepoints using the tracepoint() macro.
  3. Use -I. and -fpic when compiling the tracepoint provider (e.g., tp.c).
  4. Link the tracepoint provider with -llttng-ust and make it a shared object with -shared.
  5. Link the application with -ldl on Linux, or with -lc on 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:

Controlling tracing and viewing traces

Use LTTng-tools to control the tracer. Use Babeltrace to print traces as a human-readable text log.

Environment variables and compile flags

  • liblttng-ust debug can be activated by setting the environment variable LTTNG_UST_DEBUG when 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_TIMEOUT can 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_VALGRIND should be enabled at build time to allow liblttng-ust to be used with Valgrind (side-effect: disables per-CPU buffering).

Notes

C++ support

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.

Contact

Maintainer: Mathieu Desnoyers

Mailing list: lttng-dev@lists.lttng.org

Package contents

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 between liblttng-ust and 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 (using LD_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 to dlopen() and dlclose().
  • 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-ust may be linked at build time.
  • liblttng-ust-java: a simple library that uses JNI to allow tracing in Java programs. (Configure with --enable-jni-interface).
  • liblttng-ust-java-agent: a package that includes a JNI library and a JAR library to provide an LTTng-UST logging back-end for Java applications using Java Util Logging or Log4j. (Configure with --enable-java-agent-jul or --enable-java-agent-log4j or --enable-java-agent-all).
  • liblttng-ust-libc-wrapper: an example library that can be preloaded to instrument some calls to libc (currently malloc() and free()) and to POSIX threads (mutexes currently instrumented) in any program without need to recompile it.
  • liblttng-ust-python-agent: a library used by python-lttngust to allow tracing in Python applications. (Configure with --enable-python-agent)
  • libringbuffer: the ring buffer implementation used within LTTng-UST.
  • python-lttngust: a package to provide an LTTng-UST logging back-end for Python applications using the standard logging framework.
  • snprintf: an asynchronous signal-safe version of snprintf().
  • tests: various test programs.
  • tools: home of lttng-gen-tp.