README

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