README

   1 LTTng Trace Control
   2 ----------------
   3
   4 Please visit https://lttng.org for more information. The current maintainer is
   5 David Goulet <dgoulet@efficios.com>.
   6
   7 Latest development can be found at:
   8
   9     * Gitweb :  https://git.lttng.org/?p=lttng-tools.git;a=summary
  10     * Git :     git://git.lttng.org/lttng-tools.git
  11
  12 REQUIREMENTS:
  13
  14         - Linux kernel >= 2.6.27
  15           For epoll() support, at least this version is needed. However, poll() is
  16           also supported by running "./configure --disable-epoll". Using that, the
  17           kernel version can probably be older but we can't provide any guarantee.
  18           Please let us know if you are able to go lower without any problems.
  19
  20     - liburcu
  21       Userspace RCU library, by Mathieu Desnoyers and Paul E. McKenney
  22
  23       -> Tested with liburcu 0.7.x stable.
  24
  25       * Debian/Ubuntu package: liburcu-dev
  26       * Git : git://git.lttng.org/userspace-rcu.git
  27       * Website:  https://lttng.org/urcu
  28
  29     - libpopt >= 1.13
  30       Library for parsing command line parameters
  31
  32       * Debian/Ubuntu package: libpopt-dev
  33
  34     - libuuid
  35       Universally unique id library
  36
  37       * Debian/Ubuntu package: uuid-dev
  38
  39     - Perl (optional)
  40       Needed for make check and tests.
  41
  42     - Python >= 3.0 (optional)
  43       Needed for make check and tests.
  44
  45       * Debian/Ubuntu package: python3
  46
  47     - SWIG >= 2.0 (optional)
  48       Needed for Python bindings (--enable-python-bindings).
  49
  50       * Debian/Ubuntu package: swig2.0
  51
  52     - python-dev (optional)
  53       Python headers
  54
  55       * Debian/Ubuntu package: python3-dev
  56
  57     - For kernel tracing: modprobe
  58
  59         - bash
  60           Needed for running "make check".
  61
  62 For developers using the git tree:
  63
  64 This source tree is based on the autotools suite from GNU to simplify
  65 portability. Here are some things you should have on your system in order to
  66 compile the git repository tree :
  67
  68 - GNU autotools (automake >=1.10, autoconf >=2.50, autoheader >=2.50)
  69   (make sure your system wide "automake" points to a recent version!)
  70 - GNU Libtool >=2.2
  71   (for more information, go to https://www.gnu.org/software/autoconf/)
  72 - flex >= 2.5.35
  73 - bison >= 2.4
  74
  75 If you use GNU gold, which is NOT mandatory, make sure you have this version:
  76 - GNU gold >= 2.22
  77 (Before this version we hit a known bug documented at:
  78  http://sourceware.org/bugzilla/show_bug.cgi?id=11317)
  79 Be advise that with GNU gold, you'll might have to specify -L/usr/local/lib in
  80 LDFLAGS.
  81
  82 If you get the tree from the repository, you will need to use the "bootstrap"
  83 script in the root of the tree. It calls all the GNU tools needed to prepare
  84 the tree configuration.
  85
  86 INSTALLATION INSTRUCTIONS:
  87
  88   - Download, compile and install the prerequisites.
  89   Then:
  90   $ ./boostrap
  91   $ ./configure
  92   $ make
  93   $ sudo make install
  94   $ sudo ldconfig
  95
  96   If compiling from the git repository, run ./bootstrap before running
  97   the configure script, to generate it.
  98
  99   If you want Python bindings, run ./configure --enable-python-bindings.
 100   Please note that some distributions will need the following
 101   environment variables set before running configure:
 102
 103     export PYTHON="python3"
 104     export PYTHON_CONFIG="/usr/bin/python3-config"
 105
 106 USAGE:
 107
 108 Please see doc/quickstart.txt to help you start tracing. You can also use the
 109 -h/--help command on 'lttng' and all other commands offered in this tool (Ex:
 110 lttng enable-event -h).
 111
 112 A network streaming HOWTO can be found in doc/streaming-howto.txt which quickly
 113 helps you understand how to stream a LTTng 2.0 trace.
 114
 115 A Python HOWTO can be found in doc/python-howto.txt which quickly
 116 helps you understand how to use the Python module to control the LTTng API.
 117
 118 PACKAGE CONTENTS:
 119
 120     This package contains the following elements:
 121
 122     - liblttng-ctl (public API)
 123       The LTTng tracing control library.
 124
 125     - libsessiond-comm (internal)
 126           The lttng-sessiond communication library. In order to talk with
 127           lttng-sessiond, this library must be used.
 128
 129     - libkernel-ctl (internal)
 130       Kernel tracer control and ioctl definitions.
 131
 132     - libconsumer (internal)
 133       Library for Kernel and (optionally) UST trace consumer.
 134
 135         - libkernel-consumer (internal)
 136           Library for Kernel consumer control
 137
 138         - libust-consumer (internal)
 139           Library for UST consumer control
 140
 141         - libhashtable (internal)
 142           Library wrapper over URCU hashtables.
 143
 144         - libcommon (internal)
 145           Contains multiple useful function call used by the whole tree.
 146
 147         - libcompat (internal)
 148           Compatibility library mostly for FreeBSD and Linux.
 149
 150         - librelayd (internal)
 151           Library for all relayd interactions over the network.
 152
 153         - lttng-relayd
 154           The relay daemon used for network streaming
 155
 156     - lttng-consumerd
 157       The consumer daemon which uses libconsumer.
 158
 159     - lttng-sessiond
 160       The LTTng session daemon binary.
 161
 162     - lttng
 163       The LTTng tracer command line control tool.
 164
 165     - include (installed in $(includedir)/lttng/)
 166       The liblttngctl API header file.
 167
 168     - tests
 169       Various test programs.
 170
 171         - doc
 172           Various documentations and quickstart guide.
 173
 174         - extras
 175           Contains extra data such as bash completion file. Python bindings for
 176           liblttng-ctl are also available there.