README.adoc

   1 // Render with Asciidoctor
   2
   3 :nbh: &#8209;
   4 :lt: LTTng{nbh}tools
   5 :lib: liblttng{nbh}ctl
   6
   7 ifdef::env-github[]
   8 :toc: macro
   9 endif::env-github[]
  10
  11 ifndef::env-github[]
  12 :toc: left
  13 endif::env-github[]
  14
  15 = {lt}
  16 5 May 2020
  17
  18 [.normal]
  19 https://ci.lttng.org/job/lttng-tools_master_linuxbuild/[image:https://img.shields.io/jenkins/build.svg?jobUrl=https://ci.lttng.org/job/lttng-tools_master_linuxbuild/[Jenkins, title="Jenkins"]]
  20 https://scan.coverity.com/projects/lttng-tools[image:https://img.shields.io/coverity/scan/lttng-tools.svg[Coverity, title="Coverity"]]
  21
  22 [.lead]
  23 _**{lt}**_ is a set of components to control https://lttng.org/[LTTng]
  24 tracing.
  25
  26 The project includes:
  27
  28 * The LTTng https://lttng.org/man/8/lttng-sessiond/[session daemon].
  29
  30 * The LTTng consumer daemon.
  31
  32 * The LTTng https://lttng.org/man/8/lttng-relayd/[relay daemon].
  33
  34 * {lib}, a library with a C{nbsp}API used to communicate with
  35   the session daemon.
  36
  37 * Python{nbsp}3 bindings of liblttng{nbh}ctl.
  38
  39 * https://lttng.org/man/1/lttng/[`lttng`], a command-line tool over
  40   {lib}.
  41
  42 * https://lttng.org/man/1/lttng-crash/[`lttng{nbh}crash`], a command-line
  43   tool to recover and view LTTng{nbsp}2 trace buffers in the event of a
  44   crash.
  45
  46 ifdef::env-github[]
  47 toc::[]
  48 endif::env-github[]
  49
  50 == Required and optional dependencies
  51
  52 You need the following dependencies to build and run the {lt}
  53 components:
  54
  55 * **Linux kernel{nbsp}≥{nbsp}2.6.30**
  56
  57 * **http://www.liburcu.org/[Userspace{nbsp}RCU]{nbsp}≥{nbsp}0.14.0**.
  58 +
  59 Debian/Ubuntu package: `liburcu{nbh}dev`.
  60
  61 * **popt{nbsp}≥{nbsp}1.13**
  62 +
  63 Debian/Ubuntu package: `libpopt{nbh}dev`.
  64
  65 * **http://xmlsoft.org/[Libxml2]{nbsp}≥{nbsp}2.7.6**
  66 +
  67 Debian/Ubuntu package: `libxml2{nbh}dev`
  68
  69 The following dependencies are optional:
  70
  71 * **https://babeltrace.org/[Babeltrace{nbsp}2]**: default viewer
  72   of the https://lttng.org/man/1/lttng-view/[`lttng view`] command,
  73   `make{nbsp}check` and tests.
  74 +
  75 Debian/Ubuntu package: `babeltrace2 libbabeltrace2-dev`
  76
  77 * **https://lttng.org/[LTTng{nbh}UST]** (same minor version as {lt}):
  78   LTTng user space tracing (applications and libraries).
  79 +
  80 Debian/Ubuntu package: `liblttng{nbh}ust{nbh}dev`
  81
  82 * **https://www.python.org/[Python]{nbsp}≥{nbsp}3.4**:
  83   `make{nbsp}check` and tests.
  84 +
  85 Debian/Ubuntu package: `python3`
  86
  87 * **http://www.swig.org/[SWIG]{nbsp}≥{nbsp}2.0** and
  88   **Python{nbsp}3 development headers**: Python bindings
  89   (enabled at <<configure,build configuration>> time with the
  90   `{nbh}{nbh}enable{nbh}python{nbh}bindings` option).
  91 +
  92 Debian/Ubuntu packages: `swig2.0` and `python3{nbh}dev`
  93
  94 * **modprobe** and/or
  95   **https://git.kernel.org/pub/scm/utils/kernel/kmod/kmod.git/[kmod]{nbsp}≥{nbsp}22**:
  96   automatic LTTng kernel modules loading (kernel tracing).
  97
  98 * **Bash**: `make{nbsp}check`.
  99
 100 * **http://man7.org/linux/man-pages/man1/man.1.html[`man`]**
 101   (manual pager): view `lttng` command manual
 102   pages with the `{nbh}{nbh}help` option or with the
 103   https://lttng.org/man/1/lttng-help/[`lttng{nbsp}help`] command.
 104 +
 105 NOTE: You can use the <<configure,build configuration>> option
 106 `{nbh}{nbh}enable{nbh}embedded{nbh}help` to embed the manual pages into
 107 the `lttng`, `lttng{nbh}sessiond`, `lttng{nbh}relayd`, and
 108 `lttng{nbh}crash` programs so that you don't need `man` to view them.
 109
 110 * **http://perfmon2.sourceforge.net/[libpfm]{nbsp}≥{nbsp}4.0**:
 111   perf regression test suite.
 112 +
 113 Debian/Ubuntu package: `libpfm4-dev`
 114
 115 {lt} supports both the LTTng Linux kernel tracer and LTTng user space
 116 tracer sharing the same _minor_ version. While some minor releases do
 117 not change the tracer ABIs and _could_ work, no testing is performed to
 118 ensure that cross-version compatibility is maintained.
 119
 120 You don't need to rebuild or modify applications instrumented with older
 121 versions of the LTTng{nbh}UST project to make them work with the
 122 components of the latest {lt} release.
 123
 124 See the https://lttng.org/docs/[LTTng Documentation] for more
 125 information on versioning.
 126
 127 == Build from source
 128
 129 === Dependencies
 130
 131 You need the following tools to build {lt}:
 132
 133 * **https://www.gnu.org/software/automake/manual/html_node/Autotools-Introduction.html[GNU{nbsp}Autotools]**
 134   (**Automake{nbsp}≥{nbsp}1.12**,
 135   **Autoconf{nbsp}≥{nbsp}2.64**, and **Autoheader{nbsp}≥{nbsp}2.50**)
 136
 137 * **http://www.gnu.org/software/autoconf/[GNU{nbsp}Libtool]{nbsp}≥{nbsp}2.2**
 138
 139 * **https://github.com/westes/flex/[Flex]{nbsp}≥{nbsp}2.5.35**
 140
 141 * **https://www.gnu.org/software/bison/[Bison]{nbsp}≥{nbsp}2.4**
 142
 143 To build the {lt} manual pages:
 144
 145 * **https://asciidoc.org/[AsciiDoc]{nbsp}≥{nbsp}8.4.5**
 146 +
 147 NOTE: Previous versions could work, but were not tested.
 148
 149 * **https://pagure.io/xmlto[xmlto]{nbsp}≥{nbsp}0.0.21**
 150 +
 151 NOTE: Previous versions could work, but were not tested.
 152
 153 If you use GNU{nbsp}gold, which is _not_ mandatory:
 154
 155 * **GNU{nbsp}gold{nbsp}≥{nbsp}2.22**
 156
 157 NOTE: With GNU{nbsp}gold, you might need to add
 158 `-L/usr/local/lib` to the `LDFLAGS` environment variable.
 159
 160 === Build steps
 161
 162 . **If you have the {lt} Git source**, run:
 163 +
 164 ----
 165 $ ./bootstrap
 166 ----
 167 +
 168 This script creates the `configure` script.
 169
 170 . [[configure]]Configure the build:
 171 +
 172 --
 173 ----
 174 $ ./configure
 175 ----
 176
 177 If you want the {lib} Python bindings, use the
 178 `{nbh}{nbh}enable{nbh}python{nbh}bindings` option. See also the `PYTHON`
 179 and `PYTHON_CONFIG` environment variables in
 180 `./configure{nbsp}{nbh}{nbh}help`.
 181
 182 If you don't want to build the manual pages, use the
 183 `{nbh}{nbh}disable{nbh}man{nbh}pages` option.
 184
 185 If you want to embed the manual pages into the `lttng`,
 186 `lttng{nbh}sessiond`, `lttng{nbh}relayd`, and `lttng{nbh}crash` programs
 187 so that you don't need `man` to view them, use the
 188 `{nbh}{nbh}enable{nbh}embedded{nbh}help` option.
 189
 190 This build configuration script finds LTTng{nbh}UST with
 191 https://www.freedesktop.org/wiki/Software/pkg-config/[pkg{nbh}config]:
 192 set the `PKG_CONFIG_PATH` environment variable accordingly if
 193 pkg{nbh}config cannot find the `lttng{nbh}ust` package information.
 194
 195 See `./configure{nbsp}{nbh}{nbh}help` for the complete list of options.
 196 --
 197
 198 . Build the project:
 199 +
 200 ----
 201 $ make
 202 ----
 203
 204 . Install the project:
 205 +
 206 ----
 207 $ sudo make install
 208 $ sudo ldconfig
 209 ----
 210
 211 == Usage
 212
 213 See the https://lttng.org/docs/#doc-controlling-tracing[Tracing control]
 214 section of the LTTng Documentation to learn how to use the {lt}
 215 components.
 216
 217 See also the https://lttng.org/man/[LTTng manual pages] (all
 218 section{nbsp}1 and{nbsp}8 pages).
 219
 220 As there's no official {lib} Python bindings yet, see
 221 link:doc/python-howto.txt[`doc/python-howto.txt`] to understand how to
 222 use them.
 223
 224 == Community
 225
 226 Mailing list::
 227     https://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev[lttng-dev]
 228     (mailto:lttng-dev@lists.lttng.org[lttng-dev@lists.lttng.org])
 229
 230 IRC channel::
 231     irc://irc.oftc.net/lttng[`#lttng`] on the OFTC network
 232
 233 Bug tracker::
 234     https://bugs.lttng.org/projects/lttng-tools[{lt} bug tracker]
 235
 236 GitHub project::
 237     https://github.com/lttng/lttng-tools/[lttng/lttng{nbh}tools]
 238
 239 Continuous integration::
 240     https://ci.lttng.org/job/lttng-tools_master_build/[{lt}'s master build]
 241     on LTTng's CI
 242
 243 Code review::
 244     https://review.lttng.org/q/project:lttng-tools[_lttng{nbh}tools_ project]
 245     on LTTng Review
 246
 247 Contributor's guide::
 248     https://github.com/lttng/lttng-tools/blob/master/CONTRIBUTING.md