LTTng‑tools

LTTng‑tools is a set of components to control LTTng tracing.

The project includes:

• The LTTng session daemon.

• The LTTng consumer daemon.

• The LTTng relay daemon.

• liblttng‑ctl, a library with a C API used to communicate with the session daemon.

• Python 3 bindings of liblttng‑ctl.

• lttng, a command-line tool over liblttng‑ctl.

• lttng‑crash, a command-line tool to recover and view LTTng 2 trace buffers in the event of a crash.

Table of Contents

• Required and optional dependencies
• Build from source
  • Dependencies
  • Build steps
• Usage
• Supported versions
• Community

Required and optional dependencies

You need the following dependencies to build and run the LTTng‑tools components:

• Linux kernel ≥ 2.6.30

• Userspace RCU ≥ 0.14.0.

  Debian/Ubuntu package: liburcu‑dev.

• popt ≥ 1.13

  Debian/Ubuntu package: libpopt‑dev.

• Libxml2 ≥ 2.7.6

  Debian/Ubuntu package: libxml2‑dev

The following dependencies are optional:

• Babeltrace 2: default viewer of the lttng view command, make check and tests.

  Debian/Ubuntu package: babeltrace2 libbabeltrace2-dev

• LTTng‑UST (same minor version as LTTng‑tools): LTTng user space tracing (applications and libraries).

  Debian/Ubuntu package: liblttng‑ust‑dev

• Python ≥ 3.4: make check and tests.

  Debian/Ubuntu package: python3

• SWIG ≥ 2.0 and Python 3 development headers: Python bindings (enabled at build configuration time with the ‑‑enable‑python‑bindings option).

  Debian/Ubuntu packages: swig2.0 and python3‑dev

• modprobe and/or kmod ≥ 22: automatic LTTng kernel modules loading (kernel tracing).

• Bash: make check.

• man (manual pager): view lttng command manual pages with the ‑‑help option or with the lttng help command.

  Note	You can use the build configuration option ‑‑enable‑embedded‑help to embed the manual pages into the lttng, lttng‑sessiond, lttng‑relayd, and lttng‑crash programs so that you don’t need man to view them.

• libpfm ≥ 4.0: perf regression test suite.

  Debian/Ubuntu package: libpfm4-dev

LTTng‑tools supports both the LTTng Linux kernel tracer and LTTng user space tracer sharing the same minor version. While some minor releases do not change the tracer ABIs and could work, no testing is performed to ensure that cross-version compatibility is maintained.

You don’t need to rebuild or modify applications instrumented with older versions of the LTTng‑UST project to make them work with the components of the latest LTTng‑tools release.

See the LTTng Documentation for more information on versioning.

Build from source

Dependencies

You need the following tools to build LTTng‑tools:

• GNU Autotools (Automake ≥ 1.12, Autoconf ≥ 2.64, and Autoheader ≥ 2.50)

• GNU Libtool ≥ 2.2

• Flex ≥ 2.5.35

• Bison ≥ 2.4

To build the LTTng‑tools manual pages:

• AsciiDoc ≥ 8.4.5

  Note	Previous versions could work, but were not tested.

• xmlto ≥ 0.0.21

  Note	Previous versions could work, but were not tested.

If you use GNU gold, which is not mandatory:

• GNU gold ≥ 2.22

Note	With GNU gold, you might need to add -L/usr/local/lib to the LDFLAGS environment variable.

Build steps

1. If you have the LTTng‑tools Git source, run:

   $ ./bootstrap

   This script creates the configure script.

2. Configure the build:

   $ ./configure

   If you want the liblttng‑ctl Python bindings, use the ‑‑enable‑python‑bindings option. See also the PYTHON and PYTHON_CONFIG environment variables in ./configure ‑‑help.

   If you don’t want to build the manual pages, use the ‑‑disable‑man‑pages option.

   If you want to embed the manual pages into the lttng, lttng‑sessiond, lttng‑relayd, and lttng‑crash programs so that you don’t need man to view them, use the ‑‑enable‑embedded‑help option.

   This build configuration script finds LTTng‑UST with pkg‑config: set the PKG_CONFIG_PATH environment variable accordingly if pkg‑config cannot find the lttng‑ust package information.

   See ./configure ‑‑help for the complete list of options.

3. Build the project:

   $ make

4. Install the project:

   $ sudo make install
   $ sudo ldconfig

Usage

See the Tracing control section of the LTTng Documentation to learn how to use the LTTng‑tools components.

See also the LTTng manual pages (all section 1 and 8 pages).

As there’s no official liblttng‑ctl Python bindings yet, see doc/python-howto.txt to understand how to use them.

Supported versions

The LTTng project supports the last two released stable versions (e.g. stable-2.13 and stable-2.12).

Fixes are backported from the master branch to the last stable version unless those fixes would break the ABI or API. Those fixes may be backported to the second-last stable version, depending on complexity and ABI/API compatibility.

Security fixes are backported from the master branch to both of the last stable version and the second-last stable version.

New features are integrated into the master branch and not backported to the last stable branch.

Community

Mailing list

lttng-dev (lttng-dev@lists.lttng.org)

IRC channel

#lttng on the OFTC network

Bug tracker

LTTng‑tools bug tracker

GitHub project

lttng/lttng‑tools

Continuous integration

LTTng‑tools’s master build on LTTng’s CI

Code review

lttng‑tools project on LTTng Review

Contributor’s guide

https://github.com/lttng/lttng-tools/blob/master/CONTRIBUTING.md