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