7 lttng-rotate - Archive a tracing session's current trace chunk
13 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *rotate* [option:--no-wait] ['SESSION']
18 The `lttng rotate` command archives the current trace chunk of the
19 current tracing session, or of the tracing session named 'SESSION' if
20 provided, to the file system. This action is called a tracing session
23 Once LTTng archives a trace chunk, it does not manage it anymore: you
24 can read it, modify it, move it, or remove it.
26 An _archived trace chunk_ is a collection of metadata and data stream
27 files which form a self-contained LTTng trace.
29 The _current trace chunk_ of a given tracing session includes:
31 * The stream files already written to the file system, and which are
32 not part of a previously archived trace chunk, since the most recent
34 ** The first time the tracing session was started with
36 ** The last rotation, either an immediate one with `lttng rotate`, or an
37 automatic one from a rotation schedule previously set with
38 man:lttng-enable-rotation(1).
39 * The content of all the non-flushed sub-buffers of the tracing
42 You can use `lttng rotate`:
44 * At any time when the tracing session is active (see
46 * A single time once the tracing session becomes inactive
47 (see man:lttng-stop(1)).
49 By default, the `lttng rotate` command ensures that LTTng finished
50 performing the tracing session rotation before it prints the archived
51 trace chunk's path and exits. The printed path is absolute when the
52 tracing session was created in normal mode and relative to the relay
53 daemon's output directory (see the nloption:--output option in
54 man:lttng-relayd(8)) when it was created in network streaming mode (see
57 With the option:--no-wait option, the command finishes immediately, so
58 that LTTng might not have completed the rotation when the command exits.
59 In this case, there is no easy way to know when the current trace chunk
60 becomes archived, and the command does not print the archived trace
63 Because when LTTng performs a tracing session rotation, it flushes the
64 tracing session's current sub-buffers, archived trace chunks are never
65 redundant, that is, they do not overlap over time like snapshots can
66 (see man:lttng-snapshot(1)). Also, a rotation does not directly cause
67 discarded event records or packets.
69 See <<limitations,LIMITATIONS>> for important limitations regarding
73 Trace chunk archive naming
74 ~~~~~~~~~~~~~~~~~~~~~~~~~~
75 A trace chunk archive is a subdirectory of the `archives` subdirectory
76 within a tracing session's output directory (see the nloption:--output
77 option in man:lttng-create(1) and man:lttng-relayd(8)).
79 A trace chunk archive contains, through tracing domain and possibly
80 UID/PID subdirectories, metadata and data stream files.
82 A trace chunk archive is, at the same time:
84 * A self-contained LTTng trace.
85 * A member of a set of trace chunk archives which form the complete
86 trace of a tracing session.
88 In other words, an LTTng trace reader can read both the tracing
89 session output directory (all the trace chunk archives), or a
90 single trace chunk archive.
92 When LTTng performs a tracing session rotation, it names the resulting
93 trace chunk archive as such, relative to the tracing session's output
97 archives/__BEGIN__-__END__-__ID__
100 Date and time of the beginning of the trace chunk archive with
101 the ISO{nbsp}8601-compatible `YYYYmmddTHHMMSS±HHMM` form, where
102 `YYYYmmdd` is the date and `HHMMSS±HHMM` is the time with the
103 time zone offset from UTC.
105 Example: `20171119T152407-0500`
108 Date and time of the end of the trace chunk archive with
109 the ISO{nbsp}8601-compatible `YYYYmmddTHHMMSS±HHMM` form, where
110 `YYYYmmdd` is the date and `HHMMSS±HHMM` is the time with the
111 time zone offset from UTC.
113 Example: `20180118T152407+0930`
116 Unique numeric identifier of the trace chunk within its tracing
119 Trace chunk archive name example:
122 archives/20171119T152407-0500-20171119T151422-0500-3
126 include::common-cmd-options-head.txt[]
129 option:-n, option:--no-wait::
130 Do not ensure that the rotation is done before returning to
134 include::common-cmd-help-options.txt[]
140 The `lttng rotate` command only works when:
142 * The tracing session is created in normal mode or in network streaming
143 mode (see man:lttng-create(1)).
145 * No channel was created with a configured trace file count or size
146 limit (see the nloption:--tracefile-size and
147 nloption:--tracefile-count options in man:lttng-enable-channel(1)).
149 * No immediate rotation (`lttng rotate`) is currently happening.
152 include::common-cmd-footer.txt[]
157 man:lttng-enable-rotation(1),
158 man:lttng-disable-rotation(1),