1LTTNG-ENABLE-ROTAT(1)            LTTng Manual            LTTNG-ENABLE-ROTAT(1)
2
3
4

NAME

6       lttng-enable-rotation - Set an LTTng recording session rotation
7       schedule
8

SYNOPSIS

10       lttng [GENERAL OPTIONS] enable-rotation [--session=SESSION]
11             (--timer=PERIODUS | --size=SIZE | --timer=PERIODUS --size=SIZE)
12

DESCRIPTION

14       The lttng enable-rotation command sets a recording session rotation
15       schedule for:
16
17       With the --session=SESSION option
18           The recording session named SESSION.
19
20       Without the --session option
21           The current recording session (see lttng-concepts(7) to learn more
22           about the current recording session).
23
24       See lttng-concepts(7) to learn more about the recording session
25       rotation and trace chunk concepts.
26
27       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
31       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
36       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
41       •   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
45           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
49       •   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
53       You may combine the --timer and --size options.
54
55       See the lttng-concepts(7) to learn how LTTng names a trace chunk
56       archive directory.
57
58       See the “EXAMPLES” section below for usage examples.
59
60       Unset a recording session rotation schedule with the lttng-disable-
61       rotation(1) command.
62
63       Important
64           You may only use the enable-rotation command when:
65
66           •   The selected recording session was created in normal mode or in
67               network streaming mode (see lttng-create(1)).
68
69           •   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
73           For a given recording session, LTTng only performs an automatic
74           rotation when it’s not currently performing a rotation.
75

OPTIONS

77       See lttng(1) for GENERAL OPTIONS.
78
79   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
85           The k (KiB), M (MiB), and G (GiB) suffixes are supported.
86
87       --timer=PERIODUS
88           Set a rotation schedule so that LTTng performs an automatic
89           rotation approximately every PERIODUS microseconds.
90
91           The ms (milliseconds), s (seconds), m (minutes), and h (hours)
92           suffixes are supported.
93
94   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
99   Program information
100       -h, --help
101           Show help.
102
103           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
107       --list-options
108           List available command options and quit.
109

EXIT STATUS

111       0
112           Success
113
114       1
115           Command error
116
117       2
118           Undefined command
119
120       3
121           Fatal error
122
123       4
124           Command warning (something went wrong during the command)
125

ENVIRONMENT

127       LTTNG_ABORT_ON_ERROR
128           Set to 1 to abort the process after the first error is encountered.
129
130       LTTNG_HOME
131           Path to the LTTng home directory.
132
133           Defaults to $HOME.
134
135           Useful when the Unix user running the commands has a non-writable
136           home directory.
137
138       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
143       LTTNG_SESSION_CONFIG_XSD_PATH
144           Path to the directory containing the session.xsd recording session
145           configuration XML schema.
146
147       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
151           The --sessiond-path general option overrides this environment
152           variable.
153

FILES

155       $LTTNG_HOME/.lttngrc
156           Unix user’s LTTng runtime configuration.
157
158           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
162       $LTTNG_HOME/lttng-traces
163           Default output directory of LTTng traces in local and snapshot
164           modes.
165
166           Override this path with the --output option of the lttng-create(1)
167           command.
168
169       $LTTNG_HOME/.lttng
170           Unix user’s LTTng runtime and configuration directory.
171
172       $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
176       /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
180       Note
181           $LTTNG_HOME defaults to the value of the HOME environment variable.
182

EXAMPLES

184       Example 1. Set the size-based rotation schedule of the current
185       recording session.
186
187           See the --size option.
188
189               $ lttng disable-rotation --size=256M
190
191       Example 2. Set the periodic rotation schedule of a specific recording
192       session.
193
194           See the --timer and --session options.
195
196               $ lttng disable-rotation --session=my-session --timer=5m
197

RESOURCES

199       •   LTTng project website <https://lttng.org>
200
201       •   LTTng documentation <https://lttng.org/docs>
202
203       •   LTTng bug tracker <https://bugs.lttng.org>
204
205       •   Git repositories <https://git.lttng.org>
206
207       •   GitHub organization <https://github.com/lttng>
208
209       •   Continuous integration <https://ci.lttng.org/>
210
211       •   Mailing list <https://lists.lttng.org/> for support and
212           development: lttng-dev@lists.lttng.org
213
214       •   IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net
215
217       This program is part of the LTTng-tools project.
218
219       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

THANKS

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

SEE ALSO

233       lttng(1), lttng-create(1), lttng-disable-rotation(1), lttng-rotate(1),
234       lttng-concepts(7)
235
236
237
238LTTng 2.13.7                     14 June 2021            LTTNG-ENABLE-ROTAT(1)
Impressum