+++ /dev/null
-LTTNG USERSPACE TRACER (LTTng-UST)
-----------------------------
-
-UST web site: http://lttng.org
-
-Updated versions of this package may be found at:
-
- * 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.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://git.urcu.so/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/)
-- 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
-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.
-
- 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 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:
-
- - 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.
-
- - 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.x.
- See http://lttng.org for download.
-
-
-CONTACT:
-
- Maintainer: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
- 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-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
- 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.
projects / lttng-ust.git / blobdiff