Rename "tracing session" -> "recording session" Starting from LTTng 2.13, _tracing_ is defined as attempting to execute one or more actions when emitting an event, which is very close to the trigger definition. To highlight that a tracing session is only about event recording, rename this concept to _recording session_. This patch mostly changes the manual pages, although I also updated some C source and other files which contain user-facing text to use the new term. I didn't update logging messages because debugging scripts could still refer to "tracing sessions". The lttng-concepts(7) manual page mentions that the "recording session" term was "tracing session" before LTTng 2.13. Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com> Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com> Change-Id: I620d6b6be9e0f1dac14c0bc5e26094c3b3711c75
doc/man: use double quotes when referring to internal section This patch adds double quotes to all the manual page internal section references using their full name. Those references often have the following AsciiDoc form: See the <<id,Full section name>> section below. With this patch, this would be converted to: See the ``<<id,Full section name>>'' section below. In the rendered manual page, before this patch: See the Full section name section below. ¯¯¯¯ ¯¯¯¯¯¯¯ ¯¯¯¯ With this patch: See the “Full section name” section below. The purpose of this patch is, thanks to the change in `doc/man/manpage.xsl`, to remove the italic style for the text of internal links. Because there's no way to create dynamic internal links in a manual page, this style causes internal links to look weird when they're not a full section name, for example: Note that the trigger doesn't need to [...] ¯¯¯¯¯¯¯ The HTML rendering of LTTng-tools manual pages can still benefit from internal links. This patch makes it possible to add more internal links without degrading the visual style of manual pages when rendered in a terminal. Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com> Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com> Change-Id: I1a5ef7eab7ff1e66c137e16b51a9c9074e43f583
doc/man: lttng(1) command pages: always include `common-footer.txt` The end of an lttng(1) command manual page source now looks like this: include::common-lttng-cmd-help-options.txt[] include::common-lttng-cmd-after-options.txt[] include::common-footer.txt[] `common-lttng-cmd-after-options.txt` contains the "EXIT STATUS", "ENVIRONMENT", and "FILES" sections. `common-footer.txt` begins with the "RESOURCES" section. This will make it possible to insert an "EXAMPLES" section between `common-lttng-cmd-after-options.txt` and `common-footer.txt`. Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com> Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com> Change-Id: I1eee42d7386f4671d9825e9d3e131e54f868ee39
Update the remaining manual pages for LTTng-tools 2.13 This patch updates the remaining manual pages for LTTng-tools 2.13. This patch: * Improves the consistency of some command descriptions in `configure.ac`. * Adds `common-daemon-cfg.txt` which is a section explaining how to configure a daemon (session or relay). lttng-sessiond(8) and lttng-relayd(8) include this file. * Adds `lttng-concepts.7.txt` which is an adapted copy of the "Core concepts" section of the online LTTng Documentation. This centralizes all the LTTng theory into a single manual page instead of having this information split into multiple lttng(1) command manual pages. Many manual pages now refer to lttng-concepts(7), making it possible to cut a lot of text in those. * Updates existing manual pages to: * Have a style and voice which is more consistent with the LTTng Documentation (website) for 2.13. * Fix various terminology ambiguities. * Use more textual variables and lists to explain more complex logic and processes. * Always use the same pattern to specify the behaviour of an lttng(1) command depending on the `SESSION` argument or the `--session` option. * For the commands which can perform more than one task, list their available tasks at the beginning of the "DESCRIPTION" section. * For some lttng(1) commands which can operate on all tracing sessions (for example, lttng-clear(1) and lttng-destroy(1)), always indicate that they target all your Unix user's tracing sessions or, if your Unix user is `root`, the tracing sessions of all the Unix users within the root session daemon. * Clean the "SEE ALSO" sections. * Always have "LTTng" in the "NAME" section of a manual page. More specifically: lttng-create(1): * Clarify the tracing session modes. * Clarify how the command adds (or not) a snapshot output for a snapshot mode tracing session. * Specify that `--output=DIR` is equivalent to `--set-url=file://DIR`. lttng-enable-channel(1): Include the `--discard`, `--buffers-uid`, and `--buffers-global` options in the "SYNOPSIS" section even if they are the current defaults. lttng-list(1): Explain what this command does exactly using a tree of options and arguments. lttng-load(1): Clarify how LTTng finds tracing session configurations. lttng-relayd(8): * Document the missing `--group` option. * Rework the text in general. * Add a daemon configuration section with an INI file example. * Add more cross-references between options and equivalent environment variables. lttng-rotate(1): Specify that the `rotate-session` trigger action can also rotate a tracing session. lttng-save(1): Clarify the output path. lttng-sessiond(8): Add more cross-references between options and equivalent environment variables. lttng-shapshot(1): * Clarify everything related to the snapshot output of a tracing session, including when and how the lttng-create(1) command adds an initial snapshot output. * Specify that the `snapshot-session` trigger action can also take a snapshot of a tracing session. lttng-track(1): lttng-untrack(1): * Simply refer to allowing processes to record events and to process attribute inclusion sets instead of using the vague "tracker" terminology. * Restate that those commands control an implicit condition of a recording event rule, as per lttng-concepts(7). * Improve the documentation of each inclusion set selection option. Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com> Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com> Change-Id: Iac7498ee979fe077f0927a9b8335f6c07f203989
doc/man: use specific revision date for each manual page This patch makes each manual page indicate its own revision date with the `revdate` AsciiDoc attribute. In `asciidoc.conf`, we use this attribute to specify the DocBook reference page date (see <https://tdg.docbook.org/tdg/4.5/refentryinfo.html> and <https://tdg.docbook.org/tdg/4.5/date.html>). Without the DocBook date tag, `xmlto` uses the current date. You can see this date at the bottom of the rendered manual page: ... SEE ALSO lttng-enable-rotation(1), lttng-disable-rotation(1), lttng(1) LTTng 2.12.0-pre 10/18/2019 LTTNG-ROTATE(1) Using the manual page generation date seems unexpected for the reader here. For this initial change, I used the last commit date for each source file. Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com> Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
Rename the "metadata regenerate" command to "regenerate metadata" Prepare the deprecation of the "metadata regenerate" command since we need to regenerate the statedump as well, so it is more convenient to have one command to regenerate various session's attributes. Signed-off-by: Julien Desfossez <jdesfossez@efficios.com> Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>