lttng-tools  2.12.3
About: LTTng-tools (Linux Trace Toolkit Next Generation) is a system software package for correlated tracing of the Linux kernel, applications and libraries: This package contains tracing control daemons, libraries and interfaces.
  Fossies Dox: lttng-tools-2.12.3.tar.bz2  ("unofficial" and yet experimental doxygen-generated source code documentation)  
lttng-tools Documentation

Some Fossies usage hints in advance:

  1. To see the Doxygen generated documentation please click on one of the items in the steelblue colored "quick index" bar above or use the side panel at the left which displays a hierarchical tree-like index structure and is adjustable in width.
  2. If you want to search for something by keyword rather than browse for it you can use the client side search facility (using Javascript and DHTML) that provides live searching, i.e. the search results are presented and adapted as you type in the Search input field at the top right.
  3. Doxygen doesn't incorporate all member files but just a definable subset (basically the main project source code files that are written in a supported language). So to search and browse all member files you may visit the Fossies lttng-tools-2.12.3.tar.bz2 contents page and use the Fossies standard member browsing features (also with source code highlighting and additionally with optional code folding).
README.md

LTTng-tools

Jenkins Coverity

LTTng-tools is a set of tools to control LTTng tracing. The project includes the LTTng session daemon, consumer daemon and relay daemon, as well as liblttng-ctl, a C library used to communicate with the session daemon, and lttng, a command line interface to liblttng-ctl.

Requirements and optional dependencies

The following items are required to build and run LTTng-tools components:

  • Linux kernel >= 2.6.27: for epoll() support, at least this version is needed. However, poll() is also supported by configuring LTTng-tools with the --disable-epoll option. Using that, the kernel version may probably be older, but we can't provide any guarantee. Please let us know if you are able to go lower without any problems.
  • liburcu >= 0.9.0: userspace RCU library, by Mathieu Desnoyers and Paul E. McKenney.
  • libpopt >= 1.13: command line arguments parsing library.
    • Debian/Ubuntu package: libpopt-dev
  • libxml2 >= 2.7.6: XML document parsing library. Needed for tracing session configuration saving/loading and machine interface output support.
    • Debian/Ubuntu package: libxml2-dev

The following items are optional dependencies:

  • Babeltrace: trace viewer. Enables the use of lttng view command.
    • Debian/Ubuntu package: babeltrace
  • LTTng UST (same minor version as LTTng Tools): userspace tracer. Enables the tracing of userspace applications.
    • Debian/Ubuntu package: liblttng-ust-dev
  • Perl: needed for make check and tests.
  • Python >= 3.0: needed for make check and tests.
    • Debian/Ubuntu package: python3
  • SWIG >= 2.0 and Python 3 development headers: needed for Python bindings (enabled at configure time with the --enable-python-bindings option).
    • Debian/Ubuntu packages: swig2.0 and python3-dev
  • modprobe: needed for automatic LTTng kernel modules loading (kernel tracing).
  • bash: needed to run make check.
  • man (manual pager): needed to view LTTng-tools commands' man pages with the --help option or with the lttng help command. Note that without man, you cannot get offline help with LTTng-tools commands, not even their usage.
  • libpfm >= 4.0: needed to run the perf regression test suite.
    • Debian/Ubuntu package: libpfm4-dev

LTTng-tools supports both the LTTng Linux Kernel tracer and LTTng user space tracer released as part of the same minor release series. While some releases do not change the tracer ABIs and should work with, no testing is performed to ensure cross-version compatibility is maintained.

Note that applications instrumented with older versions of the LTTng UST project do not have to be rebuilt or modified to work with the latest LTTng-tools. For more information on versioning, please refer to the LTTng documentation.

Building

This source tree is based on the Autotools suite from GNU to simplify portability. Here are some things you should have on your system in order to compile the Git repository tree:

  • GNU Autotools (Automake >= 1.10, Autoconf >= 2.64, Autoheader >= 2.50; make sure your system-wide automake points to a recent version)
  • GNU Libtool >= 2.2
  • Flex >= 2.5.35
  • Bison >= 2.4

Optional packages to build LTTng-tools man pages:

  • AsciiDoc >= 8.4.5 (previous versions may work, but were not tested)
  • xmlto >= 0.0.21 (previous versions may work, but were not tested)

If you use GNU gold, which is not mandatory, make sure you have this version:

  • GNU gold >= 2.22

Before this version of GNU gold, we hit a known bug. Be advised that with GNU gold, you might have to specify -L/usr/local/lib in LDFLAGS.

If you get the tree from the Git repository, you will need to run

./bootstrap

in its root. It calls all the GNU tools needed to prepare the tree configuration.

To build LTTng-tools, do:

./configure
make
sudo make install
sudo ldconfig

If you want Python bindings, add the --enable-python-bindings option to configure. Please note that some distributions will need the following environment variables set before running configure:

export PYTHON="python3"
export PYTHON_CONFIG="/usr/bin/python3-config"

Using

Please see doc/quickstart.txt to get started with LTTng tracing. You can also use the -h or --help option of any lttng command, e.g.:

lttng enable-event --help

A network streaming HOWTO can be found in doc/streaming-howto.txt which quickly helps you understand how to stream a LTTng 2.x trace.

A Python binding HOWTO can be found in doc/python-howto.txt which quickly helps you understand how to use the Python module to control LTTng.

Contact

Maintainer: Jérémie Galarneau

Mailing list: lttng-dev@lists.lttng.org

Package contents

This package contains the following elements:

  • doc: LTTng-tools documentation.
  • include: the public header files that will be installed on the system.
  • src/bin: source code of LTTng-tools programs.
    • lttng-consumerd: consumer daemon.
    • lttng-crash: crash trace viewer.
    • lttng-relayd: relay daemon.
    • lttng-sessiond: session daemon.
    • lttng: command line interface for LTTng tracing control.
  • src/common: common LTTng-tools source code.
    • compat: compatibility library mostly for FreeBSD and Linux.
    • config: tracing session configuration saving/loading.
    • hashtable: library wrapper over Userspace RCU hashtables.
    • health: health check subsytem.
    • index: CTF index utilities.
    • kernel-consumer: Linux kernel consumer.
    • kernel-ctl: Linux kernel tracer control.
    • relayd: relay daemon control.
    • sessiond-comm: session daemon communication.
    • ust-consumer: user space consumer.
  • src/lib: source code of LTTng-tools libraries.
    • lttng-ctl: LTTng control library.
  • tests: various test programs.