LTTNG USERSPACE TRACER (LTTng-UST) ---------------------------- UST web site: http://lttng.org/lttng2.0 Updated versions of this package may be found at: * Website: http://lttng.org/lttng2.0 * Releases: http://lttng.org/files/lttng-ust * GitWeb: http://git.lttng.org (project: lttng-ust) * Git: git://git.lttng.org/lttng-ust.git PREREQUISITES: - liburcu Userspace RCU library, by Mathieu Desnoyers and Paul E. McKenney -> This release depends on liburcu v0.6.6 * Debian/Ubuntu package: liburcu-dev * Website: http://lttng.org/urcu * Releases: http://lttng.org/files/urcu * GitWeb: http://lttng.org/cgi-bin/gitweb.cgi?p=userspace-rcu.git;a=summary * Git: git://lttng.org/userspace-rcu.git For developers using the git tree: 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 (for more information, go to http://www.gnu.org/software/autoconf/) If you get the tree from the repository, you will need to use the "bootstrap" script in the root of the tree. It calls all the GNU tools needed to prepare the tree configuration. INSTALLATION INSTRUCTIONS: - Download, compile and install liburcu. - In this package's tree, run ./configure. - Run make. - Run make install. - Run ldconfig. If compiling from the git repository, run ./bootstrap before running the configure script, to generate it. USAGE: - Create an instrumentation header following the tracepoint examples. See lttng/tracepoint.h, and examples. - Either compile the Tracepoint probes with the application: - Use "-I." for the compilation unit containing the tracepoint provider include (e.g. tp.c). - Link application with "-ldl -llttng-ust". - Example: tests/hello/ hello.c tp.c ust_tests_hello.h Makefile.example - Or compile the Tracepoint probes separately from the application, using dynamic linking: - Compile the tracepoint provider with "-I.". - Link the tracepoint provider with "-llttng-ust". - Link application with "-ldl". - Set a LD_PRELOAD environment to preload the tracepoint provider shared object before starting the application when tracing is needed. - Example: - tests/demo/ demo.c tp*.c ust_tests_demo*.h demo-trace - Note about dlopen() usage: due to locking side-effects due to the way libc lazily resolves Thread-Local Storage (TLS) symbols when a library is dlopen'd, linking the tracepoint probe or liblttng-ust with dlopen() is discouraged. They should be linked with the application using "-llibname" or loaded with LD_PRELOAD. - Enable instrumentation and control tracing with the "lttng" command from lttng-tools. See lttng-tools doc/quickstart.txt. ENVIRONMENT VARIABLES: - liblttng-ust debug can be activated by setting the environment variable "LTTNG_UST_DEBUG" when launching the application. It can also be enabled at compile-time by compiling libust with -DLTTNG_UST_DEBUG. - The environment variable "LTTNG_UST_REGISTER_TIMEOUT" can be used to specify how long the applications should wait for sessiond "registration done" command before proceeding to execute the main program. The default is 3000ms (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. TRACE VIEWER: Use babeltrace for viewing traces generated by LTTng UST 2.0. See http://lttng.org for download. CONTACT: Maintainer: Mathieu Desnoyers Mailing list: lttng-dev@lists.lttng.org PACKAGE CONTENTS: This package contains the following elements. - liblttng-ust The actual userspace tracing library that must be linked to the instrumented programs. - include The public header files that will be installed on the system. - tests Various test programs - liblttng-ust-libc An example library that can be LD_PRELOAD'ed to instrument some calls to libc (currently malloc() and free()) in any program without need to recompile it. - liblttng-ust-fork A library that is LD_PRELOAD'ed, and that hijacks calls to several system calls in order to trace across these calls. It _has_ to be LD_PRELOAD'ed in order to hijack calls. In contrast, libust may be linked at build time. - liblttng-ust-ctl A library to control tracing in other processes. Used by lttng-tools. - liblttng-ust-comm A static library shared between libust and lttng-tools, that provides functions that allow these components to communicate together. - libringbuffer The ring buffer implementation used within LTTng-UST. - snprintf An asynchronous signal-safe version of snprintf. - liblttng-ust-java A simple library that uses JNI to allow tracing in java programs. See liblttng-ust-java/README for build instructions.