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: python3-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   Please note that some distributions will need the following
  96   environment variables set before running configure:
  97
  98     export PYTHON="python3"
  99     export PYTHON_CONFIG="/usr/bin/python3-config"
 100
 101 USAGE:
 102
 103 Please see doc/quickstart.txt to help you start tracing. You can also use the
 104 -h/--help command on 'lttng' and all other commands offered in this tool (Ex:
 105 lttng enable-event -h).
 106
 107 A network streaming HOWTO can be found in doc/streaming-howto.txt which quickly
 108 helps you understand how to stream a LTTng 2.0 trace.
 109
 110 A Python HOWTO can be found in doc/python-howto.txt which quickly
 111 helps you understand how to use the Python module to control the LTTng API.
 112
 113 PACKAGE CONTENTS:
 114
 115     This package contains the following elements:
 116
 117     - liblttng-ctl (public API)
 118       The LTTng tracing control library.
 119
 120     - libsessiond-comm (internal)
 121           The lttng-sessiond communication library. In order to talk with
 122           lttng-sessiond, this library must be used.
 123
 124     - libkernel-ctl (internal)
 125       Kernel tracer control and ioctl definitions.
 126
 127     - libconsumer (internal)
 128       Library for Kernel and (optionally) UST trace consumer.
 129
 130         - libkernel-consumer (internal)
 131           Library for Kernel consumer control
 132
 133         - libust-consumer (internal)
 134           Library for UST consumer control
 135
 136         - libhashtable (internal)
 137           Library wrapper over URCU hashtables.
 138
 139         - libcommon (internal)
 140           Contains multiple useful function call used by the whole tree.
 141
 142         - libcompat (internal)
 143           Compatibility library mostly for FreeBSD and Linux.
 144
 145         - librelayd (internal)
 146           Library for all relayd interactions over the network.
 147
 148         - lttng-relayd
 149           The relay daemon used for network streaming
 150
 151     - lttng-consumerd
 152       The consumer daemon which uses libconsumer.
 153
 154     - lttng-sessiond
 155       The LTTng session daemon binary.
 156
 157     - lttng
 158       The LTTng tracer command line control tool.
 159
 160     - include (installed in $(includedir)/lttng/)
 161       The liblttngctl API header file.
 162
 163     - tests
 164       Various test programs.
 165
 166         - doc
 167           Various documentations and quickstart guide.
 168
 169         - extras
 170           Contains extra data such as bash completion file. Python bindings for
 171           liblttng-ctl are also available there.