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