README

   1 LTTNG USERSPACE TRACER (UST)
   2 ----------------------------
   3
   4 UST web site and manual: http://lttng.org/ust
   5
   6 Updated versions of this package may be found at:
   7
   8   * Website:  http://lttng.org/ust
   9   * Releases: http://lttng.org/files/ust/releases
  10   * GitWeb:   http://git.lttng.org (project: ust)
  11   * Git:      git://git.lttng.org/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   - See the manual for usage instructions.
  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 tracepoint.h and tests/hello/tp.h).
  60   - Link application with -lust.
  61   - (TODO: start tracing with the "lttng" command from lttng-tools)
  62
  63 ENVIRONMENT VARIABLES:
  64
  65   - liblttng-ust debug can be activated by setting the environment variable
  66     "LTTNG_UST_DEBUG" when launching the application. It can also be enabled
  67     at compile-time by compiling libust with -DLTTNG_UST_DEBUG.
  68
  69   - The environment variable "LTTNG_UST_REGISTER_TIMEOUT" can be used to
  70     specify how long the applications should wait for sessiond
  71     "registration done" command before proceeding to execute the main
  72     program. The default is 3000ms (3 seconds). The timeout value is
  73     specified in milliseconds. The value 0 means "don't wait". The value
  74     -1 means "wait forever".
  75
  76
  77 TRACE VIEWER:
  78
  79   Use babeltrace for viewing traces generated by LTTng UST 2.0.
  80   See http://lttng.org for download.
  81
  82
  83 CONTACT:
  84
  85   Maintainer: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
  86   Mailing list: ltt-dev@lists.casi.polymtl.ca
  87
  88
  89 PACKAGE CONTENTS:
  90
  91   This package contains the following elements.
  92
  93   - liblttng-ust
  94     The actual userspace tracing library that must be linked to the
  95     instrumented programs.
  96
  97   - include
  98     The public header files that will be installed on the system.
  99
 100   - doc
 101     The documentation.
 102
 103   - tests
 104     Various test programs
 105
 106   - liblttng-ust-malloc
 107     An example library that can be LD_PRELOAD'ed to instrument calls to malloc()
 108     in any program without need to recompile it.
 109
 110   - liblttng-ust-fork
 111     A library that is LD_PRELOAD'ed, and that hijacks calls to several system
 112     calls in order to trace across these calls. It _has_ to be LD_PRELOAD'ed
 113     in order to hijack calls. In contrast, libust may be linked at build time.
 114
 115   - liblttng-ust-ctl
 116     A library to control tracing in other processes. Used by lttng-tools.
 117
 118   - liblttng-ust-comm
 119     A static library shared between libust and lttng-tools, that
 120     provides functions that allow these components to communicate together.
 121
 122   - snprintf
 123     An asynchronous signal-safe version of snprintf.
 124
 125   - java
 126     A simple library that uses JNI to allow tracing in java programs.
 127     See java/README for build instructions.