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     - Perl (optional)
  35       Needed for make check and tests.
  36
  37     - Python >= 3.0 (optional)
  38       Needed for make check and tests.
  39
  40       * Debian/Ubuntu package: python3
  41
  42     - SWIG >= 2.0 (optional)
  43       Needed for Python bindings (--enable-python-bindings).
  44
  45       * Debian/Ubuntu package: swig2.0
  46
  47     - python-dev (optional)
  48       Python headers
  49
  50       * Debian/Ubuntu package: python-dev
  51
  52     - For kernel tracing: modprobe
  53
  54         - bash
  55           Needed for running "make check".
  56
  57 For developers using the git tree:
  58
  59 This source tree is based on the autotools suite from GNU to simplify
  60 portability. Here are some things you should have on your system in order to
  61 compile the git repository tree :
  62
  63 - GNU autotools (automake >=1.10, autoconf >=2.50, autoheader >=2.50)
  64   (make sure your system wide "automake" points to a recent version!)
  65 - GNU Libtool >=2.2
  66   (for more information, go to https://www.gnu.org/software/autoconf/)
  67 - flex >= 2.5.35
  68 - bison >= 2.4
  69
  70 If you use GNU gold, which is NOT mandatory, make sure you have this version:
  71 - GNU gold >= 2.22
  72 (Before this version we hit a known bug documented at:
  73  http://sourceware.org/bugzilla/show_bug.cgi?id=11317)
  74 Be advise that with GNU gold, you'll might have to specify -L/usr/local/lib in
  75 LDFLAGS.
  76
  77 If you get the tree from the repository, you will need to use the "bootstrap"
  78 script in the root of the tree. It calls all the GNU tools needed to prepare
  79 the tree configuration.
  80
  81 INSTALLATION INSTRUCTIONS:
  82
  83   - Download, compile and install the prerequisites.
  84   Then:
  85   $ ./boostrap
  86   $ ./configure
  87   $ make
  88   $ sudo make install
  89   $ sudo ldconfig
  90
  91   If compiling from the git repository, run ./bootstrap before running
  92   the configure script, to generate it.
  93
  94   If you want Python bindings, run ./configure --enable-python-bindings.
  95
  96 USAGE:
  97
  98 Please see doc/quickstart.txt to help you start tracing. You can also use the
  99 -h/--help command on 'lttng' and all other commands offered in this tool (Ex:
 100 lttng enable-event -h).
 101
 102 A network streaming HOWTO can be found in doc/streaming-howto.txt which quickly
 103 helps you understand how to stream a LTTng 2.0 trace.
 104
 105 A Python HOWTO can be found in doc/python-howto.txt which quickly
 106 helps you understand how to use the Python module to control the LTTng API.
 107
 108 PACKAGE CONTENTS:
 109
 110     This package contains the following elements:
 111
 112     - liblttng-ctl (public API)
 113       The LTTng tracing control library.
 114
 115     - libsessiond-comm (internal)
 116           The lttng-sessiond communication library. In order to talk with
 117           lttng-sessiond, this library must be used.
 118
 119     - libkernel-ctl (internal)
 120       Kernel tracer control and ioctl definitions.
 121
 122     - libconsumer (internal)
 123       Library for Kernel and (optionally) UST trace consumer.
 124
 125         - libkernel-consumer (internal)
 126           Library for Kernel consumer control
 127
 128         - libust-consumer (internal)
 129           Library for UST consumer control
 130
 131         - libhashtable (internal)
 132           Library wrapper over URCU hashtables.
 133
 134         - libcommon (internal)
 135           Contains multiple useful function call used by the whole tree.
 136
 137         - libcompat (internal)
 138           Compatibility library mostly for FreeBSD and Linux.
 139
 140         - librelayd (internal)
 141           Library for all relayd interactions over the network.
 142
 143         - lttng-relayd
 144           The relay daemon used for network streaming
 145
 146     - lttng-consumerd
 147       The consumer daemon which uses libconsumer.
 148
 149     - lttng-sessiond
 150       The LTTng session daemon binary.
 151
 152     - lttng
 153       The LTTng tracer command line control tool.
 154
 155     - include (installed in $(includedir)/lttng/)
 156       The liblttngctl API header file.
 157
 158     - tests
 159       Various test programs.
 160
 161         - doc
 162           Various documentations and quickstart guide.
 163
 164         - extras
 165           Contains extra data such as bash completion file. Python bindings for
 166           liblttng-ctl are also available there.