doc/man: use double quotes when referring to internal section
[lttng-tools.git] / doc / man / lttng-enable-rotation.1.txt
1 lttng-enable-rotation(1)
2 ========================
3 :revdate: 17 May 2021
4
5
6 NAME
7 ----
8 lttng-enable-rotation - Set an LTTng tracing session rotation schedule
9
10
11 SYNOPSIS
12 --------
13 [verse]
14 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-rotation* [option:--session='SESSION']
15 (option:--timer='PERIODUS' | option:--size='SIZE' | option:--timer='PERIODUS' option:--size='SIZE')
16
17
18 DESCRIPTION
19 -----------
20 The `lttng enable-rotation` command sets a tracing session rotation
21 schedule for:
22
23 With the option:--session='SESSION' option::
24 The tracing session named 'SESSION'.
25
26 Without the option:--session option::
27 The current tracing session (see man:lttng-concepts(7) to learn more
28 about the current tracing session).
29
30 See man:lttng-concepts(7) to learn more about the tracing session
31 rotation and trace chunk concepts.
32
33 With the option:--timer='PERIODUS' option, the `enable-rotation` command
34 sets a rotation schedule so that LTTng performs an automatic rotation at
35 least every 'PERIODUS'.
36
37 With the option:--size='SIZE' option, the `enable-rotation` command sets
38 a rotation schedule so that LTTng performs an automatic rotation every
39 time the total size of the flushed part of the current trace chunk is at
40 least 'SIZE'.
41
42 For both the option:--timer and option:--size options, LTTng checks the
43 schedule condition periodically using the monitor timers of the channels
44 of the selected tracing session (see the nloption:--monitor-timer option
45 of the man:lttng-enable-channel(1) command). This means that:
46
47 * With the option:--timer='PERIODUS' option, LTTng can perform an
48 automatic rotation when the elapsed time since the last automatic
49 rotation is slightly greater than 'PERIODUS'.
50 +
51 The exact precision depends on the precision of the monitor timer, which
52 relies on the precision of the platform implementation of POSIX timers.
53
54 * With the option:--size='SIZE' option, LTTng can perform an automatic
55 rotation when the size of the flushed part of the current trace chunk
56 is greater than 'SIZE'.
57
58 You may combine the option:--timer and option:--size options.
59
60 See the man:lttng-concepts(7) to learn how LTTng names a trace chunk
61 archive directory.
62
63 See the ``<<examples,EXAMPLES>>'' section below for usage examples.
64
65 Unset a tracing session rotation schedule with the
66 man:lttng-disable-rotation(1) command.
67
68 [IMPORTANT]
69 ====
70 You may only use the `enable-rotation` command when:
71
72 * The selected tracing session was created in normal mode or in network
73 streaming mode (see man:lttng-create(1)).
74
75 * No channel was created with a configured trace file count or size
76 limit (see the nloption:--tracefile-size and
77 nloption:--tracefile-count options of the man:lttng-enable-channel(1)
78 command).
79
80 For a given tracing session, LTTng only performs an automatic rotation
81 when it's not currently performing a rotation.
82 ====
83
84
85 include::common-lttng-cmd-options-head.txt[]
86
87
88 Rotation schedule condition
89 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
90 option:--size='SIZE'::
91 Set a rotation schedule so that LTTng performs an automatic rotation
92 every time the total size of the flushed part of the current trace
93 chunk is at least 'SIZE' bytes.
94 +
95 The `k`{nbsp}(KiB), `M`{nbsp}(MiB), and `G`{nbsp}(GiB) suffixes are
96 supported.
97
98 option:--timer='PERIODUS'::
99 Set a rotation schedule so that LTTng performs an automatic rotation
100 approximately every 'PERIODUS' microseconds.
101 +
102 The `ms`{nbsp}(milliseconds), `s`{nbsp}(seconds), `m`{nbsp}(minutes),
103 and `h`{nbsp}(hours) suffixes are supported.
104
105
106 Recording target
107 ~~~~~~~~~~~~~~~~
108 option:-s 'SESSION', option:--session='SESSION'::
109 Set a rotation schedule for the tracing session named 'SESSION'
110 instead of the current tracing session.
111
112
113 include::common-lttng-cmd-help-options.txt[]
114
115
116 include::common-lttng-cmd-after-options.txt[]
117
118
119 [[examples]]
120 EXAMPLES
121 --------
122 .Set the size-based rotation schedule of the current tracing session.
123 ====
124 See the option:--size option.
125
126 [role="term"]
127 ----
128 $ lttng disable-rotation --size=256M
129 ----
130 ====
131
132 .Set the periodic rotation schedule of a specific tracing session.
133 ====
134 See the option:--timer and option:--session options.
135
136 [role="term"]
137 ----
138 $ lttng disable-rotation --session=my-session --timer=5m
139 ----
140 ====
141
142
143 include::common-footer.txt[]
144
145
146 SEE ALSO
147 --------
148 man:lttng(1),
149 man:lttng-create(1),
150 man:lttng-disable-rotation(1),
151 man:lttng-rotate(1),
152 man:lttng-concepts(7)
This page took 0.034542 seconds and 5 git commands to generate.