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

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


NAME
----
lttng-rotate - Archive the current trace chunk of an LTTng recording session


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


DESCRIPTION
-----------
The `lttng rotate` command archives to the file system
the current trace chunk of:

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

Without the 'SESSION' argument::
    The current recording session (see man:lttng-concepts(7) to learn
    more about the current recording session).

This action is called a _recording session rotation_.

See man:lttng-concepts(7) to learn more about the recording session
rotation and trace chunk concepts.

You can use the `rotate` command:

* Any time the recording session is active.

* A single time once the recording session becomes inactive.

See man:lttng-concepts(7) to learn more about the activity of a
recording session.

By default, the `rotate` command ensures that LTTng finished performing
the recording session rotation before it prints the path of the archived
trace chunk and exits. The printed path is absolute when the recording
session was created in normal mode and relative to the base output
directory of the relay daemon (see the nloption:--output option of
man:lttng-relayd(8)) when it was created in network streaming mode (see
man:lttng-create(1)).

Make the command exit immediately with the option:--no-wait option. In
this case, there's no easy way to know when the current trace chunk
becomes archived, and the command does :not: print the path of the
archived trace chunk.

Because LTTng flushes the current sub-buffers of the selected recording
session when it performs a recording session rotation, archived trace
chunks are never redundant, that is, they do not overlap over time like
snapshots can (see man:lttng-snapshot(1)). Also, a rotation does :not:
directly cause discarded event records or packets.

A `rotate-session` trigger action can also rotate a recording session
(see man:lttng-add-trigger(1)).

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

[IMPORTANT]
====
You may only use the `rotate` command when:

* The selected recording session was created in normal mode or in
  network streaming mode (see man:lttng-create(1)).

* No channel was created with a configured trace file count or size
  limit (see the nloption:--tracefile-size and
  nloption:--tracefile-count options of the man:lttng-enable-channel(1)
  command).

* LTTng is not currently performing an immediate rotation (this
  command).
====


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


option:-n, option:--no-wait::
    Do not ensure that the recording session rotation operation is
    completed before exiting.


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


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


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

.Rotate a specific recording session.
====
[role="term"]
----
$ lttng rotate my-session
----
====

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

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


include::common-footer.txt[]


SEE ALSO
--------
man:lttng(1),
man:lttng-disable-rotation(1),
man:lttng-enable-rotation(1),
man:lttng-concepts(7)
Commit	Line	Data
	1	lttng-rotate(1)
	2	===============
	3	:revdate: 14 June 2021
	4
	5
	6	NAME
	7	----
	8	lttng-rotate - Archive the current trace chunk of an LTTng recording session
	9
	10
	11	SYNOPSIS
	12	--------
	13	[verse]
	14	lttng ['linkgenoptions:(GENERAL OPTIONS)'] rotate [option:--no-wait] ['SESSION']
	15
	16
	17	DESCRIPTION
	18	-----------
	19	The `lttng rotate` command archives to the file system
	20	the current trace chunk of:
	21
	22	With the 'SESSION' argument::
	23	The recording session named 'SESSION'.
	24
	25	Without the 'SESSION' argument::
	26	The current recording session (see man:lttng-concepts(7) to learn
	27	more about the current recording session).
	28
	29	This action is called a _recording session rotation_.
	30
	31	See man:lttng-concepts(7) to learn more about the recording session
	32	rotation and trace chunk concepts.
	33
	34	You can use the `rotate` command:
	35
	36	* Any time the recording session is active.
	37
	38	* A single time once the recording session becomes inactive.
	39
	40	See man:lttng-concepts(7) to learn more about the activity of a
	41	recording session.
	42
	43	By default, the `rotate` command ensures that LTTng finished performing
	44	the recording session rotation before it prints the path of the archived
	45	trace chunk and exits. The printed path is absolute when the recording
	46	session was created in normal mode and relative to the base output
	47	directory of the relay daemon (see the nloption:--output option of
	48	man:lttng-relayd(8)) when it was created in network streaming mode (see
	49	man:lttng-create(1)).
	50
	51	Make the command exit immediately with the option:--no-wait option. In
	52	this case, there's no easy way to know when the current trace chunk
	53	becomes archived, and the command does :not: print the path of the
	54	archived trace chunk.
	55
	56	Because LTTng flushes the current sub-buffers of the selected recording
	57	session when it performs a recording session rotation, archived trace
	58	chunks are never redundant, that is, they do not overlap over time like
	59	snapshots can (see man:lttng-snapshot(1)). Also, a rotation does :not:
	60	directly cause discarded event records or packets.
	61
	62	A `rotate-session` trigger action can also rotate a recording session
	63	(see man:lttng-add-trigger(1)).
	64
	65	See the ``<<examples,EXAMPLES>>'' section below for usage examples.
	66
	67	[IMPORTANT]
	68	====
	69	You may only use the `rotate` command when:
	70
	71	* The selected recording session was created in normal mode or in
	72	network streaming mode (see man:lttng-create(1)).
	73
	74	* No channel was created with a configured trace file count or size
	75	limit (see the nloption:--tracefile-size and
	76	nloption:--tracefile-count options of the man:lttng-enable-channel(1)
	77	command).
	78
	79	* LTTng is not currently performing an immediate rotation (this
	80	command).
	81	====
	82
	83
	84	include::common-lttng-cmd-options-head.txt[]
	85
	86
	87	option:-n, option:--no-wait::
	88	Do not ensure that the recording session rotation operation is
	89	completed before exiting.
	90
	91
	92	include::common-lttng-cmd-help-options.txt[]
	93
	94
	95	include::common-lttng-cmd-after-options.txt[]
	96
	97
	98	[[examples]]
	99	EXAMPLES
	100	--------
	101	.Rotate the current recording session.
	102	====
	103	[role="term"]
	104	----
	105	$ lttng rotate
	106	----
	107	====
	108
	109	.Rotate a specific recording session.
	110	====
	111	[role="term"]
	112	----
	113	$ lttng rotate my-session
	114	----
	115	====
	116
	117	.Rotate the current recording session without waiting for completion.
	118	====
	119	See the option:--no-wait option.
	120
	121	[role="term"]
	122	----
	123	$ lttng rotate --no-wait
	124	----
	125	====
	126
	127
	128	include::common-footer.txt[]
	129
	130
	131	SEE ALSO
	132	--------
	133	man:lttng(1),
	134	man:lttng-disable-rotation(1),
	135	man:lttng-enable-rotation(1),
	136	man:lttng-concepts(7)