1 LTTNG USERSPACE TRACER (LTTng-UST)
2 ----------------------------
4 UST web site: http://lttng.org/lttng2.0
6 Updated versions of this package may be found at:
8 * Website: http://lttng.org/lttng2.0
9 * Releases: http://lttng.org/files/lttng-ust
10 * GitWeb: http://git.lttng.org (project: lttng-ust)
11 * Git: git://git.lttng.org/lttng-ust.git
17 Userspace RCU library, by Mathieu Desnoyers and Paul E. McKenney
19 -> This release depends on liburcu v0.7.2
21 * Debian/Ubuntu package: liburcu-dev
22 * Website: http://lttng.org/urcu
23 * Releases: http://lttng.org/files/urcu
24 * GitWeb: http://lttng.org/cgi-bin/gitweb.cgi?p=userspace-rcu.git;a=summary
25 * Git: git://lttng.org/userspace-rcu.git
28 * Debian/Ubuntu package: libuuid1, uuid-dev
29 * Fedora package: libuuid-devel
31 For developers using the git tree:
33 This source tree is based on the autotools suite from GNU to simplify
34 portability. Here are some things you should have on your system in order to
35 compile the git repository tree :
37 - GNU autotools (automake >=1.10, autoconf >=2.50, autoheader >=2.50)
38 (make sure your system wide "automake" points to a recent version!)
40 (for more information, go to http://www.gnu.org/software/autoconf/)
42 If you get the tree from the repository, you will need to use the "bootstrap"
43 script in the root of the tree. It calls all the GNU tools needed to prepare the
47 INSTALLATION INSTRUCTIONS:
49 - Download, compile and install liburcu.
50 - In this package's tree, run ./configure.
55 If compiling from the git repository, run ./bootstrap before running
56 the configure script, to generate it.
61 - Create an instrumentation header following the tracepoint examples.
62 See lttng/tracepoint.h, and examples.
64 There are 2 ways to compile the Tracepoint Provider with the
65 application: either statically or dynamically. Please follow
68 1.1) Compile the Tracepoint provider with the application, either
69 directly or through a static library (.a):
70 - Into exactly one object of your application: define
71 "TRACEPOINT_DEFINE" and include the tracepoint provider.
72 - Use "-I." for the compilation unit containing the tracepoint
73 provider include (e.g. tp.c).
74 - Link application with "-ldl" on Linux, with "-lc" on BSD.
75 - If building the provider directly into the application,
76 link the application with "-llttng-ust".
77 - If building a static library for the provider, link the static
78 library with "-lllttng-ust".
79 - Include the tracepoint provider header into all C files using
82 tests/hello/ hello.c tp.c ust_tests_hello.h Makefile.example.*
84 2) Compile the Tracepoint Provider separately from the application,
85 using dynamic linking:
86 - Into exactly one object of your application: define
87 "TRACEPOINT_DEFINE" _and_ also define
88 "TRACEPOINT_PROBE_DYNAMIC_LINKAGE", then include the tracepoint
90 - Include the tracepoint provider header into all instrumented C
91 files that use the provider.
92 - Compile the tracepoint provider with "-I.".
93 - Link the tracepoint provider with "-llttng-ust".
94 - Link application with "-ldl" on Linux, "-lc" on BSD.
95 - Set a LD_PRELOAD environment to preload the tracepoint provider
96 shared object before starting the application when tracing is
97 needed. Another way is to dlopen the tracepoint probe when needed
100 - tests/demo/ demo.c tp*.c ust_tests_demo*.h demo-trace
102 - Enable instrumentation and control tracing with the "lttng" command
103 from lttng-tools. See lttng-tools doc/quickstart.txt.
105 ENVIRONMENT VARIABLES:
107 - liblttng-ust debug can be activated by setting the environment variable
108 "LTTNG_UST_DEBUG" when launching the application. It can also be enabled
109 at compile-time by compiling libust with -DLTTNG_UST_DEBUG.
111 - The environment variable "LTTNG_UST_REGISTER_TIMEOUT" can be used to
112 specify how long the applications should wait for sessiond
113 "registration done" command before proceeding to execute the main
114 program. The default is 3000ms (3 seconds). The timeout value is
115 specified in milliseconds. The value 0 means "don't wait". The value
116 -1 means "wait forever". Setting this environment variable to 0 is
117 recommended for applications with time constraints on the process
120 - The compilation flag "-DLTTNG_UST_DEBUG_VALGRIND" should be enabled
121 at build time to allow liblttng-ust to be used with valgrind
122 (side-effect: disables per-cpu buffering).
127 Use babeltrace for viewing traces generated by LTTng UST 2.0.
128 See http://lttng.org for download.
133 Maintainer: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
134 Mailing list: lttng-dev@lists.lttng.org
139 This package contains the following elements.
142 The actual userspace tracing library that must be linked to the
143 instrumented programs.
146 The public header files that will be installed on the system.
149 Various test programs
151 - liblttng-ust-libc-wrapper
152 An example library that can be LD_PRELOAD'ed to instrument some
153 calls to libc (currently malloc() and free()) in any program without
154 need to recompile it.
157 A library that is LD_PRELOAD'ed, and that hijacks calls to several system
158 calls in order to trace across these calls. It _has_ to be LD_PRELOAD'ed
159 in order to hijack calls. In contrast, libust may be linked at build time.
162 A library to control tracing in other processes. Used by lttng-tools.
165 A static library shared between libust and lttng-tools, that
166 provides functions that allow these components to communicate together.
169 The ring buffer implementation used within LTTng-UST.
172 An asynchronous signal-safe version of snprintf.
175 A simple library that uses JNI to allow tracing in java programs.
176 See liblttng-ust-java/README for build instructions.