1LTTNG-ROTATE(1) LTTng Manual LTTNG-ROTATE(1)
2
6 lttng-rotate - Archive a tracing session's current trace chunk
7
9 lttng [GENERAL OPTIONS] rotate [--no-wait] [SESSION]
10
12 The lttng rotate command archives the current trace chunk of the
13 current tracing session, or of the tracing session named SESSION if
14 provided, to the file system. This action is called a tracing session
15 rotation.
16 Once LTTng archives a trace chunk, it does not manage it anymore: you
18 can read it, modify it, move it, or remove it.
19 An archived trace chunk is a collection of metadata and data stream
21 files which form a self-contained LTTng trace.
22 The current trace chunk of a given tracing session includes:
24 • The stream files already written to the file system, and which are
26 not part of a previously archived trace chunk, since the most
27 recent event amongst:
28 • The first time the tracing session was started with lttng-
30 start(1).
31 • The last rotation, either an immediate one with lttng rotate,
33 or an automatic one from a rotation schedule previously set
34 with lttng-enable-rotation(1).
35 • The content of all the non-flushed sub-buffers of the tracing
37 session’s channels.
38 You can use lttng rotate:
40 • At any time when the tracing session is active (see lttng-
42 start(1)).
43 • A single time once the tracing session becomes inactive (see lttng-
45 stop(1)).
46 By default, the lttng rotate command ensures that LTTng finished
48 performing the tracing session rotation before it prints the archived
49 trace chunk’s path and exits. The printed path is absolute when the
50 tracing session was created in normal mode and relative to the relay
51 daemon’s output directory (see the --output option in lttng-relayd(8))
52 when it was created in network streaming mode (see lttng-create(1)).
53 With the --no-wait option, the command finishes immediately, so that
55 LTTng might not have completed the rotation when the command exits. In
56 this case, there is no easy way to know when the current trace chunk
57 becomes archived, and the command does not print the archived trace
58 chunk’s path.
59 Because when LTTng performs a tracing session rotation, it flushes the
61 tracing session’s current sub-buffers, archived trace chunks are never
62 redundant, that is, they do not overlap over time like snapshots can
63 (see lttng-snapshot(1)). Also, a rotation does not directly cause
64 discarded event records or packets.
65 See LIMITATIONS for important limitations regarding this command.
67 Trace chunk archive naming
69 A trace chunk archive is a subdirectory of the archives subdirectory
70 within a tracing session’s output directory (see the --output option in
71 lttng-create(1) and lttng-relayd(8)).
72 A trace chunk archive contains, through tracing domain and possibly
74 UID/PID subdirectories, metadata and data stream files.
75 A trace chunk archive is, at the same time:
77 • A self-contained LTTng trace.
79 • A member of a set of trace chunk archives which form the complete
81 trace of a tracing session.
82 In other words, an LTTng trace reader can read both the tracing session
84 output directory (all the trace chunk archives), or a single trace
85 chunk archive.
86 When LTTng performs a tracing session rotation, it names the resulting
88 trace chunk archive as such, relative to the tracing session’s output
89 directory:
90 archives/BEGIN-END-ID
92 BEGIN
94 Date and time of the beginning of the trace chunk archive with the
95 ISO 8601-compatible YYYYmmddTHHMMSS±HHMM form, where YYYYmmdd is
96 the date and HHMMSS±HHMM is the time with the time zone offset from
97 UTC.
98 Example: 20171119T152407-0500
100 END
102 Date and time of the end of the trace chunk archive with the
103 ISO 8601-compatible YYYYmmddTHHMMSS±HHMM form, where YYYYmmdd is
104 the date and HHMMSS±HHMM is the time with the time zone offset from
105 UTC.
106 Example: 20180118T152407+0930
108 ID
110 Unique numeric identifier of the trace chunk within its tracing
111 session.
112 Trace chunk archive name example:
114 archives/20171119T152407-0500-20171119T151422-0500-3
116
118 General options are described in lttng(1).
119 -n, --no-wait
121 Do not ensure that the rotation is done before returning to the
122 prompt.
123 Program information
125 -h, --help
126 Show command help.
127 This option, like lttng-help(1), attempts to launch /usr/bin/man to
129 view the command’s man page. The path to the man pager can be
130 overridden by the LTTNG_MAN_BIN_PATH environment variable.
131 --list-options
133 List available command options.
134
136 The lttng rotate command only works when:
137 • The tracing session is created in normal mode or in network
139 streaming mode (see lttng-create(1)).
140 • No channel was created with a configured trace file count or size
142 limit (see the --tracefile-size and --tracefile-count options in
143 lttng-enable-channel(1)).
144 • No immediate rotation (lttng rotate) is currently happening.
146
148 LTTNG_ABORT_ON_ERROR
149 Set to 1 to abort the process after the first error is encountered.
150 LTTNG_HOME
152 Overrides the $HOME environment variable. Useful when the user
153 running the commands has a non-writable home directory.
154 LTTNG_MAN_BIN_PATH
156 Absolute path to the man pager to use for viewing help information
157 about LTTng commands (using lttng-help(1) or lttng COMMAND --help).
158 LTTNG_SESSION_CONFIG_XSD_PATH
160 Path in which the session.xsd session configuration XML schema may
161 be found.
162 LTTNG_SESSIOND_PATH
164 Full session daemon binary path.
165 The --sessiond-path option has precedence over this environment
167 variable.
168 Note that the lttng-create(1) command can spawn an LTTng session daemon
170 automatically if none is running. See lttng-sessiond(8) for the
171 environment variables influencing the execution of the session daemon.
172
174 $LTTNG_HOME/.lttngrc
175 User LTTng runtime configuration.
176 This is where the per-user current tracing session is stored
178 between executions of lttng(1). The current tracing session can be
179 set with lttng-set-session(1). See lttng-create(1) for more
180 information about tracing sessions.
181 $LTTNG_HOME/lttng-traces
183 Default output directory of LTTng traces. This can be overridden
184 with the --output option of the lttng-create(1) command.
185 $LTTNG_HOME/.lttng
187 User LTTng runtime and configuration directory.
188 $LTTNG_HOME/.lttng/sessions
190 Default location of saved user tracing sessions (see lttng-save(1)
191 and lttng-load(1)).
192 /usr/local/etc/lttng/sessions
194 System-wide location of saved tracing sessions (see lttng-save(1)
195 and lttng-load(1)).
196 Note
198 $LTTNG_HOME defaults to $HOME when not explicitly set.
199
201 0
202 Success
203 1
205 Command error
206 2
208 Undefined command
209 3
211 Fatal error
212 4
214 Command warning (something went wrong during the command)
215
217 If you encounter any issue or usability problem, please report it on
218 the LTTng bug tracker <https://bugs.lttng.org/projects/lttng-tools>.
219
221 • LTTng project website <https://lttng.org>
222 • LTTng documentation <https://lttng.org/docs>
224 • Git repositories <http://git.lttng.org>
226 • GitHub organization <http://github.com/lttng>
228 • Continuous integration <http://ci.lttng.org/>
230 • Mailing list <http://lists.lttng.org> for support and development:
232 lttng-dev@lists.lttng.org
233 • IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net
235
237 This program is part of the LTTng-tools project.
238 LTTng-tools is distributed under the GNU General Public License version
240 2 <http://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html>. See the
241 LICENSE <https://github.com/lttng/lttng-tools/blob/master/LICENSE> file
242 for details.
243
245 Special thanks to Michel Dagenais and the DORSAL laboratory
246 <http://www.dorsal.polymtl.ca/> at École Polytechnique de Montréal for
247 the LTTng journey.
248 Also thanks to the Ericsson teams working on tracing which helped us
250 greatly with detailed bug reports and unusual test cases.
251
253 lttng-enable-rotation(1), lttng-disable-rotation(1), lttng(1)
254LTTng 2.12.4 18 October 2019 LTTNG-ROTATE(1)