1LTTNG-ROTATE(1)                  LTTng Manual                  LTTNG-ROTATE(1)
2
3
4

NAME

6       lttng-rotate - Archive the current trace chunk of an LTTng recording
7       session
8

SYNOPSIS

10       lttng [GENERAL OPTIONS] rotate [--no-wait] [SESSION]
11

DESCRIPTION

13       The lttng rotate command archives to the file system the current trace
14       chunk of:
15
16       With the SESSION argument
17           The recording session named SESSION.
18
19       Without the SESSION argument
20           The current recording session (see lttng-concepts(7) to learn more
21           about the current recording session).
22
23       This action is called a recording session rotation.
24
25       See lttng-concepts(7) to learn more about the recording session
26       rotation and trace chunk concepts.
27
28       You can use the rotate command:
29
30       •   Any time the recording session is active.
31
32       •   A single time once the recording session becomes inactive.
33
34       See lttng-concepts(7) to learn more about the activity of a recording
35       session.
36
37       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
45       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
50       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
56       A rotate-session trigger action can also rotate a recording session
57       (see lttng-add-trigger(1)).
58
59       See the “EXAMPLES” section below for usage examples.
60
61       Important
62           You may only use the rotate command when:
63
64           •   The selected recording session was created in normal mode or in
65               network streaming mode (see lttng-create(1)).
66
67           •   LTTng is not currently performing an immediate rotation (this
68               command).
69

OPTIONS

71       See lttng(1) for GENERAL OPTIONS.
72
73       -n, --no-wait
74           Do not ensure that the recording session rotation operation is
75           completed before exiting.
76
77   Program information
78       -h, --help
79           Show help.
80
81           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
85       --list-options
86           List available command options and quit.
87

EXIT STATUS

89       0
90           Success
91
92       1
93           Command error
94
95       2
96           Undefined command
97
98       3
99           Fatal error
100
101       4
102           Command warning (something went wrong during the command)
103

ENVIRONMENT

105       LTTNG_ABORT_ON_ERROR
106           Set to 1 to abort the process after the first error is encountered.
107
108       LTTNG_HOME
109           Path to the LTTng home directory.
110
111           Defaults to $HOME.
112
113           Useful when the Unix user running the commands has a non-writable
114           home directory.
115
116       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
121       LTTNG_SESSION_CONFIG_XSD_PATH
122           Path to the directory containing the session.xsd recording session
123           configuration XML schema.
124
125       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
129           The --sessiond-path general option overrides this environment
130           variable.
131

FILES

133       $LTTNG_HOME/.lttngrc
134           Unix user’s LTTng runtime configuration.
135
136           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
140       $LTTNG_HOME/lttng-traces
141           Default output directory of LTTng traces in local and snapshot
142           modes.
143
144           Override this path with the --output option of the lttng-create(1)
145           command.
146
147       $LTTNG_HOME/.lttng
148           Unix user’s LTTng runtime and configuration directory.
149
150       $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
154       /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
158       Note
159           $LTTNG_HOME defaults to the value of the HOME environment variable.
160

EXAMPLES

162       Example 1. Rotate the current recording session.
163
164               $ lttng rotate
165
166       Example 2. Rotate a specific recording session.
167
168               $ lttng rotate my-session
169
170       Example 3. Rotate the current recording session without waiting for
171       completion.
172
173           See the --no-wait option.
174
175               $ lttng rotate --no-wait
176

RESOURCES

178       •   LTTng project website <https://lttng.org>
179
180       •   LTTng documentation <https://lttng.org/docs>
181
182       •   LTTng bug tracker <https://bugs.lttng.org>
183
184       •   Git repositories <https://git.lttng.org>
185
186       •   GitHub organization <https://github.com/lttng>
187
188       •   Continuous integration <https://ci.lttng.org/>
189
190       •   Mailing list <https://lists.lttng.org/> for support and
191           development: lttng-dev@lists.lttng.org
192
193       •   IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net
194
196       This program is part of the LTTng-tools project.
197
198       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

THANKS

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
208       Also thanks to the Ericsson teams working on tracing which helped us
209       greatly with detailed bug reports and unusual test cases.
210

SEE ALSO

212       lttng(1), lttng-disable-rotation(1), lttng-enable-rotation(1), lttng-
213       concepts(7)
214
215
216
217LTTng 2.13.10                    14 June 2021                  LTTNG-ROTATE(1)
Impressum