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 == Supported versions
 225
 226 The LTTng project supports the last two released stable versions
 227 (e.g. stable-2.13 and stable-2.12).
 228
 229 Fixes are backported from the master branch to the last stable version unless
 230 those fixes would break the ABI or API. Those fixes may be backported to the
 231 second-last stable version, depending on complexity and ABI/API compatibility.
 232
 233 Security fixes are backported from the master branch to both of the last stable
 234 version and the second-last stable version.
 235
 236 New features are integrated into the master branch and not backported to the
 237 last stable branch.
 238
 239 == Community
 240
 241 Mailing list::
 242     https://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev[lttng-dev]
 243     (mailto:lttng-dev@lists.lttng.org[lttng-dev@lists.lttng.org])
 244
 245 IRC channel::
 246     irc://irc.oftc.net/lttng[`#lttng`] on the OFTC network
 247
 248 Bug tracker::
 249     https://bugs.lttng.org/projects/lttng-tools[{lt} bug tracker]
 250
 251 GitHub project::
 252     https://github.com/lttng/lttng-tools/[lttng/lttng{nbh}tools]
 253
 254 Continuous integration::
 255     https://ci.lttng.org/job/lttng-tools_master_build/[{lt}'s master build]
 256     on LTTng's CI
 257
 258 Code review::
 259     https://review.lttng.org/q/project:lttng-tools[_lttng{nbh}tools_ project]
 260     on LTTng Review
 261
 262 Contributor's guide::
 263     https://github.com/lttng/lttng-tools/blob/master/CONTRIBUTING.md