Fix: skip start trace for app that are already started.
[lttng-tools.git] / README.md
1 LTTng-tools
2 ===========
3
4 [![Jenkins](https://img.shields.io/jenkins/s/https/ci.lttng.org/lttng-tools_master_build.svg)](https://ci.lttng.org/job/lttng-tools_master_build/)
5 [![Coverity](https://img.shields.io/coverity/scan/lttng-tools.svg)](https://scan.coverity.com/projects/lttng-tools)
6
7 LTTng-tools is a set of tools to control [LTTng](https://lttng.org/)
8 tracing. The project includes the LTTng session daemon, consumer daemon
9 and relay daemon, as well as `liblttng-ctl`, a C library used to
10 communicate with the session daemon, and `lttng`, a command line
11 interface to `liblttng-ctl`.
12
13
14 Requirements and optional dependencies
15 --------------------------------------
16
17 The following items are _required_ to build and run LTTng-tools
18 components:
19
20 - **Linux kernel >= 2.6.27**: for `epoll()` support, at least this
21 version is needed. However, `poll()` is also supported by
22 configuring LTTng-tools with the `--disable-epoll` option. Using
23 that, the kernel version may probably be older, but we can't provide
24 any guarantee. Please let us know if you are able to go lower
25 without any problems.
26 - **[`liburcu`](http://www.liburcu.org/) >= 0.9.0**: userspace RCU library,
27 by Mathieu Desnoyers and Paul E. McKenney.
28 - **`libpopt` >= 1.13**: command line arguments parsing library.
29 - Debian/Ubuntu package: `libpopt-dev`
30 - **`libxml2` >= 2.7.6**: XML document parsing library. Needed for
31 tracing session configuration saving/loading and machine interface
32 output support.
33 - Debian/Ubuntu package: `libxml2-dev`
34
35
36 The following items are _optional_ dependencies:
37
38 - **[Babeltrace](https://lttng.org/babeltrace)**: trace viewer.
39 Enables the use of `lttng view` command.
40 - Debian/Ubuntu package: `babeltrace`
41 - **[LTTng UST](https://lttng.org) (same minor version as LTTng Tools)**:
42 userspace tracer. Enables the tracing of userspace applications.
43 - Debian/Ubuntu package: `liblttng-ust-dev`
44 - **Perl**: needed for `make check` and tests.
45 - **Python >= 3.0**: needed for `make check` and tests.
46 - Debian/Ubuntu package: `python3`
47 - **SWIG >= 2.0** and **Python 3 development headers**: needed for
48 Python bindings
49 (enabled at configure time with the `--enable-python-bindings` option).
50 - Debian/Ubuntu packages: `swig2.0` and `python3-dev`
51 - **modprobe**: needed for automatic LTTng kernel modules loading
52 (kernel tracing).
53 - **bash**: needed to run `make check`.
54 - **man** (manual pager): needed to view LTTng-tools commands' man
55 pages with the `--help` option or with the `lttng help` command.
56 Note that without `man`, you cannot get offline help with
57 LTTng-tools commands, not even their usage.
58 - **libpfm >= 4.0**: needed to run the perf regression test suite.
59 - Debian/Ubuntu package: `libpfm4-dev`
60
61 LTTng-tools supports both the [LTTng Linux Kernel tracer](https://lttng.org)
62 and [LTTng user space tracer](https://lttng.org) released as part of the same
63 **minor** release series. While some releases do not change the tracer ABIs and
64 should work with, no testing is performed to ensure cross-version compatibility
65 is maintained.
66
67 Note that applications instrumented with older versions of the LTTng UST project
68 do not have to be rebuilt or modified to work with the latest LTTng-tools.
69 For more information on versioning, please refer to the
70 [LTTng documentation](https://lttng.org/docs).
71
72 Building
73 --------
74
75 This source tree is based on the Autotools suite from GNU to simplify
76 portability. Here are some things you should have on your system in
77 order to compile the Git repository tree:
78
79 - **GNU Autotools** (**Automake >= 1.10**, **Autoconf >= 2.64**,
80 **Autoheader >= 2.50**; make sure your system-wide `automake` points
81 to a recent version)
82 - **[GNU Libtool](http://www.gnu.org/software/autoconf/) >= 2.2**
83 - **Flex >= 2.5.35**
84 - **Bison >= 2.4**
85
86 Optional packages to build LTTng-tools man pages:
87
88 - **AsciiDoc >= 8.4.5** (previous versions may work, but were
89 not tested)
90 - **xmlto >= 0.0.21** (previous versions may work, but were
91 not tested)
92
93 If you use GNU gold, which is _not_ mandatory, make sure you have this
94 version:
95
96 - **GNU gold >= 2.22**
97
98 Before this version of GNU gold, we hit a
99 [known bug](http://sourceware.org/bugzilla/show_bug.cgi?id=11317).
100 Be advised that with GNU gold, you might have to specify
101 `-L/usr/local/lib` in `LDFLAGS`.
102
103 If you get the tree from the Git repository, you will need to run
104
105 ./bootstrap
106
107 in its root. It calls all the GNU tools needed to prepare the tree
108 configuration.
109
110 To build LTTng-tools, do:
111
112 ./configure
113 make
114 sudo make install
115 sudo ldconfig
116
117 If you want Python bindings, add the `--enable-python-bindings` option
118 to `configure`. Please note that some distributions will need the
119 following environment variables set before running configure:
120
121 export PYTHON="python3"
122 export PYTHON_CONFIG="/usr/bin/python3-config"
123
124
125 Using
126 -----
127
128 Please see [`doc/quickstart.txt`](doc/quickstart.txt) to get started
129 with LTTng tracing. You can also use the `-h` or `--help` option of
130 any `lttng` command, e.g.:
131
132 lttng enable-event --help
133
134 A network streaming HOWTO can be found in
135 [`doc/streaming-howto.txt`](doc/streaming-howto.txt) which quickly
136 helps you understand how to stream a LTTng 2.x trace.
137
138 A Python binding HOWTO can be found in
139 [`doc/python-howto.txt`](doc/python-howto.txt) which quickly helps you
140 understand how to use the Python module to control LTTng.
141
142
143 Contact
144 -------
145
146 Maintainer: [Jérémie Galarneau](mailto:jeremie.galarneau@efficios.com)
147
148 Mailing list: [`lttng-dev@lists.lttng.org`](https://lttng.org/cgi-bin/mailman/listinfo/lttng-dev)
149
150
151 Package contents
152 ----------------
153
154 This package contains the following elements:
155
156 - `doc`: LTTng-tools documentation.
157 - `include`: the public header files that will be installed on the system.
158 - `src/bin`: source code of LTTng-tools programs.
159 - `lttng-consumerd`: consumer daemon.
160 - `lttng-crash`: crash trace viewer.
161 - `lttng-relayd`: relay daemon.
162 - `lttng-sessiond`: session daemon.
163 - `lttng`: command line interface for LTTng tracing control.
164 - `src/common`: common LTTng-tools source code.
165 - `compat`: compatibility library mostly for FreeBSD and Linux.
166 - `config`: tracing session configuration saving/loading.
167 - `hashtable`: library wrapper over Userspace RCU hashtables.
168 - `health`: health check subsytem.
169 - `index`: CTF index utilities.
170 - `kernel-consumer`: Linux kernel consumer.
171 - `kernel-ctl`: Linux kernel tracer control.
172 - `relayd`: relay daemon control.
173 - `sessiond-comm`: session daemon communication.
174 - `ust-consumer`: user space consumer.
175 - `src/lib`: source code of LTTng-tools libraries.
176 - `lttng-ctl`: LTTng control library.
177 - `tests`: various test programs.
This page took 0.051518 seconds and 5 git commands to generate.