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
  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
  28 INSTALLATION INSTRUCTIONS:
  29
  30   - Download, compile and install liburcu.
  31   - In this package's tree, run ./configure.
  32   - Run make.
  33   - Run make install.
  34   - Run ldconfig.
  35   - See the manual for usage instructions.
  36
  37   If compiling from the git repository, run ./bootstrap before running
  38   the configure script, to generate it.
  39
  40
  41 USAGE:
  42
  43   - Create an instrumentation header following the tracepoint examples.
  44     (see tracepoint.h and tests/hello/tp.h).
  45   - Link application with -lust.
  46   - (TODO: start tracing with the "lttng" command from lttng-tools)
  47
  48 ENVIRONMENT VARIABLES:
  49
  50   - libust debug can be activated by setting the environment variable
  51     "UST_DEBUG" when launching the application. It can also be enabled
  52     at compile-time by compiling libust with -DUST_DEBUG.
  53
  54   - The environment variable "UST_REGISTER_TIMEOUT" can be used to
  55     specify how long the applications should wait for sessiond
  56     "registration done" command before proceeding to execute the main
  57     program. The default is 3000ms (3 seconds). The timeout value is
  58     specified in milliseconds. The value 0 means "don't wait". The value
  59     -1 means "wait forever".
  60
  61
  62 TRACE VIEWER:
  63
  64   LTTV is used for viewing UST traces. LTTV may be obtained at
  65   http://lttng.org in the Downloads section.
  66
  67   This release has been tested with LTTV 0.12.32.
  68
  69
  70 CONTACT:
  71
  72   Maintainer: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
  73   Mailing list: ltt-dev@lists.casi.polymtl.ca
  74
  75
  76 PACKAGE CONTENTS:
  77
  78   This package contains the following elements.
  79
  80   - libust
  81     The actual userspace tracing library that must be linked to the
  82     instrumented programs.
  83
  84   - ustctl
  85     A program to control the tracing of userspace applications. It can list
  86     markers, start the tracing, stop the tracing, enable/disable markers, etc.
  87
  88   - include
  89     The public header files that will be installed on the system.
  90
  91   - ust-consumerd
  92     The daemon that collects trace data and writes it to the disk.
  93
  94   - doc
  95     The documentation.
  96
  97   - tests
  98     Various test programs
  99
 100   - libustinstr-malloc
 101     An example library that can be LD_PRELOAD'ed to instrument calls to malloc()
 102     in any program without need to recompile it.
 103
 104   - libustfork
 105     A library that is LD_PRELOAD'ed, and that hijacks calls to several system
 106     calls in order to trace across these calls. It _has_ to be LD_PRELOAD'ed
 107     in order to hijack calls. In contrast, libust may be linked at build time.
 108
 109   - libustctl
 110     A library to control tracing in other processes. Used by ustctl.
 111
 112   - libustcomm
 113     A static library shared between libust, ust-consumerd and libustctl, that
 114     provides functions that allow these components to communicate together.
 115
 116   - libustconsumer
 117     A library to create ust consumers by registering callbacks, used by
 118     ust-consumerd.
 119
 120   - snprintf
 121     An asynchronous signal-safe version of snprintf.
 122
 123   - java
 124     A simple library that uses JNI to allow tracing in java programs.
 125     See java/README for build instructions.