ovpanait / lttng-tools

The lttng-tools project provides a session daemon (lttng-sessiond) that acts as a tracing registry, the "lttng" command line for tracing control, a lttng-ctl library for tracing control and a lttng-relayd for network streaming.

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.

Required and optional dependencies

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

• Linux kernel ≥ 2.6.27

  Use --disable-epoll at build configuration time to build LTTng‑tools for an older kernel. However, note that we can't provide any guarantee below 2.6.27.

• Userspace RCU ≥ 0.9.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.

  Debian/Ubuntu package: babeltrace2

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

  Debian/Ubuntu package: liblttng-ust-dev

• Perl: make check and tests.

• Python ≥ 3.0: 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 that 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.10, 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

  Previous versions could work, but were not tested.

• xmlto ≥ 0.0.21

  Previous versions could work, but were not tested.

If you use GNU gold, which is not mandatory:

• GNU gold ≥ 2.22

Note that with GNU gold, you might have 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.

   If your Linux kernel is older than 2.6.27, use the --enable-epoll 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.

Community

• Mailing list: lttng‑dev.

• IRC channel: #lttng on the OFTC network.

• Bug tracker:: LTTng‑tools bug tracker.

• GitHub project: lttng/lttng‑tools.

• Continuous integration: LTTng CI.

• Code review: lttng‑tools project on LTTng Review.