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: follow man-pages(7) for section names/order and for "SEE ALSO" Changes, following the "Sections within a manual page" section of man-pages(7): * Rename the "ENVIRONMENT VARIABLES" section to "ENVIRONMENT". * Rename the "COPYRIGHTS" section to "COPYRIGHT". * Move the "EXIT STATUS" section immediately after the "OPTIONS" section. * Remove the "BUGS" section. Such a section indicates known bugs (why would you ever have such a section anyway?). The "RESOURCES" section now contains the URL of our bug tracker. * Sort the manual pages by section, and then by name in the "SEE ALSO" section. Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com> Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com> Change-Id: I3d91073ec876efd98dcc723ddf40272c814663dd
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
Update some manual pages for LTTng-tools 2.13 This patch updates some manual pages for LTTng-tools 2.13. A few pages still remain to be updated, a task which is reserved for a subsequent patch. This patch: * Improves the consistency of the the command descriptions in `configure.ac`. * Adds `common-help-option.txt` which is the description of any `--help` option. * Adds `common-intro.txt` which is a common description introduction for the top-level manual pages. * Adds `lttng-event-rule.7.txt` which describes the common way to specify an event rule on the command-line. lttng-event-rule(7) has a "Migration from a recording event rule specification" section with a table which shows the relationship between lttng-enable-event(1) command-line arguments and lttng-event-rule(7) options. As of this patch, only `lttng-add-trigger.1.txt` references it, for the `event-rule-matches` trigger condition. `Makefile.am` is also updated to build and include manual pages of section 7. * 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. More specifically: lttng-add-context(1): Specify that this command adds context fields to be recorded to the event records of one or more channels. In other words, this is a recording-related command. You don't need to use it to access context fields with the filter expression of an event rule, for example. lttng-add-trigger(1): * Update the "NAME" section. * Add internal option links where missing. * Improve the description. Add links to the lttng-remove-trigger(1) and lttng-list-triggers(1) manual pages and explain what those commands are used for. Use "condition specifier" and "action specifier" terms to describe those groups of options. For condition and action specifiers, use localized synopses. For action specifiers, add links to the corresponding LTTng command manual pages. * Document the `--owner-id` option. * Group option descriptions. * Use "name" instead of "ID". * Refer to the new lttng-event-rule(7) manual page. * Remove the "no context field" limitation for `ERSPEC`. * Fix verse blocks nested in lists. lttng-create(1): * Add more documentation about tracing sessions. * Specify that the `create` command can spawn a session daemon. * Add the "Current tracing session" section to explain this concept and where it applies. * Clarify the "URL format" section. lttng-disable-event(1): Explain how this command can only find recording event rules to disable by instrumentation point type and event name condition. lttng-enable-event(1): I more or less completely rewrote this page. The document now clearly explains the related core concepts, shows the explicit and implicit conditions of a recording event rule, has one section for each condition explaining how an event can satisfy it, and more. The synopsis is more accurate. I added an "Event record name" section to indicate what's the name of a matched event depending on the instrumentation point type and some command-line arguments. I also added an "Enable a disabled recording event rule" section to explain how the `enable-event` command enables existing, disabled events. This manual page now documents all the options, even if they're the default, as defaults may change in the future. The new lttng-event-rule(7) manual page is based on this one, but with its own ways to specify event rule conditions. lttng-remove-trigger(1): * Use "name" instead of "ID". * Use `--owner-id` instead of `--user-id`. lttng-sessiond(8): * Explain what an LTTng session daemon does. * Clarify everything related to the tracing group and root session daemon. * Add a "Daemon configuration" section which explains the INI configuration files and the `--config` option. * Make the "Tracing session configuration loading" section (renamed) much more straightforward, with less text. * Specify that the `--daemonize` and `--background` options make `lttng-sessiond` only exit when the daemon is ready to receive client commands. lttng-set-session(1): List which commands rely on the current tracing session concept. lttng(1): * Add a "Session daemon connection" section which shows how the `lttng` tool (or any LTTng tracing control application) connects to a session daemon (user-specific vs. root session daemon). * Use tables to list the available commands. Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com> Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com> Change-Id: I6b98f4907d94763f3bfcb6576e4add9cfc59a2e3
sessiond: split event notifier error counter CLI options With this commit, users can specify the size of event notifier error counting buffers for each domain independently using the following new lttng-sessiond options: --event-notifier-error-buffer-size-kernel= --event-notifier-error-buffer-size-userspace= The index allocation is now also per-domain meaning that index allocation in the kernel domain doesn't affect available indices in the userspace domain and reversely. Small changes: - Add manual page description of the new options, - Rename `struct error_account_entry` to `struct ust_error_accounting_entry`. Signed-off-by: Francis Deslauriers <francis.deslauriers@efficios.com> Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com> Change-Id: I4758d32c00cb432be377fd67eaffa11b193bad74
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>
Fix: unprivilieged sessiond agent port clashes with root sessiond This fix addresses the same problem as reported in f28f9e44. The session daemon now tries to bind the agent TCP socket to a port within a range (10 ports by default). The session daemon will use the first available TCP port within that range when binding to "localhost". It is still possible to restrict the session daemon to the broken behaviour by specifying an agent port using the --agent-tcp-port PORT. If that option is used, the session daemon will attempt to bind to that part. If it fails, agent tracing will be marked as disabled. This fix is backported since the current logic of binding to a set port means that the default configuration on Ubuntu, Debian, and other distributions that launch an lttng-sessiond on boot does not allow the tracing of agent domains (Java Util Logging, log4j, and Python logging back-ends). By default, users are not part of the tracing group and it is not reasonable to expect users to be part of that group for userspace tracing. The behaviour of the "system" lttng-sessiond does not change as it will bind on the first available port within the range. The non-privilieged session daemons that will be launched after will be able to bind on other ports available within the range. Reported-by: Deborah Barnard <starfallprojects@gmail.com> Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
Add environment variable to allow abort on error The new environment variable LTTNG_ABORT_ON_ERROR allows each lttng-tools program to call abort() on PERROR() and ERR() after the error message has been printed to stderr. Signed-off-by: Mathieu Desnoyers <mathieu.desnoyers@efficios.com> Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
doc/man: linklttng macro -> man macro This macro is shorter, and some referenced man pages are not LTTng man pages, so the linklttng name makes little sense. Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com> Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>