Rename "tracing session" -> "recording session"

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

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


NAME
----
lttng-destroy - Destroy LTTng recording sessions


SYNOPSIS
--------
[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *destroy* [option:--no-wait] [option:--all | 'SESSION']


DESCRIPTION
-----------
The `lttng destroy` command destroys:

With the 'SESSION' argument::
    The recording session named 'SESSION'.

With the option:--all option::
    *All* the recording sessions of the connected session daemon for
    your Unix user, or for all users if your Unix user is `root`, as
    listed in the output of `lttng list` (see man:lttng-list(1)).
+
See the ``Session daemon connection'' section of man:lttng(1) to learn
how a user application connects to a session daemon.

Otherwise::
    The current recording session (see man:lttng-concepts(7) to learn
    more about the current recording session).
+
In that case, the current recording session becomes nonexistent.

See man:lttng-concepts(7) to learn more about recording sessions.

``Destroying'' a recording session means freeing the resources which the
LTTng daemons and tracers acquired for it, also making sure to flush all
the recorded trace data to either the local file system or the connected
LTTng relay daemon (see man:lttng-relayd(8)), depending on the recording
session mode.

The `destroy` command stops any recording activity within the selected
recording session(s). By default, the command runs an implicit
man:lttng-stop(1) command to ensure that the trace data of the recording
session(s) is valid before it exits. Make the command exit immediately
with the option:--no-wait option. In this case, however, the traces(s)
might not be valid when the command exits, and there's no way to know
when it/they become valid.

If, for a recording session{nbsp}__RS__ to destroy with the `destroy`
command, the following statements are true:

* You don't specify the option:--no-wait option.

* LTTng archived the current trace chunk (see man:lttng-concepts(7))
  of{nbsp}__RS__ at least once during its lifetime.

Then all the subdirectories of the output directory of{nbsp}__RS__
(local or remote) are considered trace chunk archives once the `destroy`
command exits. In other words, it's safe to read them, modify them, move
them, or remove then.

See the ``<<examples,EXAMPLES>>'' section below for usage examples.


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


option:-a, option:--all::
    Destroy all the recording sessions of your Unix user, or of all
    users if your Unix user is `root`, as listed in the output of
    man:lttng-list(1), instead of the current recording session or the
    recording session named 'SESSION'.

option:-n, option:--no-wait::
    Do :not: ensure that the trace data of the recording session(s) to
    destroy is valid before exiting.


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


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


[[examples]]
EXAMPLES
--------
.Destroy the current recording session.
====
[role="term"]
----
$ lttng destroy
----
====

.Destroy the current recording session without waiting for completion.
====
See the option:--no-wait option.

[role="term"]
----
$ lttng destroy --no-wait
----
====

.Destroy a specific recording session.
====
[role="term"]
----
$ lttng destroy my-session
----
====

.Destroy all recording sessions.
====
See the option:--all option.

[role="term"]
----
$ lttng destroy --all
----
====


include::common-footer.txt[]


SEE ALSO
--------
man:lttng(1),
man:lttng-create(1),
man:lttng-list(1),
man:lttng-concepts(7)