Commit | Line | Data |
---|---|---|
980bb5fd PP |
1 | lttng-enable-rotation(1) |
2 | ======================== | |
4605890e | 3 | :revdate: 13 November 2018 |
980bb5fd PP |
4 | |
5 | ||
6 | NAME | |
7 | ---- | |
31099add | 8 | lttng-enable-rotation - Set a tracing session's rotation schedule |
980bb5fd PP |
9 | |
10 | ||
11 | SYNOPSIS | |
12 | -------- | |
13 | [verse] | |
eb027cfc PP |
14 | *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-rotation* [option:--session='SESSION'] |
15 | (option:--timer='PERIOD' | option:--size='SIZE' | option:--timer='PERIOD' option:--size='SIZE') | |
980bb5fd PP |
16 | |
17 | ||
18 | DESCRIPTION | |
19 | ----------- | |
31099add PP |
20 | The `lttng enable-rotation` command sets a rotation schedule for the |
21 | current tracing session, or for the tracing session named 'SESSION' if | |
22 | provided. See man:lttng-rotate(1) for more information about the | |
23 | concepts of a tracing session _rotation_ and a _trace chunk_. | |
980bb5fd PP |
24 | |
25 | With the option:--timer option, the rotation schedule is set so that an | |
26 | automatic rotation occurs at least every 'PERIOD' (microseconds without | |
27 | a unit suffix). | |
28 | ||
29 | With the option:--size option, the rotation schedule is set | |
30 | so that an automatic rotation occurs every time the total size of the | |
31 | flushed part of the current trace chunk is at least 'SIZE' (bytes | |
32 | without a unit suffix). | |
33 | ||
17bb414d | 34 | For both option:--timer and option:--size options, LTTng checks the |
980bb5fd | 35 | schedule condition periodically using the monitor timers of the tracing |
437afa71 PP |
36 | session's channels (see the nloption:--monitor-timer option of the |
37 | man:lttng-enable-channel(1) command). This means that: | |
38 | ||
39 | * With the option:--timer option, the automatic rotation can occur when | |
40 | the elapsed time since the last automatic rotation is slightly greater | |
41 | than 'PERIOD'. The exact precision is governed by the monitor timer's | |
42 | precision, which relies on the precision of the platform's | |
43 | implementation of POSIX timers. | |
44 | ||
45 | * With the option:--size option, the automatic rotation can occur when | |
46 | the size of the flushed part of the current trace chunk is greater | |
47 | than 'SIZE'. | |
980bb5fd | 48 | |
eb027cfc PP |
49 | You can combine the option:--timer and option:--size options. |
50 | ||
980bb5fd | 51 | The naming convention of a trace chunk archive which an automatic |
31099add | 52 | rotation creates is the same as with the immediate rotation command, |
980bb5fd PP |
53 | man:lttng-rotate(1). |
54 | ||
31099add PP |
55 | You can unset a rotation schedule with the man:lttng-disable-rotation(1) |
56 | command. | |
980bb5fd PP |
57 | |
58 | See <<limitations,LIMITATIONS>> for important limitations regarding | |
59 | this command. | |
60 | ||
61 | ||
62 | include::common-cmd-options-head.txt[] | |
63 | ||
64 | ||
31099add PP |
65 | Rotation schedule condition |
66 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
980bb5fd | 67 | option:--size='SIZE':: |
31099add PP |
68 | Set a rotation schedule so that an automatic rotation occurs every |
69 | time the total size of the flushed part of the current trace chunk | |
70 | is at least 'SIZE' bytes. The `k` (kiB), `M` (MiB), and `G` (GiB) | |
71 | suffixes are supported. | |
980bb5fd PP |
72 | |
73 | option:--timer='PERIOD':: | |
31099add PP |
74 | Set a rotation schedule so that an automatic rotation occurs at |
75 | least every 'PERIOD' microseconds. The `ms` (milliseconds), `s` | |
76 | (seconds), `m` (minutes), and `h` (hours) suffixes are supported. | |
980bb5fd PP |
77 | |
78 | ||
79 | Target | |
80 | ~~~~~~ | |
81 | option:-s 'SESSION', option:--session='SESSION':: | |
31099add PP |
82 | Set a rotation schedule for the tracing session named 'SESSION' |
83 | instead of the current tracing session. | |
980bb5fd PP |
84 | |
85 | ||
86 | include::common-cmd-help-options.txt[] | |
87 | ||
88 | ||
89 | [[limitations]] | |
90 | LIMITATIONS | |
91 | ----------- | |
92 | The `lttng enable-rotation` command only works when: | |
93 | ||
94 | * The tracing session is created in normal mode or in network streaming | |
95 | mode (see man:lttng-create(1)). | |
96 | ||
97 | * No channel was created with a configured trace file count or size | |
98 | limit (see the nloption:--tracefile-size and | |
99 | nloption:--tracefile-count options in man:lttng-enable-channel(1)). | |
100 | ||
101 | For a given tracing session, LTTng only performs an automatic rotation | |
102 | when no other rotation is currently happening. | |
103 | ||
104 | ||
105 | include::common-cmd-footer.txt[] | |
106 | ||
107 | ||
108 | SEE ALSO | |
109 | -------- | |
110 | man:lttng-rotate(1), | |
111 | man:lttng-disable-rotation(1), | |
112 | man:lttng(1) |