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   - Either compile the Tracepoint probes with the application:
  60     - Use "-I." for the compilation unit containing the tracepoint
  61       provider include (e.g. tp.c).
  62     - Link application with "-ldl -llttng-ust".
  63     - Example:
  64         tests/hello/  hello.c tp.c ust_tests_hello.h Makefile.example
  65   - Or compile the Tracepoint probes separately from the application,
  66     using dynamic linking:
  67     - Compile the tracepoint provider with "-I.".
  68     - Link the tracepoint provider with "-llttng-ust".
  69     - Link application with "-ldl".
  70     - Set a LD_PRELOAD environment to preload the tracepoint provider
  71       shared object before starting the application when tracing is
  72       needed.
  73     - Example:
  74       - tests/demo/   demo.c  tp*.c ust_tests_demo*.h demo-trace
  75   - Note about dlopen() usage: due to locking side-effects due to the
  76     way libc lazily resolves Thread-Local Storage (TLS) symbols when a
  77     library is dlopen'd, linking the tracepoint probe or liblttng-ust
  78     with dlopen() is discouraged. They should be linked with the
  79     application using "-llibname" or loaded with LD_PRELOAD.
  80   - Enable instrumentation and control tracing with the "lttng" command
  81     from lttng-tools. See lttng-tools doc/quickstart.txt.
  82
  83 ENVIRONMENT VARIABLES:
  84
  85   - liblttng-ust debug can be activated by setting the environment variable
  86     "LTTNG_UST_DEBUG" when launching the application. It can also be enabled
  87     at compile-time by compiling libust with -DLTTNG_UST_DEBUG.
  88
  89   - The environment variable "LTTNG_UST_REGISTER_TIMEOUT" can be used to
  90     specify how long the applications should wait for sessiond
  91     "registration done" command before proceeding to execute the main
  92     program. The default is 3000ms (3 seconds). The timeout value is
  93     specified in milliseconds. The value 0 means "don't wait". The value
  94     -1 means "wait forever". Setting this environment variable to 0 is
  95     recommended for applications with time constraints on the process
  96     startup time.
  97
  98
  99 TRACE VIEWER:
 100
 101   Use babeltrace for viewing traces generated by LTTng UST 2.0.
 102   See http://lttng.org for download.
 103
 104
 105 CONTACT:
 106
 107   Maintainer: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
 108   Mailing list: lttng-dev@lists.lttng.org
 109
 110
 111 PACKAGE CONTENTS:
 112
 113   This package contains the following elements.
 114
 115   - liblttng-ust
 116     The actual userspace tracing library that must be linked to the
 117     instrumented programs.
 118
 119   - include
 120     The public header files that will be installed on the system.
 121
 122   - tests
 123     Various test programs
 124
 125   - liblttng-ust-libc
 126     An example library that can be LD_PRELOAD'ed to instrument some
 127     calls to libc (currently malloc() and free()) in any program without
 128     need to recompile it.
 129
 130   - liblttng-ust-fork
 131     A library that is LD_PRELOAD'ed, and that hijacks calls to several system
 132     calls in order to trace across these calls. It _has_ to be LD_PRELOAD'ed
 133     in order to hijack calls. In contrast, libust may be linked at build time.
 134
 135   - liblttng-ust-ctl
 136     A library to control tracing in other processes. Used by lttng-tools.
 137
 138   - liblttng-ust-comm
 139     A static library shared between libust and lttng-tools, that
 140     provides functions that allow these components to communicate together.
 141
 142   - libringbuffer
 143     The ring buffer implementation used within LTTng-UST.
 144
 145   - snprintf
 146     An asynchronous signal-safe version of snprintf.
 147
 148   - liblttng-ust-java
 149     A simple library that uses JNI to allow tracing in java programs.
 150     See liblttng-ust-java/README for build instructions.