1LTTNG-ENABLE-ROTAT(1) LTTng Manual LTTNG-ENABLE-ROTAT(1)
2
6 lttng-enable-rotation - Set an LTTng recording session rotation
7 schedule
8
10 lttng [GENERAL OPTIONS] enable-rotation [--session=SESSION]
11 (--timer=PERIODUS | --size=SIZE | --timer=PERIODUS --size=SIZE)
12
14 The lttng enable-rotation command sets a recording session rotation
15 schedule for:
16 With the --session=SESSION option
18 The recording session named SESSION.
19 Without the --session option
21 The current recording session (see lttng-concepts(7) to learn more
22 about the current recording session).
23 See lttng-concepts(7) to learn more about the recording session
25 rotation and trace chunk concepts.
26 With the --timer=PERIODUS option, the enable-rotation command sets a
28 rotation schedule so that LTTng performs an automatic rotation at least
29 every PERIODUS.
30 With the --size=SIZE option, the enable-rotation command sets a
32 rotation schedule so that LTTng performs an automatic rotation every
33 time the total size of the flushed part of the current trace chunk is
34 at least SIZE.
35 For both the --timer and --size options, LTTng checks the schedule
37 condition periodically using the monitor timers of the channels of the
38 selected recording session (see the --monitor-timer option of the
39 lttng-enable-channel(1) command). This means that:
40 • With the --timer=PERIODUS option, LTTng can perform an automatic
42 rotation when the elapsed time since the last automatic rotation is
43 slightly greater than PERIODUS.
44 The exact precision depends on the precision of the monitor timer,
46 which relies on the precision of the platform implementation of
47 POSIX timers.
48 • With the --size=SIZE option, LTTng can perform an automatic
50 rotation when the size of the flushed part of the current trace
51 chunk is greater than SIZE.
52 You may combine the --timer and --size options.
54 See the lttng-concepts(7) to learn how LTTng names a trace chunk
56 archive directory.
57 See the “EXAMPLES” section below for usage examples.
59 Unset a recording session rotation schedule with the lttng-disable-
61 rotation(1) command.
62 Important
64 You may only use the enable-rotation command when:
65 • The selected recording session was created in normal mode or in
67 network streaming mode (see lttng-create(1)).
68 • No channel was created with a configured trace file count or
70 size limit (see the --tracefile-size and --tracefile-count
71 options of the lttng-enable-channel(1) command).
72 For a given recording session, LTTng only performs an automatic
74 rotation when it’s not currently performing a rotation.
75
77 See lttng(1) for GENERAL OPTIONS.
78 Rotation schedule condition
80 --size=SIZE
81 Set a rotation schedule so that LTTng performs an automatic
82 rotation every time the total size of the flushed part of the
83 current trace chunk is at least SIZE bytes.
84 The k (KiB), M (MiB), and G (GiB) suffixes are supported.
86 --timer=PERIODUS
88 Set a rotation schedule so that LTTng performs an automatic
89 rotation approximately every PERIODUS microseconds.
90 The ms (milliseconds), s (seconds), m (minutes), and h (hours)
92 suffixes are supported.
93 Recording target
95 -s SESSION, --session=SESSION
96 Set a rotation schedule for the recording session named SESSION
97 instead of the current recording session.
98 Program information
100 -h, --help
101 Show help.
102 This option attempts to launch /usr/bin/man to view this manual
104 page. Override the manual pager path with the LTTNG_MAN_BIN_PATH
105 environment variable.
106 --list-options
108 List available command options and quit.
109
111 0
112 Success
113 1
115 Command error
116 2
118 Undefined command
119 3
121 Fatal error
122 4
124 Command warning (something went wrong during the command)
125
127 LTTNG_ABORT_ON_ERROR
128 Set to 1 to abort the process after the first error is encountered.
129 LTTNG_HOME
131 Path to the LTTng home directory.
132 Defaults to $HOME.
134 Useful when the Unix user running the commands has a non-writable
136 home directory.
137 LTTNG_MAN_BIN_PATH
139 Absolute path to the manual pager to use to read the LTTng
140 command-line help (with lttng-help(1) or with the --help option)
141 instead of /usr/bin/man.
142 LTTNG_SESSION_CONFIG_XSD_PATH
144 Path to the directory containing the session.xsd recording session
145 configuration XML schema.
146 LTTNG_SESSIOND_PATH
148 Absolute path to the LTTng session daemon binary (see lttng-
149 sessiond(8)) to spawn from the lttng-create(1) command.
150 The --sessiond-path general option overrides this environment
152 variable.
153
155 $LTTNG_HOME/.lttngrc
156 Unix user’s LTTng runtime configuration.
157 This is where LTTng stores the name of the Unix user’s current
159 recording session between executions of lttng(1). lttng-create(1)
160 and lttng-set-session(1) set the current recording session.
161 $LTTNG_HOME/lttng-traces
163 Default output directory of LTTng traces in local and snapshot
164 modes.
165 Override this path with the --output option of the lttng-create(1)
167 command.
168 $LTTNG_HOME/.lttng
170 Unix user’s LTTng runtime and configuration directory.
171 $LTTNG_HOME/.lttng/sessions
173 Default directory containing the Unix user’s saved recording
174 session configurations (see lttng-save(1) and lttng-load(1)).
175 /usr/local/etc/lttng/sessions
177 Directory containing the system-wide saved recording session
178 configurations (see lttng-save(1) and lttng-load(1)).
179 Note
181 $LTTNG_HOME defaults to the value of the HOME environment variable.
182
184 Example 1. Set the size-based rotation schedule of the current
185 recording session.
186 See the --size option.
188 $ lttng disable-rotation --size=256M
190 Example 2. Set the periodic rotation schedule of a specific recording
192 session.
193 See the --timer and --session options.
195 $ lttng disable-rotation --session=my-session --timer=5m
197
199 • LTTng project website <https://lttng.org>
200 • LTTng documentation <https://lttng.org/docs>
202 • LTTng bug tracker <https://bugs.lttng.org>
204 • Git repositories <https://git.lttng.org>
206 • GitHub organization <https://github.com/lttng>
208 • Continuous integration <https://ci.lttng.org/>
210 • Mailing list <https://lists.lttng.org/> for support and
212 development: lttng-dev@lists.lttng.org
213 • IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net
215
217 This program is part of the LTTng-tools project.
218 LTTng-tools is distributed under the GNU General Public License
220 version 2 <http://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html>.
221 See the LICENSE <https://github.com/lttng/lttng-
222 tools/blob/master/LICENSE> file for details.
223
225 Special thanks to Michel Dagenais and the DORSAL laboratory
226 <http://www.dorsal.polymtl.ca/> at École Polytechnique de Montréal for
227 the LTTng journey.
228 Also thanks to the Ericsson teams working on tracing which helped us
230 greatly with detailed bug reports and unusual test cases.
231
233 lttng(1), lttng-create(1), lttng-disable-rotation(1), lttng-rotate(1),
234 lttng-concepts(7)
235LTTng 2.13.10 14 June 2021 LTTNG-ENABLE-ROTAT(1)