README

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