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://git.urcu.so/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   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.
  62
  63 USAGE:
  64
  65   - Create an instrumentation header following the tracepoint examples.
  66     See lttng/tracepoint.h, and examples.
  67
  68   There are 2 ways to compile the Tracepoint Provider with the
  69   application: either statically or dynamically. Please follow
  70   carefully:
  71
  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
  84       the provider.
  85     - Examples:
  86       - doc/examples/easy-ust/   sample.c sample_component_provider.h
  87         tp.c Makefile
  88       - doc/examples/hello-static-lib/   hello.c tp.c ust_test_hello.h
  89         Makefile
  90
  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
  96       provider header.
  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
 105       by the application.
 106     - Example:
 107       - doc/examples/demo   demo.c  tp*.c ust_tests_demo*.h demo-trace Makefile
 108
 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
 112     object.
 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.
 118
 119
 120 ENVIRONMENT VARIABLES:
 121
 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.
 125
 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
 133     startup time.
 134
 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).
 138
 139
 140 TRACE VIEWER:
 141
 142   Use babeltrace for viewing traces generated by LTTng UST 2.x.
 143   See http://lttng.org for download.
 144
 145
 146 CONTACT:
 147
 148   Maintainer: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
 149   Mailing list: lttng-dev@lists.lttng.org
 150
 151
 152 PACKAGE CONTENTS:
 153
 154   This package contains the following elements.
 155
 156   - liblttng-ust
 157     The actual userspace tracing library that must be linked to the
 158     instrumented programs.
 159
 160   - include
 161     The public header files that will be installed on the system.
 162
 163   - tests
 164     Various test programs
 165
 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.
 170
 171   - liblttng-ust-fork
 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.
 175
 176   - liblttng-ust-ctl
 177     A library to control tracing in other processes. Used by lttng-tools.
 178
 179   - liblttng-ust-comm
 180     A static library shared between libust and lttng-tools, that
 181     provides functions that allow these components to communicate together.
 182
 183   - libringbuffer
 184     The ring buffer implementation used within LTTng-UST.
 185
 186   - snprintf
 187     An asynchronous signal-safe version of snprintf.
 188
 189   - liblttng-ust-java
 190     A simple library that uses JNI to allow tracing in java programs.
 191     See liblttng-ust-java/README for build instructions.