| 1 | // Render with Asciidoctor |
| 2 | |
| 3 | :nbh: ‑ |
| 4 | :lt: LTTng{nbh}tools |
| 5 | :lib: liblttng{nbh}ctl |
| 6 | |
| 7 | ifdef::env-github[] |
| 8 | :toc: macro |
| 9 | endif::env-github[] |
| 10 | |
| 11 | ifndef::env-github[] |
| 12 | :toc: left |
| 13 | endif::env-github[] |
| 14 | |
| 15 | = {lt} |
| 16 | 5 May 2020 |
| 17 | |
| 18 | [.normal] |
| 19 | 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"]] |
| 20 | https://scan.coverity.com/projects/lttng-tools[image:https://img.shields.io/coverity/scan/lttng-tools.svg[Coverity, title="Coverity"]] |
| 21 | |
| 22 | [.lead] |
| 23 | _**{lt}**_ is a set of components to control https://lttng.org/[LTTng] |
| 24 | tracing. |
| 25 | |
| 26 | The project includes: |
| 27 | |
| 28 | * The LTTng https://lttng.org/man/8/lttng-sessiond/[session daemon]. |
| 29 | |
| 30 | * The LTTng consumer daemon. |
| 31 | |
| 32 | * The LTTng https://lttng.org/man/8/lttng-relayd/[relay daemon]. |
| 33 | |
| 34 | * {lib}, a library with a C{nbsp}API used to communicate with |
| 35 | the session daemon. |
| 36 | |
| 37 | * Python{nbsp}3 bindings of liblttng{nbh}ctl. |
| 38 | |
| 39 | * https://lttng.org/man/1/lttng/[`lttng`], a command-line tool over |
| 40 | {lib}. |
| 41 | |
| 42 | * https://lttng.org/man/1/lttng-crash/[`lttng{nbh}crash`], a command-line |
| 43 | tool to recover and view LTTng{nbsp}2 trace buffers in the event of a |
| 44 | crash. |
| 45 | |
| 46 | ifdef::env-github[] |
| 47 | toc::[] |
| 48 | endif::env-github[] |
| 49 | |
| 50 | == Required and optional dependencies |
| 51 | |
| 52 | You need the following dependencies to build and run the {lt} |
| 53 | components: |
| 54 | |
| 55 | * **Linux kernel{nbsp}≥{nbsp}2.6.27** |
| 56 | + |
| 57 | Use `{nbh}{nbh}disable{nbh}epoll` at <<configure,build configuration>> |
| 58 | time to build {lt} for an older kernel. However, note that we can't |
| 59 | provide any guarantee below 2.6.27. |
| 60 | |
| 61 | * **http://www.liburcu.org/[Userspace{nbsp}RCU]{nbsp}≥{nbsp}0.11.0**. |
| 62 | + |
| 63 | Debian/Ubuntu package: `liburcu{nbh}dev`. |
| 64 | |
| 65 | * **popt{nbsp}≥{nbsp}1.13** |
| 66 | + |
| 67 | Debian/Ubuntu package: `libpopt{nbh}dev`. |
| 68 | |
| 69 | * **http://xmlsoft.org/[Libxml2]{nbsp}≥{nbsp}2.7.6** |
| 70 | + |
| 71 | Debian/Ubuntu package: `libxml2{nbh}dev` |
| 72 | |
| 73 | The following dependencies are optional: |
| 74 | |
| 75 | * **https://babeltrace.org/[Babeltrace{nbsp}2]**: default viewer |
| 76 | of the https://lttng.org/man/1/lttng-view/[`lttng view`] command. |
| 77 | + |
| 78 | Debian/Ubuntu package: `babeltrace2` |
| 79 | |
| 80 | * **https://lttng.org/[LTTng{nbh}UST]** (same minor version as {lt}): |
| 81 | LTTng user space tracing (applications and libraries). |
| 82 | + |
| 83 | Debian/Ubuntu package: `liblttng{nbh}ust{nbh}dev` |
| 84 | |
| 85 | * **Perl**: `make{nbsp}check` and tests. |
| 86 | |
| 87 | * **https://www.python.org/[Python]{nbsp}≥{nbsp}3.0**: |
| 88 | `make{nbsp}check` and tests. |
| 89 | + |
| 90 | Debian/Ubuntu package: `python3` |
| 91 | |
| 92 | * **http://www.swig.org/[SWIG]{nbsp}≥{nbsp}2.0** and |
| 93 | **Python{nbsp}3 development headers**: Python bindings |
| 94 | (enabled at <<configure,build configuration>> time with the |
| 95 | `{nbh}{nbh}enable{nbh}python{nbh}bindings` option). |
| 96 | + |
| 97 | Debian/Ubuntu packages: `swig2.0` and `python3{nbh}dev` |
| 98 | |
| 99 | * **modprobe** and/or |
| 100 | **https://git.kernel.org/pub/scm/utils/kernel/kmod/kmod.git/[kmod]{nbsp}≥{nbsp}22**: |
| 101 | automatic LTTng kernel modules loading (kernel tracing). |
| 102 | |
| 103 | * **Bash**: `make{nbsp}check`. |
| 104 | |
| 105 | * **http://man7.org/linux/man-pages/man1/man.1.html[`man`]** |
| 106 | (manual pager): view `lttng` command manual |
| 107 | pages with the `{nbh}{nbh}help` option or with the |
| 108 | https://lttng.org/man/1/lttng-help/[`lttng{nbsp}help`] command. |
| 109 | + |
| 110 | NOTE: You can use the <<configure,build configuration>> option |
| 111 | `{nbh}{nbh}enable{nbh}embedded{nbh}help` to embed the manual pages into |
| 112 | the `lttng`, `lttng{nbh}sessiond`, `lttng{nbh}relayd`, and |
| 113 | `lttng{nbh}crash` programs so that you don't need `man` to view them. |
| 114 | |
| 115 | * **http://perfmon2.sourceforge.net/[libpfm]{nbsp}≥{nbsp}4.0**: |
| 116 | perf regression test suite. |
| 117 | + |
| 118 | Debian/Ubuntu package: `libpfm4-dev` |
| 119 | |
| 120 | {lt} supports both the LTTng Linux kernel tracer and LTTng user space |
| 121 | tracer sharing the same _minor_ version. While some minor releases do |
| 122 | not change the tracer ABIs and _could_ work, no testing is performed to |
| 123 | ensure that cross-version compatibility is maintained. |
| 124 | |
| 125 | You don't need to rebuild or modify applications instrumented with older |
| 126 | versions of the LTTng{nbh}UST project to make them work with the |
| 127 | components of the latest {lt} release. |
| 128 | |
| 129 | See the https://lttng.org/docs/[LTTng Documentation] for more |
| 130 | information on versioning. |
| 131 | |
| 132 | == Build from source |
| 133 | |
| 134 | === Dependencies |
| 135 | |
| 136 | You need the following tools to build {lt}: |
| 137 | |
| 138 | * **https://www.gnu.org/software/automake/manual/html_node/Autotools-Introduction.html[GNU{nbsp}Autotools]** |
| 139 | (**Automake{nbsp}≥{nbsp}1.10**, |
| 140 | **Autoconf{nbsp}≥{nbsp}2.64**, and **Autoheader{nbsp}≥{nbsp}2.50**) |
| 141 | |
| 142 | * **http://www.gnu.org/software/autoconf/[GNU{nbsp}Libtool]{nbsp}≥{nbsp}2.2** |
| 143 | |
| 144 | * **https://github.com/westes/flex/[Flex]{nbsp}≥{nbsp}2.5.35** |
| 145 | |
| 146 | * **https://www.gnu.org/software/bison/[Bison]{nbsp}≥{nbsp}2.4** |
| 147 | |
| 148 | To build the {lt} manual pages: |
| 149 | |
| 150 | * **https://www.methods.co.nz/asciidoc/[AsciiDoc]{nbsp}≥{nbsp}8.4.5** |
| 151 | + |
| 152 | NOTE: Previous versions could work, but were not tested. |
| 153 | |
| 154 | * **https://pagure.io/xmlto[xmlto]{nbsp}≥{nbsp}0.0.21** |
| 155 | + |
| 156 | NOTE: Previous versions could work, but were not tested. |
| 157 | |
| 158 | If you use GNU{nbsp}gold, which is _not_ mandatory: |
| 159 | |
| 160 | * **GNU{nbsp}gold{nbsp}≥{nbsp}2.22** |
| 161 | |
| 162 | NOTE: With GNU{nbsp}gold, you might need to add |
| 163 | `-L/usr/local/lib` to the `LDFLAGS` environment variable. |
| 164 | |
| 165 | === Build steps |
| 166 | |
| 167 | . **If you have the {lt} Git source**, run: |
| 168 | + |
| 169 | ---- |
| 170 | $ ./bootstrap |
| 171 | ---- |
| 172 | + |
| 173 | This script creates the `configure` script. |
| 174 | |
| 175 | . [[configure]]Configure the build: |
| 176 | + |
| 177 | -- |
| 178 | ---- |
| 179 | $ ./configure |
| 180 | ---- |
| 181 | |
| 182 | If you want the {lib} Python bindings, use the |
| 183 | `{nbh}{nbh}enable{nbh}python{nbh}bindings` option. See also the `PYTHON` |
| 184 | and `PYTHON_CONFIG` environment variables in |
| 185 | `./configure{nbsp}{nbh}{nbh}help`. |
| 186 | |
| 187 | If you don't want to build the manual pages, use the |
| 188 | `{nbh}{nbh}disable{nbh}man{nbh}pages` option. |
| 189 | |
| 190 | If you want to embed the manual pages into the `lttng`, |
| 191 | `lttng{nbh}sessiond`, `lttng{nbh}relayd`, and `lttng{nbh}crash` programs |
| 192 | so that you don't need `man` to view them, use the |
| 193 | `{nbh}{nbh}enable{nbh}embedded{nbh}help` option. |
| 194 | |
| 195 | If your Linux kernel is older than 2.6.27, use the |
| 196 | `{nbh}{nbh}disable{nbh}epoll` option. |
| 197 | |
| 198 | This build configuration script finds LTTng{nbh}UST with |
| 199 | https://www.freedesktop.org/wiki/Software/pkg-config/[pkg{nbh}config]: |
| 200 | set the `PKG_CONFIG_PATH` environment variable accordingly if |
| 201 | pkg{nbh}config cannot find the `lttng{nbh}ust` package information. |
| 202 | |
| 203 | See `./configure{nbsp}{nbh}{nbh}help` for the complete list of options. |
| 204 | -- |
| 205 | |
| 206 | . Build the project: |
| 207 | + |
| 208 | ---- |
| 209 | $ make |
| 210 | ---- |
| 211 | |
| 212 | . Install the project: |
| 213 | + |
| 214 | ---- |
| 215 | $ sudo make install |
| 216 | $ sudo ldconfig |
| 217 | ---- |
| 218 | |
| 219 | == Usage |
| 220 | |
| 221 | See the https://lttng.org/docs/#doc-controlling-tracing[Tracing control] |
| 222 | section of the LTTng Documentation to learn how to use the {lt} |
| 223 | components. |
| 224 | |
| 225 | See also the https://lttng.org/man/[LTTng manual pages] (all |
| 226 | section{nbsp}1 and{nbsp}8 pages). |
| 227 | |
| 228 | As there's no official {lib} Python bindings yet, see |
| 229 | link:doc/python-howto.txt[`doc/python-howto.txt`] to understand how to |
| 230 | use them. |
| 231 | |
| 232 | == Community |
| 233 | |
| 234 | Mailing list:: |
| 235 | https://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev[lttng-dev] |
| 236 | (mailto:lttng-dev@lists.lttng.org[lttng-dev@lists.lttng.org]) |
| 237 | |
| 238 | IRC channel:: |
| 239 | irc://irc.oftc.net/lttng[`#lttng`] on the OFTC network |
| 240 | |
| 241 | Bug tracker:: |
| 242 | https://bugs.lttng.org/projects/lttng-tools[{lt} bug tracker] |
| 243 | |
| 244 | GitHub project:: |
| 245 | https://github.com/lttng/lttng-tools/[lttng/lttng{nbh}tools] |
| 246 | |
| 247 | Continuous integration:: |
| 248 | https://ci.lttng.org/job/lttng-tools_master_build/[{lt}'s master build] |
| 249 | on LTTng's CI |
| 250 | |
| 251 | Code review:: |
| 252 | https://review.lttng.org/q/project:lttng-tools[_lttng{nbh}tools_ project] |
| 253 | on LTTng Review |