git.lttng.org Git - lttng-tools.git/atom - doc/man/lttng-crash.1.txt history LTTng 2.0 tools and control repository https://git.lttng.org?p=lttng-tools.git Jérémie Galarneau /gitweb/theme/git-favicon.png /gitweb/theme/git-logo.png 2021-06-16T18:22:08Z gitweb Rename "tracing session" -> "recording session" 2021-06-15T02:52:02Z Philippe Proulx eeppeliteloop@gmail.com Jérémie Galarneau jeremie.galarneau@efficios.com 2021-06-15T02:52:02Z https://git.lttng.org?p=lttng-tools.git;a=commitdiff;h=e971184584781f70bbbfc52bbede8b9abf0436e5
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
  • [DB] doc/man/lttng-crash.1.txt
Update the remaining manual pages for LTTng-tools 2.13 2021-04-29T21:00:07Z Philippe Proulx eeppeliteloop@gmail.com Jérémie Galarneau jeremie.galarneau@efficios.com 2021-04-29T21:00:07Z https://git.lttng.org?p=lttng-tools.git;a=commitdiff;h=26f0c7794376456fcb5b13d4eae91c0ccf0dfe66
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
  • [DB] doc/man/lttng-crash.1.txt
Update some manual pages for LTTng-tools 2.13 2021-03-03T20:18:30Z Philippe Proulx eeppeliteloop@gmail.com Jérémie Galarneau jeremie.galarneau@efficios.com 2021-03-03T20:18:30Z https://git.lttng.org?p=lttng-tools.git;a=commitdiff;h=484b2a0cbefcf0c7072622a5a411ea5ed849da28
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
  • [DB] doc/man/lttng-crash.1.txt
lttng-crash(1): document the command's positional argument 2020-04-03T20:14:05Z Philippe Proulx eeppeliteloop@gmail.com Jérémie Galarneau jeremie.galarneau@efficios.com 2020-04-03T20:14:05Z https://git.lttng.org?p=lttng-tools.git;a=commitdiff;h=6f7058c201395648796691f05e69ce285a185f08
lttng-crash(1): document the command's positional argument

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Change-Id: I919329f2e072b14ad94181e98e49cb8840991225
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
  • [DB] doc/man/lttng-crash.1.txt
doc/man: refer to Babeltrace 2 instead of Babeltrace 1 2020-04-02T19:03:15Z Philippe Proulx eeppeliteloop@gmail.com Jérémie Galarneau jeremie.galarneau@efficios.com 2020-04-02T19:03:15Z https://git.lttng.org?p=lttng-tools.git;a=commitdiff;h=32357a9aba8ff33b71b46ec05b285171b97b9e55
doc/man: refer to Babeltrace 2 instead of Babeltrace 1

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Change-Id: Icafd69f28304b14e49e8cf8e21d2c6ebe3e319b6
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
  • [DB] doc/man/lttng-crash.1.txt
doc/man: use specific revision date for each manual page 2019-10-18T19:53:05Z Philippe Proulx eeppeliteloop@gmail.com Jérémie Galarneau jeremie.galarneau@efficios.com 2019-10-18T19:53:05Z https://git.lttng.org?p=lttng-tools.git;a=commitdiff;h=4605890e0a926f1c88355051dcd6d8a8dd135c58
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>
  • [DB] doc/man/lttng-crash.1.txt
Use https in links to the lttng.org website 2018-06-05T15:38:08Z Jérémie Galarneau jeremie.galarneau@efficios.com Jérémie Galarneau jeremie.galarneau@efficios.com 2018-06-05T15:38:08Z https://git.lttng.org?p=lttng-tools.git;a=commitdiff;h=a18d95449bcab62b0ed21ea8b93798c2e31bdf62
Use https in links to the lttng.org website

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
  • [DB] doc/man/lttng-crash.1.txt
doc/man: put short option's argument too 2016-11-28T23:25:28Z Philippe Proulx eeppeliteloop@gmail.com Jérémie Galarneau jeremie.galarneau@efficios.com 2016-11-28T23:25:28Z https://git.lttng.org?p=lttng-tools.git;a=commitdiff;h=59b19c3c82a824b602b4e3cd70e1cb22448fcb9d
doc/man: put short option's argument too

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
  • [DB] doc/man/lttng-crash.1.txt
doc/man: linklttng macro -> man macro 2016-04-07T07:17:21Z Philippe Proulx eeppeliteloop@gmail.com Jérémie Galarneau jeremie.galarneau@efficios.com 2016-04-07T07:17:21Z https://git.lttng.org?p=lttng-tools.git;a=commitdiff;h=7c1a4458be934fec31aa27a0eb52e4d0b8cb3803
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>
  • [DB] doc/man/lttng-crash.1.txt
doc/man: convert lttng-crash(1) to AsciiDoc 2016-03-05T03:19:13Z Philippe Proulx eeppeliteloop@gmail.com Jérémie Galarneau jeremie.galarneau@efficios.com 2016-03-05T03:19:13Z https://git.lttng.org?p=lttng-tools.git;a=commitdiff;h=aec4668ae1d87cdbd0e08d3ee02d5e75a1c9ca79
doc/man: convert lttng-crash(1) to AsciiDoc

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
  • [DB] doc/man/lttng-crash.1.txt