lttng / Lttng Tools

// Render with Asciidoctor

:nbh: ‑ :lt: LTTng{nbh}tools :lib: liblttng{nbh}ctl

ifdef::env-github[] :toc: macro endif::env-github[]

ifndef::env-github[] :toc: left endif::env-github[]

= {lt} 5 May 2020

[.normal] https://ci.lttng.org/job/lttng-tools_master_build/[image:https://img.shields.io/jenkins/s/https/ci.lttng.org/lttng-tools_master_build.svg[Jenkins, title="Jenkins"]] https://scan.coverity.com/projects/lttng-tools[image:https://img.shields.io/coverity/scan/lttng-tools.svg[Coverity, title="Coverity"]]

[.lead] {lt} is a set of components to control https://lttng.org/[LTTng] tracing.

The project includes:

• The LTTng https://lttng.org/man/8/lttng-sessiond/[session daemon].

• The LTTng consumer daemon.

• The LTTng https://lttng.org/man/8/lttng-relayd/[relay daemon].

• {lib}, a library with a C{nbsp}API used to communicate with the session daemon.

• Python{nbsp}3 bindings of liblttng{nbh}ctl.

• https://lttng.org/man/1/lttng/[`lttng`], a command-line tool over {lib}.

• https://lttng.org/man/1/lttng-crash/[`lttng{nbh}crash`], a command-line tool to recover and view LTTng{nbsp}2 trace buffers in the event of a crash.

ifdef::env-github[] toc::[] endif::env-github[]

== Required and optional dependencies

You need the following dependencies to build and run the {lt} components:

• Linux kernel{nbsp}≥{nbsp}2.6.27

Use {nbh}{nbh}disable{nbh}epoll at <<configure,build configuration>> time to build {lt} for an older kernel. However, note that we can't provide any guarantee below 2.6.27.

• http://www.liburcu.org/[Userspace{nbsp}RCU]{nbsp}≥{nbsp}0.9.0.

Debian/Ubuntu package: liburcu{nbh}dev.

• popt{nbsp}≥{nbsp}1.13

Debian/Ubuntu package: libpopt{nbh}dev.

• http://xmlsoft.org/[Libxml2]{nbsp}≥{nbsp}2.7.6

Debian/Ubuntu package: libxml2{nbh}dev

The following dependencies are optional:

• https://babeltrace.org/[Babeltrace{nbsp}2]: default viewer of the https://lttng.org/man/1/lttng-view/[`lttng view`] command.

Debian/Ubuntu package: babeltrace2

• https://lttng.org/[LTTng{nbh}UST] (same minor version as {lt}): LTTng user space tracing (applications and libraries).

Debian/Ubuntu package: liblttng{nbh}ust{nbh}dev

• Perl: make{nbsp}check and tests.

• https://www.python.org/[Python]{nbsp}≥{nbsp}3.0: make{nbsp}check and tests.

Debian/Ubuntu package: python3

• http://www.swig.org/[SWIG]{nbsp}≥{nbsp}2.0 and Python{nbsp}3 development headers: Python bindings (enabled at <<configure,build configuration>> time with the {nbh}{nbh}enable{nbh}python{nbh}bindings option).

Debian/Ubuntu packages: swig2.0 and python3{nbh}dev

• modprobe and/or https://git.kernel.org/pub/scm/utils/kernel/kmod/kmod.git/[kmod]{nbsp}≥{nbsp}22: automatic LTTng kernel modules loading (kernel tracing).

• Bash: make{nbsp}check.

• http://man7.org/linux/man-pages/man1/man.1.html[`man`] (manual pager): view lttng command manual pages with the {nbh}{nbh}help option or with the https://lttng.org/man/1/lttng-help/[`lttng{nbsp}help`] command.

NOTE: You can use the <<configure,build configuration>> option {nbh}{nbh}enable{nbh}embedded{nbh}help to embed the manual pages into the lttng, lttng{nbh}sessiond, lttng{nbh}relayd, and lttng{nbh}crash programs so that you don't need man to view them.

• http://perfmon2.sourceforge.net/[libpfm]{nbsp}≥{nbsp}4.0: perf regression test suite.

Debian/Ubuntu package: libpfm4-dev

{lt} 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{nbh}UST project to make them work with the components of the latest {lt} release.

See the https://lttng.org/docs/[LTTng Documentation] for more information on versioning.

== Build from source

=== Dependencies

You need the following tools to build {lt}:

• https://www.gnu.org/software/automake/manual/html_node/Autotools-Introduction.html[GNU{nbsp}Autotools] (Automake{nbsp}≥{nbsp}1.10, Autoconf{nbsp}≥{nbsp}2.64, and Autoheader{nbsp}≥{nbsp}2.50)

• http://www.gnu.org/software/autoconf/[GNU{nbsp}Libtool]{nbsp}≥{nbsp}2.2

• https://github.com/westes/flex/[Flex]{nbsp}≥{nbsp}2.5.35

• https://www.gnu.org/software/bison/[Bison]{nbsp}≥{nbsp}2.4

To build the {lt} manual pages:

• https://www.methods.co.nz/asciidoc/[AsciiDoc]{nbsp}≥{nbsp}8.4.5

NOTE: Previous versions could work, but were not tested.

• https://pagure.io/xmlto[xmlto]{nbsp}≥{nbsp}0.0.21

NOTE: Previous versions could work, but were not tested.

If you use GNU{nbsp}gold, which is not mandatory:

• GNU{nbsp}gold{nbsp}≥{nbsp}2.22

NOTE: With GNU{nbsp}gold, you might need to add -L/usr/local/lib to the LDFLAGS environment variable.

=== Build steps

. If you have the {lt} Git source, run: +

$ ./bootstrap

This script creates the configure script.

. [[configure]]Configure the build: +

$ ./configure

If you want the {lib} Python bindings, use the {nbh}{nbh}enable{nbh}python{nbh}bindings option. See also the PYTHON and PYTHON_CONFIG environment variables in ./configure{nbsp}{nbh}{nbh}help.

If you don't want to build the manual pages, use the {nbh}{nbh}disable{nbh}man{nbh}pages option.

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

If your Linux kernel is older than 2.6.27, use the {nbh}{nbh}disable{nbh}epoll option.

This build configuration script finds LTTng{nbh}UST with https://www.freedesktop.org/wiki/Software/pkg-config/[pkg{nbh}config]: set the PKG_CONFIG_PATH environment variable accordingly if pkg{nbh}config cannot find the lttng{nbh}ust package information.

See ./configure{nbsp}{nbh}{nbh}help for the complete list of options.

. Build the project: +

$ make

. Install the project: +

$ sudo make install $ sudo ldconfig

== Usage

See the https://lttng.org/docs/#doc-controlling-tracing[Tracing control] section of the LTTng Documentation to learn how to use the {lt} components.

See also the https://lttng.org/man/[LTTng manual pages] (all section{nbsp}1 and{nbsp}8 pages).

As there's no official {lib} Python bindings yet, see link:doc/python-howto.txt[doc/python-howto.txt] to understand how to use them.

== Community

Mailing list:: https://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev[lttng-dev] (mailto:[email protected][[email protected]])

IRC channel:: irc://irc.oftc.net/lttng[#lttng] on the OFTC network

Bug tracker:: https://bugs.lttng.org/projects/lttng-tools[{lt} bug tracker]

GitHub project:: https://github.com/lttng/lttng-tools/[lttng/lttng{nbh}tools]

Continuous integration:: https://ci.lttng.org/job/lttng-tools_master_build/[{lt}'s master build] on LTTng's CI

Code review:: https://review.lttng.org/q/project:lttng-tools[_lttng{nbh}tools_ project] on LTTng Review