Rename "tracing session" -> "recording session"

[lttng-tools.git] / doc / man / lttng.1.txt

lttng(1)
========
:revdate: 14 June 2021


NAME
----
lttng - Control LTTng tracing


SYNOPSIS
--------
[verse]
*lttng* [option:--group='GROUP'] [option:--mi=**xml**] [option:--no-sessiond | option:--sessiond-path='PATH']
      [option:--relayd-path='PATH'] [option:--quiet | option:-verbose...]
      '<<commands,COMMAND>>' ['COMMAND OPTIONS']


DESCRIPTION
-----------
include::common-intro.txt[]

The `lttng` command-line tool, as well as any user application linked
with the LTTng control library (`liblttng-ctl`), sends commands to a
listening LTTng session daemon (man:lttng-sessiond(8)). A session
daemon:

* Manages recording sessions (see man:lttng-concepts(7) to learn more
  about recording sessions).

* Controls the various components (like tracers and consumer daemons) of
  LTTng.

* Sends asynchronous notifications to user applications.

By default, the man:lttng-create(1) command automatically spawns:

* A session daemon for your Unix user if none is currently running.
+
Override the path of the session daemon binary to spawn with the
option:--sessiond-path option.
+
Avoid automatically spawning a session daemon with the
option:--no-sessiond option.

* A relay daemon (see man:lttng-relayd(8)) if all the following
  statements are true:
+
--
* You specify the nloption:--live option.

* You don't specify any of the nloption:--set-url, nloption:--ctrl-url,
  or nloption:--data-url options.

* No relay daemon is currently listening for TCP connections on
  +127.0.0.1:{default_network_viewer_port}+ (default LTTng live reader
  connection address and port).
--
+
Override the path of the relay daemon binary to spawn with the
option:--relayd-path option.

NOTE: The LTTng project recommends that you start the session daemon at
boot time for stable and long-term tracing.

See man:lttng-concepts(7) to learn more about the foundational concepts
of LTTng.

The `lttng` tool offers a subcommand-based command-line interface. The
``<<commands,COMMANDS>>'' section below lists the available commands.


Session daemon connection
~~~~~~~~~~~~~~~~~~~~~~~~~
For most of its commands, the `lttng` tool needs to connect to a
listening LTTng session daemon (man:lttng-sessiond(8)) to control LTTng
tracing.

Each Unix user may have its own independent running session daemon.
However, the `lttng` tool must connect to the session daemon of the
`root` user (the root session daemon) to control Linux kernel tracing.

How the `lttng` tool chooses which session daemon to connect to
is as follows:

If your Unix user is `root`::
    Connect to the root session daemon.

If your Unix user is not `root`::
    If your Unix user is part of the Unix tracing group:::
        Try to connect to the root session daemon.
+
If the root session daemon isn't running, connect to the session daemon
of your Unix user.

    If your Unix user is not part of the tracing group:::
        Connect to the session daemon of your Unix user.

The name of the Unix tracing group is one of:

With the nloption:--group='GROUP' option of the root session daemon (man:lttng-sessiond(8))::
    'GROUP'
+
In that case, you must use the option:--group='GROUP' option, with
the same 'GROUP' argument, of the `lttng` tool.

Without the nloption:--group option of the root session daemon::
    `tracing`

LTTng-instrumented user applications automatically register to both the
root and user session daemons. This makes it possible for both session
daemons to list the available instrumented applications and their
instrumentation points (see man:lttng-list(1)).


OPTIONS
-------
option:-g 'GROUP', option:--group='GROUP'::
    Set the name of the Unix tracing group to 'GROUP' instead of
    `tracing`.
+
You must use this option to be able to connect to a root session daemon
(man:lttng-sessiond(8)) which was started with its own
nloption:--group='GROUP' option.

option:-m `xml`, option:--mi=++xml++::
    Print the command's result using a stable XML machine interface (MI)
    output instead of the default, unstable human-readable output.
+
With this mode, `lttng` prints the resulting XML document to the
standard output, while it prints any error/warning to the standard error
with an unstable, human-readable format.
+
If any error occurs during the execution of `lttng`, the command
exits with a status different than{nbsp}0, and `lttng` does
:not: guarantee the syntax and data validity of its MI output.
+
An XML schema definition (XSD) file used for validation of the MI output
is available: see the `src/common/mi_lttng.xsd` file in the LTTng-tools
source tree.

option:-n, option:--no-sessiond::
    Do not automatically spawn a session daemon for your Unix user when
    running the man:lttng-create(1) command.
+
You may :not: use this option with the option:--sessiond-path option.

option:-q, option:--quiet::
    Suppress all messages, including warnings and errors.
+
You may :not: use this option with the option:--verbose option.

option:--sessiond-path='PATH'::
    Set the absolute path of the session daemon binary to spawn from the
    man:lttng-create(1) command to 'PATH'.
+
You may :not: use this option with the option:--no-sessiond option.

option:--relayd-path='PATH'::
    Set the absolute path of the relay daemon binary to spawn from the
    man:lttng-create(1) command to 'PATH'.

option:-v, option:--verbose::
    Increase verbosity.
+
Specify this option up to three times to get more levels of verbosity.
+
You may :not: use this option with the option:--quiet option.


Program information
~~~~~~~~~~~~~~~~~~~
include::common-help-option.txt[]

option:--list-commands::
    List available commands and quit.

option:-V, option:--version::
    Show version and quit.


[[commands]]
COMMANDS
--------
The following commands also have their own nloption:--help option.


Recording session
~~~~~~~~~~~~~~~~~
[options="header"]
|===
|Command |Description

|man:lttng-create(1) |{cmd_descr_create}.
|man:lttng-destroy(1) |{cmd_descr_destroy}.
|man:lttng-disable-rotation(1) |{cmd_descr_disable_rotation}.
|man:lttng-enable-rotation(1) |{cmd_descr_enable_rotation}.
|man:lttng-load(1) |{cmd_descr_load}.
|man:lttng-regenerate(1) |{cmd_descr_regenerate}.
|man:lttng-rotate(1) |{cmd_descr_rotate}.
|man:lttng-save(1) |{cmd_descr_save}.
|man:lttng-set-session(1) |{cmd_descr_set_session}.
|man:lttng-snapshot(1) |{cmd_descr_snapshot}.
|man:lttng-start(1) |{cmd_descr_start}.
|man:lttng-status(1) |{cmd_descr_status}.
|man:lttng-stop(1) |{cmd_descr_stop}.
|===


Channel
~~~~~~~
[options="header"]
|===
|Command |Description

|man:lttng-add-context(1) |{cmd_descr_add_context}.
|man:lttng-disable-channel(1) |{cmd_descr_disable_channel}.
|man:lttng-enable-channel(1) |{cmd_descr_enable_channel}.
|===


Recording event rule
~~~~~~~~~~~~~~~~~~~~
[options="header"]
|===
|Command |Description

|man:lttng-disable-event(1) |{cmd_descr_disable_event}.
|man:lttng-enable-event(1) |{cmd_descr_enable_event}.
|===

Information
~~~~~~~~~~~
[options="header"]
|===
|Command |Description

|man:lttng-list(1) |{cmd_descr_list}.
|===

Resource tracking
~~~~~~~~~~~~~~~~~
[options="header"]
|===
|Command |Description

|man:lttng-track(1) |{cmd_descr_track}.
|man:lttng-untrack(1) |{cmd_descr_untrack}.
|===

Trigger
~~~~~~~
[options="header"]
|===
|Command |Description

|man:lttng-add-trigger(1) |{cmd_descr_add_trigger}.
|man:lttng-list-triggers(1) |{cmd_descr_list_triggers}.
|man:lttng-remove-trigger(1) |{cmd_descr_remove_trigger}.
|===

Miscellaneous
~~~~~~~~~~~~~
[options="header"]
|===
|Command |Description

|man:lttng-help(1) |{cmd_descr_help}.
|man:lttng-version(1) |{cmd_descr_version}.
|man:lttng-view(1) |{cmd_descr_view}.
|===


include::common-lttng-cmd-after-options.txt[]


include::common-footer.txt[]


SEE ALSO
--------
man:lttng-concepts(7)
man:lttng-relayd(8),
man:lttng-sessiond(8)