-LTTNG USERSPACE TRACER (UST)
+LTTNG USERSPACE TRACER (LTTng-UST)
----------------------------
-UST web site and manual: http://lttng.org/ust
+UST web site: http://lttng.org
Updated versions of this package may be found at:
- * Website: http://lttng.org/ust
- * Releases: http://lttng.org/files/ust/releases
- * GitWeb: http://git.lttng.org (project: ust)
- * Git: git://git.lttng.org/ust.git
+ * Releases: http://lttng.org/download
+ * 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
+ -> This release depends on liburcu v0.7.2
* 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
+ * Git: git://git.urcu.so/userspace-rcu.git
For developers using the git tree:
(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/)
+- Perl (optional)
+ Needed for make check and tests.
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
- Run make.
- Run make install.
- Run ldconfig.
- - See the manual for usage instructions.
If compiling from the git repository, run ./bootstrap before running
the configure script, to generate it.
+ Note that configure 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. Note that LTTng-UST needs to
+ be a shared library, even if the tracepoint probe provider is statically
+ linked into the application.
USAGE:
- Create an instrumentation header following the tracepoint examples.
- (see tracepoint.h and tests/hello/tp.h).
- - Link application with -lust.
- - (TODO: start tracing with the "lttng" command from lttng-tools)
+ See lttng/tracepoint.h, and examples.
+
+ There are 2 ways to compile the Tracepoint Provider with the
+ application: either statically or dynamically. Please follow
+ carefully:
+
+ 1.1) Compile the Tracepoint provider with the application, either
+ directly or through a static library (.a):
+ - Into exactly one object of your application: define
+ "TRACEPOINT_DEFINE" and include the tracepoint provider.
+ - Use "-I." for the compilation unit containing the tracepoint
+ provider include (e.g. tp.c).
+ - Link application with "-ldl" on Linux, with "-lc" on BSD.
+ - If building the provider directly into the application,
+ link the application with "-llttng-ust".
+ - If building a static library for the provider, link the static
+ library with "-llttng-ust".
+ - Include the tracepoint provider header into all C files using
+ the provider.
+ - Examples:
+ - doc/examples/easy-ust/ sample.c sample_component_provider.h
+ tp.c Makefile
+ - doc/examples/hello-static-lib/ hello.c tp.c ust_test_hello.h
+ Makefile
+
+ 2) Compile the Tracepoint Provider separately from the application,
+ using dynamic linking:
+ - Into exactly one object of your application: define
+ "TRACEPOINT_DEFINE" _and_ also define
+ "TRACEPOINT_PROBE_DYNAMIC_LINKAGE", then include the tracepoint
+ provider header.
+ - Include the tracepoint provider header into all instrumented C
+ files that use the provider.
+ - Compile the tracepoint provider with "-I.".
+ - Link the tracepoint provider with "-llttng-ust".
+ - Link application with "-ldl" on Linux, "-lc" on BSD.
+ - Set a LD_PRELOAD environment to preload the tracepoint provider
+ shared object before starting the application when tracing is
+ needed. Another way is to dlopen the tracepoint probe when needed
+ by the application.
+ - Example:
+ - doc/examples/demo demo.c tp*.c ust_tests_demo*.h demo-trace Makefile
+
+ - Note about dlclose() usage: it is not safe to use dlclose on a
+ provider shared object that is being actively used for tracing due
+ to a lack of reference counting from lttng-ust to the used shared
+ object.
+ - Enable instrumentation and control tracing with the "lttng" command
+ from lttng-tools. See lttng-tools doc/quickstart.txt.
+ - Note for C++ support: since LTTng-UST 2.3, both tracepoints and
+ tracepoint probes can be compiled in C++. To compile tracepoint probes
+ in C++, you need g++ >= 4.7 or Clang.
+
ENVIRONMENT VARIABLES:
"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".
+ -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).
TRACE VIEWER:
- Use babeltrace for viewing traces generated by LTTng UST 2.0.
+ Use babeltrace for viewing traces generated by LTTng UST 2.x.
See http://lttng.org for download.
CONTACT:
Maintainer: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
- Mailing list: ltt-dev@lists.casi.polymtl.ca
+ Mailing list: lttng-dev@lists.lttng.org
PACKAGE CONTENTS:
- include
The public header files that will be installed on the system.
- - doc
- The documentation.
-
- tests
Various test programs
- - liblttng-ust-malloc
- An example library that can be LD_PRELOAD'ed to instrument calls to malloc()
- in any program without need to recompile it.
+ - liblttng-ust-libc-wrapper
+ 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
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.
- - java
+ - liblttng-ust-java
A simple library that uses JNI to allow tracing in java programs.
- See java/README for build instructions.
+ See liblttng-ust-java/README for build instructions.
projects / lttng-ust.git / blobdiff