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   Note: libust debug can be activated by either of the following means:
  49     - Setting the environment variable "UST_DEBUG" when launching the
  50       application.
  51     - Compiling libust with -DUST_DEBUG.
  52
  53
  54 TRACE VIEWER:
  55
  56   LTTV is used for viewing UST traces. LTTV may be obtained at
  57   http://lttng.org in the Downloads section.
  58
  59   This release has been tested with LTTV 0.12.32.
  60
  61
  62 CONTACT:
  63
  64   Maintainer: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
  65   Mailing list: ltt-dev@lists.casi.polymtl.ca
  66
  67
  68 PACKAGE CONTENTS:
  69
  70   This package contains the following elements.
  71
  72   - libust
  73     The actual userspace tracing library that must be linked to the
  74     instrumented programs.
  75
  76   - ustctl
  77     A program to control the tracing of userspace applications. It can list
  78     markers, start the tracing, stop the tracing, enable/disable markers, etc.
  79
  80   - include
  81     The public header files that will be installed on the system.
  82
  83   - ust-consumerd
  84     The daemon that collects trace data and writes it to the disk.
  85
  86   - doc
  87     The documentation.
  88
  89   - tests
  90     Various test programs
  91
  92   - libustinstr-malloc
  93     An example library that can be LD_PRELOAD'ed to instrument calls to malloc()
  94     in any program without need to recompile it.
  95
  96   - libustfork
  97     A library that is LD_PRELOAD'ed, and that hijacks calls to several system
  98     calls in order to trace across these calls. It _has_ to be LD_PRELOAD'ed
  99     in order to hijack calls. In contrast, libust may be linked at build time.
 100
 101   - libustctl
 102     A library to control tracing in other processes. Used by ustctl.
 103
 104   - libustcomm
 105     A static library shared between libust, ust-consumerd and libustctl, that
 106     provides functions that allow these components to communicate together.
 107
 108   - libustconsumer
 109     A library to create ust consumers by registering callbacks, used by
 110     ust-consumerd.
 111
 112   - snprintf
 113     An asynchronous signal-safe version of snprintf.
 114
 115   - java
 116     A simple library that uses JNI to allow tracing in java programs.