lttng-rotate(1)
===============
+:revdate: 14 June 2021
NAME
----
-lttng-rotate - Archive a tracing session's current trace chunk
+lttng-rotate - Archive the current trace chunk of an LTTng recording session
SYNOPSIS
DESCRIPTION
-----------
-The `lttng rotate` command archives the current trace chunk of the
-current tracing session, or of the tracing session named 'SESSION' if
-provided, to the file system. This action is called a tracing session
-_rotation_.
-
-Once a trace chunk is archived, LTTng does not manage it anymore: you
-can read it, modify it, move it, or remove it.
-
-An archived trace chunk is a collection of metadata and data stream
-files which form a self-contained trace.
-
-The _current trace chunk_ of a given tracing session includes:
-
-* The stream files already written to the file system, and which are
- not part of a previously archived trace chunk, since the most recent
- event amongst:
-** The first time the tracing session was started with
- man:lttng-start(1).
-** The last rotation, either a manual one with `lttng rotate`, or an
- automatic one from a rotation schedule previously set with
- man:lttng-enable-rotation(1).
-* The content of all the non-flushed sub-buffers of the tracing
- session's channels.
-
-You can use `lttng rotate` either at any time when the tracing session
-is active (see man:lttng-start(1)), or a single time once the tracing
-session becomes inactive (see man:lttng-stop(1)).
-
-By default, the `lttng rotate` command ensures that the rotation is done
-before printing the archived trace chunk's path and returning to the
-prompt. The printed path is absolute when the tracing session was
-created in normal mode and relative to the relay daemon's output
-directory (see the nloption:--output option in man:lttng-relayd(8)) when
-it was created in network streaming mode (see man:lttng-create(1)).
-
-With the option:--no-wait option, the command finishes immediately,
-hence a rotation might not be completed when the command is done. In
-this case, there is no easy way to know when the current trace chunk is
-archived, and the command does not print the archived trace chunk's
-path.
-
-Because a rotation causes the tracing session's current sub-buffers to
-be flushed, 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.
-
-See <<limitations,LIMITATIONS>> for important limitations regarding
-this command.
-
-
-Trace chunk archive naming
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-A trace chunk archive is a subdirectory of a tracing session's output
-directory (see the nloption:--output option in man:lttng-create(1))
-which contains, through tracing domain and possibly UID/PID
-subdirectories, metadata and data stream files.
-
-A trace chunk archive is, at the same time:
-
-* A self-contained LTTng trace.
-* A member of a set of trace chunk archives which form the complete
- trace of a tracing session.
-
-In other words, an LTTng trace reader can read both the tracing
-session output directory (all the trace chunk archives), or a
-single trace chunk archive.
-
-When a tracing session rotation occurs, the created trace chunk
-archive is named:
+The `lttng rotate` command archives to the file system
+the current trace chunk of:
-[verse]
-__BEGIN__-__END__-__ID__
+With the 'SESSION' argument::
+ The recording session named 'SESSION'.
-__BEGIN__::
- Date and time of the beginning of the trace chunk archive with
- the ISO 8601-compatible `YYYYmmddTHHMMSS±HHMM` form, where
- `YYYYmmdd` is the date and `HHMMSS±HHMM` is the time with the
- time zone offset from UTC.
-+
-Example: `20171119T152407-0500`
+Without the 'SESSION' argument::
+ The current recording session (see man:lttng-concepts(7) to learn
+ more about the current recording session).
-__END__::
- Date and time of the end of the trace chunk archive with
- the ISO 8601-compatible `YYYYmmddTHHMMSS±HHMM` form, where
- `YYYYmmdd` is the date and `HHMMSS±HHMM` is the time with the
- time zone offset from UTC.
-+
-Example: `20180118T152407+0930`
+This action is called a _recording session rotation_.
-__ID__::
- Unique numeric identifier of the trace chunk within its
- tracing session.
+See man:lttng-concepts(7) to learn more about the recording session
+rotation and trace chunk concepts.
-Trace chunk archive name example: `20171119T152407-0500-20171119T151422-0500-3`
+You can use the `rotate` command:
+* Any time the recording session is active.
-include::common-cmd-options-head.txt[]
+* A single time once the recording session becomes inactive.
+See man:lttng-concepts(7) to learn more about the activity of a
+recording session.
-option:-n, option:--no-wait::
- Do not ensure that the rotation is done before returning to
- the prompt.
+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.
-include::common-cmd-help-options.txt[]
+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)).
-[[limitations]]
-LIMITATIONS
------------
-The `lttng rotate` command only works when:
+See the ``<<examples,EXAMPLES>>'' section below for usage examples.
+
+[IMPORTANT]
+====
+You may only use the `rotate` command when:
-* The tracing session is created in normal mode or in network streaming
- mode (see man:lttng-create(1)).
+* 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 in man:lttng-enable-channel(1)).
+ 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[]
+
-* No manual rotation (`lttng rotate`) is currently happening.
+include::common-lttng-cmd-after-options.txt[]
-* No automatic rotation schedule is currently set (see
- man:lttng-enable-rotation(1)).
-+
-One way around this is to:
-+
---
-. Unset any automatic rotation schedule with
- man:lttng-disable-rotation(1).
-. Perform the manual rotation with `lttng rotation`.
-. **If needed**, set the rotation schedule again
- with man:lttng-enable-rotation(1).
---
+[[examples]]
+EXAMPLES
+--------
+.Rotate the current recording session.
+====
+[role="term"]
+----
+$ lttng rotate
+----
+====
-include::common-cmd-footer.txt[]
+.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-enable-rotation(1),
+man:lttng(1),
man:lttng-disable-rotation(1),
-man:lttng(1)
+man:lttng-enable-rotation(1),
+man:lttng-concepts(7)
projects / lttng-tools.git / blobdiff