From b77bfe92685a15eb6cebd0c1139bf9833afa3973 Mon Sep 17 00:00:00 2001 From: Philippe Proulx Date: Thu, 30 Apr 2020 12:33:51 -0400 Subject: [PATCH] Improve README.md MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit Changes: * Harmonize voice and style. * Add non-breaking spaces and hyphens where missing. * Add many internal and external links. * Add `lttng-crash` and the Python bindings to the list of components. * Use `≥` instead of `>=` (welcome to 2020). * Do not specify why you need to configure with `--disable-epoll` to use a Linux kernel < 2.6.27: I don't think the end user needs to know about poll() vs. epoll(). * Do not mention Mathieu Desnoyers and Paul E. McKenney (this is a README, not the `THANKS` file). * Mention Babeltrace 2 instead of Babeltrace. * Use `https://babeltrace.org/` instead of `https://lttng.org/babeltrace`. * Add kmod to the list of optional dependencies. * Specify that you can use `--enable-embedded-help` at build configuration time if you don't plan to have a manual pager installed on your system. * Don't mention the known GNU gold bug (`http://sourceware.org/bugzilla/show_bug.cgi?id=11317`). Again, the end user only cares about which minimal version of the tool to use, not why. * Use clear, ordered build steps. For the configuration step, specify which options are available and what they change. * Remove the link to `doc/quickstart.txt`. Link to the LTTng Documentation and online manual pages instead, which are more complete. * Remove the link to `doc/streaming-howto.txt`: the LTTng Documentation and online manual pages cover this topic. * Change the "Contact" section for the "Community" section and put all the community/communication links in there. * Remove the "Package contents" section: end users do not care about this and we're not keeping it updated as we amend the project's source anyway. Signed-off-by: Philippe Proulx Change-Id: I4e4c0b183d9a18243db23cde3edb608e32c5e30e (cherry picked from commit f8bd3a12204c10743dfbc456d363e30894eddfc5) Signed-off-by: Jérémie Galarneau --- README.md | 362 ++++++++++++++++++++++++++++++------------------------ 1 file changed, 201 insertions(+), 161 deletions(-) diff --git a/README.md b/README.md index 92df20daf..626225804 100644 --- a/README.md +++ b/README.md @@ -1,177 +1,217 @@ -LTTng-tools -=========== +LTTng‑tools +================= [![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/) [![Coverity](https://img.shields.io/coverity/scan/lttng-tools.svg)](https://scan.coverity.com/projects/lttng-tools) -LTTng-tools is a set of tools to control [LTTng](https://lttng.org/) -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`](http://www.liburcu.org/) >= 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](https://lttng.org/babeltrace)**: trace viewer. - Enables the use of `lttng view` command. - - Debian/Ubuntu package: `babeltrace` - - **[LTTng UST](https://lttng.org) (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](https://lttng.org) -and [LTTng user space tracer](https://lttng.org) 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](https://lttng.org/docs). - -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](http://www.gnu.org/software/autoconf/) >= 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](http://sourceware.org/bugzilla/show_bug.cgi?id=11317). -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 ------ +_**LTTng‑tools**_ is a set of components to control +[LTTng](https://lttng.org/) tracing. + +The project includes: + +* The LTTng [session daemon](https://lttng.org/man/8/lttng-sessiond/). +* The LTTng consumer daemon. +* The LTTng [relay daemon](https://lttng.org/man/8/lttng-relayd/). +* liblttng‑ctl, a library with a C API used to communicate + with the session daemon. +* Python 3 bindings of liblttng‑ctl. +* [`lttng`](https://lttng.org/man/1/lttng/), + a command-line tool to liblttng‑ctl. +* [`lttng-crash`](https://lttng.org/man/1/lttng-crash/), a command-line + tool 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](#configure) time to + build LTTng‑tools for an older kernel. However, note that we + can't provide any guarantee below 2.6.27. + +* **[Userspace RCU](http://www.liburcu.org/) ≥ 0.9.0**. + + Debian/Ubuntu package: `liburcu-dev`. + +* **popt â‰¥ 1.13** + + Debian/Ubuntu package: `libpopt-dev`. + +* **[Libxml2](http://xmlsoft.org/) â‰¥ 2.7.6** + + Debian/Ubuntu package: `libxml2-dev` + +The following dependencies are optional: + +* **[Babeltrace 2](https://babeltrace.org/)**: default viewer + of the [`lttng view`](https://lttng.org/man/1/lttng-view/) + command. + + Debian/Ubuntu package: `babeltrace2` + +* **[LTTng‑UST](https://lttng.org/)** (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](https://www.python.org/) â‰¥ 3.0**: + `make check` and tests. + + Debian/Ubuntu package: `python3` + +* **[SWIG](http://www.swig.org/) â‰¥ 2.0** and + **Python 3 development headers**: Python bindings + (enabled at [build configuration](#configure) time with the + `--enable-python-bindings` option). + + Debian/Ubuntu packages: `swig2.0` and `python3-dev` + +* **modprobe** and/or + **[kmod](https://git.kernel.org/pub/scm/utils/kernel/kmod/kmod.git/) â‰¥ 22**: + automatic LTTng kernel modules loading (kernel tracing). + +* **Bash**: `make check`. + +* **[`man`](http://man7.org/linux/man-pages/man1/man.1.html)** + (manual pager): view `lttng` command manual + pages with the `--help` option or with the + [`lttng help`](https://lttng.org/man/1/lttng-help/) command. + + Note that you can use the [build configuration](#configure) 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](http://perfmon2.sourceforge.net/) â‰¥ 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. -Please see [`doc/quickstart.txt`](doc/quickstart.txt) to get started -with LTTng tracing. You can also use the `-h` or `--help` option of -any `lttng` command, e.g.: +See the [LTTng Documentation](https://lttng.org/docs/) for more +information on versioning. - lttng enable-event --help +Build from source +----------------- +### Dependencies -A network streaming HOWTO can be found in -[`doc/streaming-howto.txt`](doc/streaming-howto.txt) which quickly -helps you understand how to stream a LTTng 2.x trace. +You need the following tools to build LTTng‑tools: -A Python binding HOWTO can be found in -[`doc/python-howto.txt`](doc/python-howto.txt) which quickly helps you -understand how to use the Python module to control LTTng. +* **[GNU Autotools](https://www.gnu.org/software/automake/manual/html_node/Autotools-Introduction.html)** + (**Automake â‰¥ 1.10**, + **Autoconf â‰¥ 2.64**, and **Autoheader â‰¥ 2.50**) + +* **[GNU Libtool](http://www.gnu.org/software/autoconf/) â‰¥ 2.2** + +* **[Flex](https://github.com/westes/flex/) â‰¥ 2.5.35** + +* **[Bison](https://www.gnu.org/software/bison/) â‰¥ 2.4** + +To build the LTTng‑tools manual pages: + +* **[AsciiDoc](https://www.methods.co.nz/asciidoc/) â‰¥ 8.4.5** + + Previous versions could work, but were not tested. + +* **[xmlto](https://pagure.io/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](https://www.freedesktop.org/wiki/Software/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](https://lttng.org/docs/#doc-controlling-tracing) +section of the LTTng Documentation to learn how to use the +LTTng‑tools components. +See also the [LTTng manual pages](https://lttng.org/man/) (all +section 1 and 8 pages). -Contact -------- +As there's no official liblttng‑ctl Python bindings yet, see +[`doc/python-howto.txt`](doc/python-howto.txt) to understand how to +use them. -Maintainer: [Jérémie Galarneau](mailto:jeremie.galarneau@efficios.com) +Community +--------- +* **Mailing list**: + [lttng‑dev](https://lists.lttng.org/cgi-bin/mailman/listinfo). -Mailing list: [`lttng-dev@lists.lttng.org`](https://lttng.org/cgi-bin/mailman/listinfo/lttng-dev) +* **IRC channel**: + [`#lttng`](irc://irc.oftc.net/lttng) on the OFTC network. +* **Bug tracker**:: + [LTTng‑tools bug tracker](https://bugs.lttng.org/projects/lttng-tools/). -Package contents ----------------- +* **GitHub project**: + [lttng/lttng‑tools](https://github.com/lttng/lttng-tools/). -This package contains the following elements: +* **Continuous integration**: + [LTTng CI](https://ci.lttng.org/). - - `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. +* **Code review**: + [_lttng‑tools_ project](https://review.lttng.org/q/project:lttng-tools) + on LTTng Review. -- 2.34.1