Commit | Line | Data |
---|---|---|
980bb5fd PP |
1 | lttng-enable-rotation(1) |
2 | ======================== | |
8b40f822 | 3 | :revdate: 17 May 2021 |
980bb5fd PP |
4 | |
5 | ||
6 | NAME | |
7 | ---- | |
188419c4 | 8 | lttng-enable-rotation - Set an LTTng tracing session rotation schedule |
980bb5fd PP |
9 | |
10 | ||
11 | SYNOPSIS | |
12 | -------- | |
13 | [verse] | |
eb027cfc | 14 | *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-rotation* [option:--session='SESSION'] |
484b2a0c | 15 | (option:--timer='PERIODUS' | option:--size='SIZE' | option:--timer='PERIODUS' option:--size='SIZE') |
980bb5fd PP |
16 | |
17 | ||
18 | DESCRIPTION | |
19 | ----------- | |
484b2a0c PP |
20 | The `lttng enable-rotation` command sets a tracing session rotation |
21 | schedule for: | |
980bb5fd | 22 | |
484b2a0c PP |
23 | With the option:--session='SESSION' option:: |
24 | The tracing session named 'SESSION'. | |
980bb5fd | 25 | |
484b2a0c | 26 | Without the option:--session option:: |
188419c4 PP |
27 | The current tracing session (see man:lttng-concepts(7) to learn more |
28 | about the current tracing session). | |
980bb5fd | 29 | |
188419c4 PP |
30 | See man:lttng-concepts(7) to learn more about the tracing session |
31 | rotation and trace chunk concepts. | |
437afa71 | 32 | |
484b2a0c PP |
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'. | |
437afa71 | 36 | |
484b2a0c PP |
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'. | |
980bb5fd | 41 | |
484b2a0c PP |
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 | |
188419c4 | 45 | of the man:lttng-enable-channel(1) command). This means that: |
484b2a0c PP |
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. | |
eb027cfc | 59 | |
188419c4 PP |
60 | See the man:lttng-concepts(7) to learn how LTTng names a trace chunk |
61 | archive directory. | |
484b2a0c | 62 | |
8b40f822 PP |
63 | See the <<examples,EXAMPLES>> section below for usage examples. |
64 | ||
484b2a0c PP |
65 | Unset a tracing session rotation schedule with the |
66 | man:lttng-disable-rotation(1) command. | |
67 | ||
68 | [IMPORTANT] | |
69 | ==== | |
188419c4 | 70 | You may only use the `enable-rotation` command when: |
484b2a0c PP |
71 | |
72 | * The selected tracing session was created in normal mode or in network | |
73 | streaming mode (see man:lttng-create(1)). | |
980bb5fd | 74 | |
484b2a0c PP |
75 | * No channel was created with a configured trace file count or size |
76 | limit (see the nloption:--tracefile-size and | |
188419c4 PP |
77 | nloption:--tracefile-count options of the man:lttng-enable-channel(1) |
78 | command). | |
980bb5fd | 79 | |
484b2a0c | 80 | For a given tracing session, LTTng only performs an automatic rotation |
188419c4 | 81 | when it's not currently performing a rotation. |
484b2a0c | 82 | ==== |
980bb5fd PP |
83 | |
84 | ||
55e06994 | 85 | include::common-lttng-cmd-options-head.txt[] |
980bb5fd PP |
86 | |
87 | ||
31099add PP |
88 | Rotation schedule condition |
89 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
980bb5fd | 90 | option:--size='SIZE':: |
484b2a0c PP |
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':: | |
188419c4 PP |
99 | Set a rotation schedule so that LTTng performs an automatic rotation |
100 | approximately every 'PERIODUS' microseconds. | |
484b2a0c PP |
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 | ~~~~~~~~~~~~~~~~ | |
980bb5fd | 108 | option:-s 'SESSION', option:--session='SESSION':: |
31099add PP |
109 | Set a rotation schedule for the tracing session named 'SESSION' |
110 | instead of the current tracing session. | |
980bb5fd PP |
111 | |
112 | ||
55e06994 | 113 | include::common-lttng-cmd-help-options.txt[] |
980bb5fd PP |
114 | |
115 | ||
55e06994 PP |
116 | include::common-lttng-cmd-after-options.txt[] |
117 | ||
118 | ||
8b40f822 PP |
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 | ||
55e06994 | 143 | include::common-footer.txt[] |
980bb5fd PP |
144 | |
145 | ||
146 | SEE ALSO | |
147 | -------- | |
484b2a0c PP |
148 | man:lttng(1), |
149 | man:lttng-create(1), | |
980bb5fd | 150 | man:lttng-disable-rotation(1), |
21b35b3a PP |
151 | man:lttng-rotate(1), |
152 | man:lttng-concepts(7) |