lttng-enable-rotation(1)

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

NAME

6       lttng-enable-rotation - Set a tracing session's rotation schedule
7

SYNOPSIS

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

DESCRIPTION

13       The lttng enable-rotation command sets a rotation schedule for the
14       current tracing session, or for the tracing session named SESSION if
15       provided. See lttng-rotate(1) for more information about the concepts
16       of a tracing session rotation and a trace chunk.
17
18       With the --timer option, the rotation schedule is set so that an
19       automatic rotation occurs at least every PERIOD (microseconds without a
20       unit suffix).
21
22       With the --size option, the rotation schedule is set so that an
23       automatic rotation occurs every time the total size of the flushed part
24       of the current trace chunk is at least SIZE (bytes without a unit
25       suffix).
26
27       For both --timer and --size options, LTTng checks the schedule
28       condition periodically using the monitor timers of the tracing
29       session’s channels (see the --monitor-timer option of the lttng-enable-
30       channel(1) command). This means that:
31
32       •   With the --timer option, the automatic rotation can occur when the
33           elapsed time since the last automatic rotation is slightly greater
34           than PERIOD. The exact precision is governed by the monitor timer’s
35           precision, which relies on the precision of the platform’s
36           implementation of POSIX timers.
37
38       •   With the --size option, the automatic rotation can occur when the
39           size of the flushed part of the current trace chunk is greater than
40           SIZE.
41
42       You can combine the --timer and --size options.
43
44       The naming convention of a trace chunk archive which an automatic
45       rotation creates is the same as with the immediate rotation command,
46       lttng-rotate(1).
47
48       You can unset a rotation schedule with the lttng-disable-rotation(1)
49       command.
50
51       See LIMITATIONS for important limitations regarding this command.
52

OPTIONS

54       General options are described in lttng(1).
55
56   Rotation schedule condition
57       --size=SIZE
58           Set a rotation schedule so that an automatic rotation occurs every
59           time the total size of the flushed part of the current trace chunk
60           is at least SIZE bytes. The k (kiB), M (MiB), and G (GiB) suffixes
61           are supported.
62
63       --timer=PERIOD
64           Set a rotation schedule so that an automatic rotation occurs at
65           least every PERIOD microseconds. The ms (milliseconds), s
66           (seconds), m (minutes), and h (hours) suffixes are supported.
67
68   Target
69       -s SESSION, --session=SESSION
70           Set a rotation schedule for the tracing session named SESSION
71           instead of the current tracing session.
72
73   Program information
74       -h, --help
75           Show command help.
76
77           This option, like lttng-help(1), attempts to launch /usr/bin/man to
78           view the command’s man page. The path to the man pager can be
79           overridden by the LTTNG_MAN_BIN_PATH environment variable.
80
81       --list-options
82           List available command options.
83

LIMITATIONS

85       The lttng enable-rotation command only works when:
86
87       •   The tracing session is created in normal mode or in network
88           streaming mode (see lttng-create(1)).
89
90       •   No channel was created with a configured trace file count or size
91           limit (see the --tracefile-size and --tracefile-count options in
92           lttng-enable-channel(1)).
93
94       For a given tracing session, LTTng only performs an automatic rotation
95       when no other rotation is currently happening.
96

ENVIRONMENT VARIABLES

98       LTTNG_ABORT_ON_ERROR
99           Set to 1 to abort the process after the first error is encountered.
100
101       LTTNG_HOME
102           Overrides the $HOME environment variable. Useful when the user
103           running the commands has a non-writable home directory.
104
105       LTTNG_MAN_BIN_PATH
106           Absolute path to the man pager to use for viewing help information
107           about LTTng commands (using lttng-help(1) or lttng COMMAND --help).
108
109       LTTNG_SESSION_CONFIG_XSD_PATH
110           Path in which the session.xsd session configuration XML schema may
111           be found.
112
113       LTTNG_SESSIOND_PATH
114           Full session daemon binary path.
115
116           The --sessiond-path option has precedence over this environment
117           variable.
118
119       Note that the lttng-create(1) command can spawn an LTTng session daemon
120       automatically if none is running. See lttng-sessiond(8) for the
121       environment variables influencing the execution of the session daemon.
122

FILES

124       $LTTNG_HOME/.lttngrc
125           User LTTng runtime configuration.
126
127           This is where the per-user current tracing session is stored
128           between executions of lttng(1). The current tracing session can be
129           set with lttng-set-session(1). See lttng-create(1) for more
130           information about tracing sessions.
131
132       $LTTNG_HOME/lttng-traces
133           Default output directory of LTTng traces. This can be overridden
134           with the --output option of the lttng-create(1) command.
135
136       $LTTNG_HOME/.lttng
137           User LTTng runtime and configuration directory.
138
139       $LTTNG_HOME/.lttng/sessions
140           Default location of saved user tracing sessions (see lttng-save(1)
141           and lttng-load(1)).
142
143       /usr/local/etc/lttng/sessions
144           System-wide location of saved tracing sessions (see lttng-save(1)
145           and lttng-load(1)).
146
147           Note
148           $LTTNG_HOME defaults to $HOME when not explicitly set.
149

EXIT STATUS

151       0
152           Success
153
154       1
155           Command error
156
157       2
158           Undefined command
159
160       3
161           Fatal error
162
163       4
164           Command warning (something went wrong during the command)
165

BUGS

167       If you encounter any issue or usability problem, please report it on
168       the LTTng bug tracker <https://bugs.lttng.org/projects/lttng-tools>.
169

RESOURCES

171       •   LTTng project website <https://lttng.org>
172
173       •   LTTng documentation <https://lttng.org/docs>
174
175       •   Git repositories <http://git.lttng.org>
176
177       •   GitHub organization <http://github.com/lttng>
178
179       •   Continuous integration <http://ci.lttng.org/>
180
181       •   Mailing list <http://lists.lttng.org> for support and development:
182           lttng-dev@lists.lttng.org
183
184       •   IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net
185

COPYRIGHTS

187       This program is part of the LTTng-tools project.
188
189       LTTng-tools is distributed under the GNU General Public License version
190       2 <http://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html>. See the
191       LICENSE <https://github.com/lttng/lttng-tools/blob/master/LICENSE> file
192       for details.
193

THANKS

195       Special thanks to Michel Dagenais and the DORSAL laboratory
196       <http://www.dorsal.polymtl.ca/> at École Polytechnique de Montréal for
197       the LTTng journey.
198
199       Also thanks to the Ericsson teams working on tracing which helped us
200       greatly with detailed bug reports and unusual test cases.
201