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 a trace chunk is archived, LTTng 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 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 a manual 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` either at any time when the tracing session
43 is active (see man:lttng-start(1)), or a single time once the tracing
44 session becomes inactive (see man:lttng-stop(1)).
46 By default, the `lttng rotate` command ensures that the rotation is done
47 before printing the archived trace chunk's path and returning to the
48 prompt. The printed path is absolute when the tracing session was
49 created in normal mode and relative to the relay daemon's output
50 directory (see the nloption:--output option in man:lttng-relayd(8)) when
51 it was created in network streaming mode (see man:lttng-create(1)).
53 With the option:--no-wait option, the command finishes immediately,
54 hence a rotation might not be completed when the command is done. In
55 this case, there is no easy way to know when the current trace chunk is
56 archived, and the command does not print the archived trace chunk's
59 Because a rotation causes the tracing session's current sub-buffers to
60 be flushed, archived trace chunks are never redundant, that is, they do
61 not overlap over time like snapshots can (see man:lttng-snapshot(1)).
62 Also, a rotation does not directly cause discarded event records or
65 See <<limitations,LIMITATIONS>> for important limitations regarding
69 Trace chunk archive naming
70 ~~~~~~~~~~~~~~~~~~~~~~~~~~
71 A trace chunk archive is a subdirectory of a tracing session's output
72 directory (see the nloption:--output option in man:lttng-create(1))
73 which contains, through tracing domain and possibly UID/PID
74 subdirectories, metadata and data stream files.
76 A trace chunk archive is, at the same time:
78 * A self-contained LTTng trace.
79 * A member of a set of trace chunk archives which form the complete
80 trace of a tracing session.
82 In other words, an LTTng trace reader can read both the tracing
83 session output directory (all the trace chunk archives), or a
84 single trace chunk archive.
86 When a tracing session rotation occurs, the created trace chunk
90 __BEGIN__-__END__-__ID__
93 Date and time of the beginning of the trace chunk archive with
94 the ISO 8601-compatible `YYYYmmddTHHMMSS±HHMM` form, where
95 `YYYYmmdd` is the date and `HHMMSS±HHMM` is the time with the
96 time zone offset from UTC.
98 Example: `20171119T152407-0500`
101 Date and time of the end of the trace chunk archive with
102 the ISO 8601-compatible `YYYYmmddTHHMMSS±HHMM` form, where
103 `YYYYmmdd` is the date and `HHMMSS±HHMM` is the time with the
104 time zone offset from UTC.
106 Example: `20180118T152407+0930`
109 Unique numeric identifier of the trace chunk within its
112 Trace chunk archive name example: `20171119T152407-0500-20171119T151422-0500-3`
115 include::common-cmd-options-head.txt[]
118 option:-n, option:--no-wait::
119 Do not ensure that the rotation is done before returning to
123 include::common-cmd-help-options.txt[]
129 The `lttng rotate` command only works when:
131 * The tracing session is created in normal mode or in network streaming
132 mode (see man:lttng-create(1)).
134 * No channel was created with a configured trace file count or size
135 limit (see the nloption:--tracefile-size and
136 nloption:--tracefile-count options in man:lttng-enable-channel(1)).
138 * No manual rotation (`lttng rotate`) is currently happening.
140 * No automatic rotation schedule is currently set (see
141 man:lttng-enable-rotation(1)).
143 One way around this is to:
146 . Unset any automatic rotation schedule with
147 man:lttng-disable-rotation(1).
148 . Perform the manual rotation with `lttng rotation`.
149 . **If needed**, set the rotation schedule again
150 with man:lttng-enable-rotation(1).
154 include::common-cmd-footer.txt[]
159 man:lttng-enable-rotation(1),
160 man:lttng-disable-rotation(1),