1 LTTNG USERSPACE TRACER (LTTng-UST)
2 ----------------------------
4 UST web site: http://lttng.org
6 Updated versions of this package may be found at:
8 * Releases: http://lttng.org/download
9 * GitWeb: http://git.lttng.org (project: lttng-ust)
10 * Git: git://git.lttng.org/lttng-ust.git
16 Userspace RCU library, by Mathieu Desnoyers and Paul E. McKenney
18 -> This release depends on liburcu v0.7.2
20 * Debian/Ubuntu package: liburcu-dev
21 * Website: http://lttng.org/urcu
22 * Releases: http://lttng.org/files/urcu
23 * GitWeb: http://lttng.org/cgi-bin/gitweb.cgi?p=userspace-rcu.git;a=summary
24 * Git: git://git.urcu.so/userspace-rcu.git
26 For developers using the git tree:
28 This source tree is based on the autotools suite from GNU to simplify
29 portability. Here are some things you should have on your system in order to
30 compile the git repository tree :
32 - GNU autotools (automake >=1.10, autoconf >=2.50, autoheader >=2.50)
33 (make sure your system wide "automake" points to a recent version!)
35 (for more information, go to http://www.gnu.org/software/autoconf/)
37 Needed for make check and tests.
39 If you get the tree from the repository, you will need to use the "bootstrap"
40 script in the root of the tree. It calls all the GNU tools needed to prepare the
44 INSTALLATION INSTRUCTIONS:
46 - Download, compile and install liburcu.
47 - In this package's tree, run ./configure.
52 If compiling from the git repository, run ./bootstrap before running
53 the configure script, to generate it.
55 Note that configure sets '/usr/local' as the default prefix for files it
56 installs. However, this path is not part of most distributions' default
57 library path which will cause builds depending on liblttng-ust to fail unless
58 '-L/usr/local/lib' is added to LDFLAGS. You may provide a custom prefix to
59 configure by using the --prefix switch. Note that LTTng-UST needs to
60 be a shared library, even if the tracepoint probe provider is statically
61 linked into the application.
65 - Create an instrumentation header following the tracepoint examples.
66 See lttng/tracepoint.h, and examples.
68 There are 2 ways to compile the Tracepoint Provider with the
69 application: either statically or dynamically. Please follow
72 1.1) Compile the Tracepoint provider with the application, either
73 directly or through a static library (.a):
74 - Into exactly one object of your application: define
75 "TRACEPOINT_DEFINE" and include the tracepoint provider.
76 - Use "-I." for the compilation unit containing the tracepoint
77 provider include (e.g. tp.c).
78 - Link application with "-ldl" on Linux, with "-lc" on BSD.
79 - If building the provider directly into the application,
80 link the application with "-llttng-ust".
81 - If building a static library for the provider, link the static
82 library with "-llttng-ust".
83 - Include the tracepoint provider header into all C files using
86 - doc/examples/easy-ust/ sample.c sample_component_provider.h
88 - doc/examples/hello-static-lib/ hello.c tp.c ust_test_hello.h
91 2) Compile the Tracepoint Provider separately from the application,
92 using dynamic linking:
93 - Into exactly one object of your application: define
94 "TRACEPOINT_DEFINE" _and_ also define
95 "TRACEPOINT_PROBE_DYNAMIC_LINKAGE", then include the tracepoint
97 - Include the tracepoint provider header into all instrumented C
98 files that use the provider.
99 - Compile the tracepoint provider with "-I.".
100 - Link the tracepoint provider with "-llttng-ust".
101 - Link application with "-ldl" on Linux, "-lc" on BSD.
102 - Set a LD_PRELOAD environment to preload the tracepoint provider
103 shared object before starting the application when tracing is
104 needed. Another way is to dlopen the tracepoint probe when needed
107 - doc/examples/demo demo.c tp*.c ust_tests_demo*.h demo-trace Makefile
109 - Note about dlclose() usage: it is not safe to use dlclose on a
110 provider shared object that is being actively used for tracing due
111 to a lack of reference counting from lttng-ust to the used shared
113 - Enable instrumentation and control tracing with the "lttng" command
114 from lttng-tools. See lttng-tools doc/quickstart.txt.
115 - Note for C++ support: since LTTng-UST 2.3, both tracepoints and
116 tracepoint probes can be compiled in C++. To compile tracepoint probes
117 in C++, you need g++ >= 4.7 or Clang.
120 ENVIRONMENT VARIABLES:
122 - liblttng-ust debug can be activated by setting the environment variable
123 "LTTNG_UST_DEBUG" when launching the application. It can also be enabled
124 at compile-time by compiling libust with -DLTTNG_UST_DEBUG.
126 - The environment variable "LTTNG_UST_REGISTER_TIMEOUT" can be used to
127 specify how long the applications should wait for sessiond
128 "registration done" command before proceeding to execute the main
129 program. The default is 3000ms (3 seconds). The timeout value is
130 specified in milliseconds. The value 0 means "don't wait". The value
131 -1 means "wait forever". Setting this environment variable to 0 is
132 recommended for applications with time constraints on the process
135 - The compilation flag "-DLTTNG_UST_DEBUG_VALGRIND" should be enabled
136 at build time to allow liblttng-ust to be used with valgrind
137 (side-effect: disables per-cpu buffering).
142 Use babeltrace for viewing traces generated by LTTng UST 2.x.
143 See http://lttng.org for download.
148 Maintainer: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
149 Mailing list: lttng-dev@lists.lttng.org
154 This package contains the following elements.
157 The actual userspace tracing library that must be linked to the
158 instrumented programs.
161 The public header files that will be installed on the system.
164 Various test programs
166 - liblttng-ust-libc-wrapper
167 An example library that can be LD_PRELOAD'ed to instrument some
168 calls to libc (currently malloc() and free()) in any program without
169 need to recompile it.
172 A library that is LD_PRELOAD'ed, and that hijacks calls to several system
173 calls in order to trace across these calls. It _has_ to be LD_PRELOAD'ed
174 in order to hijack calls. In contrast, libust may be linked at build time.
177 A library to control tracing in other processes. Used by lttng-tools.
180 A static library shared between libust and lttng-tools, that
181 provides functions that allow these components to communicate together.
184 The ring buffer implementation used within LTTng-UST.
187 An asynchronous signal-safe version of snprintf.
190 A simple library that uses JNI to allow tracing in java programs.
191 See liblttng-ust-java/README for build instructions.