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

NAME

6       lttng-rotate - Archive a tracing session's current trace chunk
7

SYNOPSIS

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

DESCRIPTION

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
17       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
20       An archived trace chunk is a collection of metadata and data stream
21       files which form a self-contained LTTng trace.
22
23       The current trace chunk of a given tracing session includes:
24
25       ·   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
29           ·   The first time the tracing session was started with lttng-
30               start(1).
31
32           ·   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
36       ·   The content of all the non-flushed sub-buffers of the tracing
37           session’s channels.
38
39       You can use lttng rotate:
40
41       ·   At any time when the tracing session is active (see lttng-
42           start(1)).
43
44       ·   A single time once the tracing session becomes inactive (see lttng-
45           stop(1)).
46
47       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
54       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
60       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
66       See LIMITATIONS for important limitations regarding this command.
67
68   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
73       A trace chunk archive contains, through tracing domain and possibly
74       UID/PID subdirectories, metadata and data stream files.
75
76       A trace chunk archive is, at the same time:
77
78       ·   A self-contained LTTng trace.
79
80       ·   A member of a set of trace chunk archives which form the complete
81           trace of a tracing session.
82
83       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
87       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
91           archives/BEGIN-END-ID
92
93       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
99           Example: 20171119T152407-0500
100
101       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
107           Example: 20180118T152407+0930
108
109       ID
110           Unique numeric identifier of the trace chunk within its tracing
111           session.
112
113       Trace chunk archive name example:
114
115           archives/20171119T152407-0500-20171119T151422-0500-3
116

OPTIONS

118       General options are described in lttng(1).
119
120       -n, --no-wait
121           Do not ensure that the rotation is done before returning to the
122           prompt.
123
124   Program information
125       -h, --help
126           Show command help.
127
128           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
132       --list-options
133           List available command options.
134

LIMITATIONS

136       The lttng rotate command only works when:
137
138       ·   The tracing session is created in normal mode or in network
139           streaming mode (see lttng-create(1)).
140
141       ·   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
145       ·   No immediate rotation (lttng rotate) is currently happening.
146

ENVIRONMENT VARIABLES

148       LTTNG_ABORT_ON_ERROR
149           Set to 1 to abort the process after the first error is encountered.
150
151       LTTNG_HOME
152           Overrides the $HOME environment variable. Useful when the user
153           running the commands has a non-writable home directory.
154
155       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
159       LTTNG_SESSION_CONFIG_XSD_PATH
160           Path in which the session.xsd session configuration XML schema may
161           be found.
162
163       LTTNG_SESSIOND_PATH
164           Full session daemon binary path.
165
166           The --sessiond-path option has precedence over this environment
167           variable.
168
169       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

FILES

174       $LTTNG_HOME/.lttngrc
175           User LTTng runtime configuration.
176
177           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
182       $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
186       $LTTNG_HOME/.lttng
187           User LTTng runtime and configuration directory.
188
189       $LTTNG_HOME/.lttng/sessions
190           Default location of saved user tracing sessions (see lttng-save(1)
191           and lttng-load(1)).
192
193       /usr/local/etc/lttng/sessions
194           System-wide location of saved tracing sessions (see lttng-save(1)
195           and lttng-load(1)).
196
197           Note
198           $LTTNG_HOME defaults to $HOME when not explicitly set.
199

EXIT STATUS

201       0
202           Success
203
204       1
205           Command error
206
207       2
208           Undefined command
209
210       3
211           Fatal error
212
213       4
214           Command warning (something went wrong during the command)
215

BUGS

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

RESOURCES

221       ·   LTTng project website <https://lttng.org>
222
223       ·   LTTng documentation <https://lttng.org/docs>
224
225       ·   Git repositories <http://git.lttng.org>
226
227       ·   GitHub organization <http://github.com/lttng>
228
229       ·   Continuous integration <http://ci.lttng.org/>
230
231       ·   Mailing list <http://lists.lttng.org> for support and development:
232           lttng-dev@lists.lttng.org
233
234       ·   IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net
235

COPYRIGHTS

237       This program is part of the LTTng-tools project.
238
239       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

THANKS

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

SEE ALSO

253       lttng-enable-rotation(1), lttng-disable-rotation(1), lttng(1)
254
255
256
257LTTng 2.11.1                    18 October 2019                LTTNG-ROTATE(1)
Impressum