README

   1 LTTNG USERSPACE TRACER (LTTng-UST)
   2 ----------------------------
   3
   4 UST web site: http://lttng.org
   5
   6 Updated versions of this package may be found at:
   7
   8   * Releases: http://lttng.org/download
   9   * GitWeb:   http://git.lttng.org (project: lttng-ust)
  10   * Git:      git://git.lttng.org/lttng-ust.git
  11
  12
  13 PREREQUISITES:
  14
  15   - liburcu
  16     Userspace RCU library, by Mathieu Desnoyers and Paul E. McKenney
  17
  18     -> This release depends on liburcu v0.7.2
  19
  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://lttng.org/userspace-rcu.git
  25
  26 For developers using the git tree:
  27
  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 :
  31
  32 - GNU autotools (automake >=1.10, autoconf >=2.50, autoheader >=2.50)
  33   (make sure your system wide "automake" points to a recent version!)
  34 - GNU Libtool >=2.2
  35   (for more information, go to http://www.gnu.org/software/autoconf/)
  36 - Perl (optional)
  37   Needed for make check and tests.
  38
  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
  41 tree configuration.
  42
  43
  44 INSTALLATION INSTRUCTIONS:
  45
  46   - Download, compile and install liburcu.
  47   - In this package's tree, run ./configure.
  48   - Run make.
  49   - Run make install.
  50   - Run ldconfig.
  51
  52   If compiling from the git repository, run ./bootstrap before running
  53   the configure script, to generate it.
  54
  55
  56 USAGE:
  57
  58   - Create an instrumentation header following the tracepoint examples.
  59     See lttng/tracepoint.h, and examples.
  60
  61   There are 2 ways to compile the Tracepoint Provider with the
  62   application: either statically or dynamically. Please follow
  63   carefully:
  64
  65   1.1) Compile the Tracepoint provider with the application, either
  66        directly or through a static library (.a):
  67     - Into exactly one object of your application: define
  68       "TRACEPOINT_DEFINE" and include the tracepoint provider.
  69     - Use "-I." for the compilation unit containing the tracepoint
  70       provider include (e.g. tp.c).
  71     - Link application with "-ldl" on Linux, with "-lc" on BSD.
  72     - If building the provider directly into the application,
  73       link the application with "-llttng-ust".
  74     - If building a static library for the provider, link the static
  75       library with "-llttng-ust".
  76     - Include the tracepoint provider header into all C files using
  77       the provider.
  78     - Examples:
  79       - doc/examples/easy-ust/   sample.c sample_component_provider.h
  80         tp.c Makefile
  81       - doc/examples/hello-static-lib/   hello.c tp.c ust_test_hello.h
  82         Makefile
  83
  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
  89       provider header.
  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
  98       by the application.
  99     - Example:
 100       - doc/examples/demo   demo.c  tp*.c ust_tests_demo*.h demo-trace Makefile
 101
 102   - Note about dlclose() usage: it is not safe to use dlclose on a
 103     provider shared object that is being actively used for tracing due
 104     to a lack of reference counting from lttng-ust to the used shared
 105     object.
 106   - Enable instrumentation and control tracing with the "lttng" command
 107     from lttng-tools. See lttng-tools doc/quickstart.txt.
 108   - Note for C++ support: although an application instrumented with
 109     tracepoints can be compiled with g++, tracepoint probes should be
 110     compiled with gcc (only tested with gcc so far).
 111
 112
 113 ENVIRONMENT VARIABLES:
 114
 115   - liblttng-ust debug can be activated by setting the environment variable
 116     "LTTNG_UST_DEBUG" when launching the application. It can also be enabled
 117     at compile-time by compiling libust with -DLTTNG_UST_DEBUG.
 118
 119   - The environment variable "LTTNG_UST_REGISTER_TIMEOUT" can be used to
 120     specify how long the applications should wait for sessiond
 121     "registration done" command before proceeding to execute the main
 122     program. The default is 3000ms (3 seconds). The timeout value is
 123     specified in milliseconds. The value 0 means "don't wait". The value
 124     -1 means "wait forever". Setting this environment variable to 0 is
 125     recommended for applications with time constraints on the process
 126     startup time.
 127
 128   - The compilation flag "-DLTTNG_UST_DEBUG_VALGRIND" should be enabled
 129     at build time to allow liblttng-ust to be used with valgrind
 130     (side-effect: disables per-cpu buffering).
 131
 132
 133 TRACE VIEWER:
 134
 135   Use babeltrace for viewing traces generated by LTTng UST 2.x.
 136   See http://lttng.org for download.
 137
 138
 139 CONTACT:
 140
 141   Maintainer: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
 142   Mailing list: lttng-dev@lists.lttng.org
 143
 144
 145 PACKAGE CONTENTS:
 146
 147   This package contains the following elements.
 148
 149   - liblttng-ust
 150     The actual userspace tracing library that must be linked to the
 151     instrumented programs.
 152
 153   - include
 154     The public header files that will be installed on the system.
 155
 156   - tests
 157     Various test programs
 158
 159   - liblttng-ust-libc-wrapper
 160     An example library that can be LD_PRELOAD'ed to instrument some
 161     calls to libc (currently malloc() and free()) in any program without
 162     need to recompile it.
 163
 164   - liblttng-ust-fork
 165     A library that is LD_PRELOAD'ed, and that hijacks calls to several system
 166     calls in order to trace across these calls. It _has_ to be LD_PRELOAD'ed
 167     in order to hijack calls. In contrast, libust may be linked at build time.
 168
 169   - liblttng-ust-ctl
 170     A library to control tracing in other processes. Used by lttng-tools.
 171
 172   - liblttng-ust-comm
 173     A static library shared between libust and lttng-tools, that
 174     provides functions that allow these components to communicate together.
 175
 176   - libringbuffer
 177     The ring buffer implementation used within LTTng-UST.
 178
 179   - snprintf
 180     An asynchronous signal-safe version of snprintf.
 181
 182   - liblttng-ust-java
 183     A simple library that uses JNI to allow tracing in java programs.
 184     See liblttng-ust-java/README for build instructions.