1LTTNG-ROTATE(1) LTTng Manual LTTNG-ROTATE(1)
2
6 lttng-rotate - Archive the current trace chunk of an LTTng recording
7 session
8
10 lttng [GENERAL OPTIONS] rotate [--no-wait] [SESSION]
11
13 The lttng rotate command archives to the file system the current trace
14 chunk of:
15 With the SESSION argument
17 The recording session named SESSION.
18 Without the SESSION argument
20 The current recording session (see lttng-concepts(7) to learn more
21 about the current recording session).
22 This action is called a recording session rotation.
24 See lttng-concepts(7) to learn more about the recording session
26 rotation and trace chunk concepts.
27 You can use the rotate command:
29 • Any time the recording session is active.
31 • A single time once the recording session becomes inactive.
33 See lttng-concepts(7) to learn more about the activity of a recording
35 session.
36 By default, the rotate command ensures that LTTng finished performing
38 the recording session rotation before it prints the path of the
39 archived trace chunk and exits. The printed path is absolute when the
40 recording session was created in normal mode and relative to the base
41 output directory of the relay daemon (see the --output option of lttng-
42 relayd(8)) when it was created in network streaming mode (see lttng-
43 create(1)).
44 Make the command exit immediately with the --no-wait option. In this
46 case, there’s no easy way to know when the current trace chunk becomes
47 archived, and the command does NOT print the path of the archived trace
48 chunk.
49 Because LTTng flushes the current sub-buffers of the selected recording
51 session when it performs a recording session rotation, archived trace
52 chunks are never redundant, that is, they do not overlap over time like
53 snapshots can (see lttng-snapshot(1)). Also, a rotation does NOT
54 directly cause discarded event records or packets.
55 A rotate-session trigger action can also rotate a recording session
57 (see lttng-add-trigger(1)).
58 See the “EXAMPLES” section below for usage examples.
60 Important
62 You may only use the rotate command when:
63 • The selected recording session was created in normal mode or in
65 network streaming mode (see lttng-create(1)).
66 • LTTng is not currently performing an immediate rotation (this
68 command).
69
71 See lttng(1) for GENERAL OPTIONS.
72 -n, --no-wait
74 Do not ensure that the recording session rotation operation is
75 completed before exiting.
76 Program information
78 -h, --help
79 Show help.
80 This option attempts to launch /usr/bin/man to view this manual
82 page. Override the manual pager path with the LTTNG_MAN_BIN_PATH
83 environment variable.
84 --list-options
86 List available command options and quit.
87
89 0
90 Success
91 1
93 Command error
94 2
96 Undefined command
97 3
99 Fatal error
100 4
102 Command warning (something went wrong during the command)
103
105 LTTNG_ABORT_ON_ERROR
106 Set to 1 to abort the process after the first error is encountered.
107 LTTNG_HOME
109 Path to the LTTng home directory.
110 Defaults to $HOME.
112 Useful when the Unix user running the commands has a non-writable
114 home directory.
115 LTTNG_MAN_BIN_PATH
117 Absolute path to the manual pager to use to read the LTTng
118 command-line help (with lttng-help(1) or with the --help option)
119 instead of /usr/bin/man.
120 LTTNG_SESSION_CONFIG_XSD_PATH
122 Path to the directory containing the session.xsd recording session
123 configuration XML schema.
124 LTTNG_SESSIOND_PATH
126 Absolute path to the LTTng session daemon binary (see lttng-
127 sessiond(8)) to spawn from the lttng-create(1) command.
128 The --sessiond-path general option overrides this environment
130 variable.
131
133 $LTTNG_HOME/.lttngrc
134 Unix user’s LTTng runtime configuration.
135 This is where LTTng stores the name of the Unix user’s current
137 recording session between executions of lttng(1). lttng-create(1)
138 and lttng-set-session(1) set the current recording session.
139 $LTTNG_HOME/lttng-traces
141 Default output directory of LTTng traces in local and snapshot
142 modes.
143 Override this path with the --output option of the lttng-create(1)
145 command.
146 $LTTNG_HOME/.lttng
148 Unix user’s LTTng runtime and configuration directory.
149 $LTTNG_HOME/.lttng/sessions
151 Default directory containing the Unix user’s saved recording
152 session configurations (see lttng-save(1) and lttng-load(1)).
153 /usr/local/etc/lttng/sessions
155 Directory containing the system-wide saved recording session
156 configurations (see lttng-save(1) and lttng-load(1)).
157 Note
159 $LTTNG_HOME defaults to the value of the HOME environment variable.
160
162 Example 1. Rotate the current recording session.
163 $ lttng rotate
165 Example 2. Rotate a specific recording session.
167 $ lttng rotate my-session
169 Example 3. Rotate the current recording session without waiting for
171 completion.
172 See the --no-wait option.
174 $ lttng rotate --no-wait
176
178 • LTTng project website <https://lttng.org>
179 • LTTng documentation <https://lttng.org/docs>
181 • LTTng bug tracker <https://bugs.lttng.org>
183 • Git repositories <https://git.lttng.org>
185 • GitHub organization <https://github.com/lttng>
187 • Continuous integration <https://ci.lttng.org/>
189 • Mailing list <https://lists.lttng.org/> for support and
191 development: lttng-dev@lists.lttng.org
192 • IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net
194
196 This program is part of the LTTng-tools project.
197 LTTng-tools is distributed under the GNU General Public License
199 version 2 <http://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html>.
200 See the LICENSE <https://github.com/lttng/lttng-
201 tools/blob/master/LICENSE> file for details.
202
204 Special thanks to Michel Dagenais and the DORSAL laboratory
205 <http://www.dorsal.polymtl.ca/> at École Polytechnique de Montréal for
206 the LTTng journey.
207 Also thanks to the Ericsson teams working on tracing which helped us
209 greatly with detailed bug reports and unusual test cases.
210
212 lttng(1), lttng-disable-rotation(1), lttng-enable-rotation(1), lttng-
213 concepts(7)
214LTTng 2.13.9 14 June 2021 LTTNG-ROTATE(1)