doc/man: use specific revision date for each manual page
[lttng-tools.git] / doc / man / lttng-rotate.1.txt
1 lttng-rotate(1)
2 ===============
3 :revdate: 18 October 2019
4
5
6 NAME
7 ----
8 lttng-rotate - Archive a tracing session's current trace chunk
9
10
11 SYNOPSIS
12 --------
13 [verse]
14 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *rotate* [option:--no-wait] ['SESSION']
15
16
17 DESCRIPTION
18 -----------
19 The `lttng rotate` command archives the current trace chunk of the
20 current tracing session, or of the tracing session named 'SESSION' if
21 provided, to the file system. This action is called a tracing session
22 _rotation_.
23
24 Once LTTng archives a trace chunk, it does not manage it anymore: you
25 can read it, modify it, move it, or remove it.
26
27 An _archived trace chunk_ is a collection of metadata and data stream
28 files which form a self-contained LTTng trace.
29
30 The _current trace chunk_ of a given tracing session includes:
31
32 * The stream files already written to the file system, and which are
33 not part of a previously archived trace chunk, since the most recent
34 event amongst:
35 ** The first time the tracing session was started with
36 man:lttng-start(1).
37 ** The last rotation, either an immediate one with `lttng rotate`, or an
38 automatic one from a rotation schedule previously set with
39 man:lttng-enable-rotation(1).
40 * The content of all the non-flushed sub-buffers of the tracing
41 session's channels.
42
43 You can use `lttng rotate`:
44
45 * At any time when the tracing session is active (see
46 man:lttng-start(1)).
47 * A single time once the tracing session becomes inactive
48 (see man:lttng-stop(1)).
49
50 By default, the `lttng rotate` command ensures that LTTng finished
51 performing the tracing session rotation before it prints the archived
52 trace chunk's path and exits. The printed path is absolute when the
53 tracing session was created in normal mode and relative to the relay
54 daemon's output directory (see the nloption:--output option in
55 man:lttng-relayd(8)) when it was created in network streaming mode (see
56 man:lttng-create(1)).
57
58 With the option:--no-wait option, the command finishes immediately, so
59 that LTTng might not have completed the rotation when the command exits.
60 In this case, there is no easy way to know when the current trace chunk
61 becomes archived, and the command does not print the archived trace
62 chunk's path.
63
64 Because when LTTng performs a tracing session rotation, it flushes the
65 tracing session's current sub-buffers, archived trace chunks are never
66 redundant, that is, they do not overlap over time like snapshots can
67 (see man:lttng-snapshot(1)). Also, a rotation does not directly cause
68 discarded event records or packets.
69
70 See <<limitations,LIMITATIONS>> for important limitations regarding
71 this command.
72
73
74 Trace chunk archive naming
75 ~~~~~~~~~~~~~~~~~~~~~~~~~~
76 A trace chunk archive is a subdirectory of the `archives` subdirectory
77 within a tracing session's output directory (see the nloption:--output
78 option in man:lttng-create(1) and man:lttng-relayd(8)).
79
80 A trace chunk archive contains, through tracing domain and possibly
81 UID/PID subdirectories, metadata and data stream files.
82
83 A trace chunk archive is, at the same time:
84
85 * A self-contained LTTng trace.
86 * A member of a set of trace chunk archives which form the complete
87 trace of a tracing session.
88
89 In other words, an LTTng trace reader can read both the tracing
90 session output directory (all the trace chunk archives), or a
91 single trace chunk archive.
92
93 When LTTng performs a tracing session rotation, it names the resulting
94 trace chunk archive as such, relative to the tracing session's output
95 directory:
96
97 [verse]
98 archives/__BEGIN__-__END__-__ID__
99
100 __BEGIN__::
101 Date and time of the beginning of the trace chunk archive with
102 the ISO{nbsp}8601-compatible `YYYYmmddTHHMMSS±HHMM` form, where
103 `YYYYmmdd` is the date and `HHMMSS±HHMM` is the time with the
104 time zone offset from UTC.
105 +
106 Example: `20171119T152407-0500`
107
108 __END__::
109 Date and time of the end of the trace chunk archive with
110 the ISO{nbsp}8601-compatible `YYYYmmddTHHMMSS±HHMM` form, where
111 `YYYYmmdd` is the date and `HHMMSS±HHMM` is the time with the
112 time zone offset from UTC.
113 +
114 Example: `20180118T152407+0930`
115
116 __ID__::
117 Unique numeric identifier of the trace chunk within its tracing
118 session.
119
120 Trace chunk archive name example:
121
122 ----
123 archives/20171119T152407-0500-20171119T151422-0500-3
124 ----
125
126
127 include::common-cmd-options-head.txt[]
128
129
130 option:-n, option:--no-wait::
131 Do not ensure that the rotation is done before returning to
132 the prompt.
133
134
135 include::common-cmd-help-options.txt[]
136
137
138 [[limitations]]
139 LIMITATIONS
140 -----------
141 The `lttng rotate` command only works when:
142
143 * The tracing session is created in normal mode or in network streaming
144 mode (see man:lttng-create(1)).
145
146 * No channel was created with a configured trace file count or size
147 limit (see the nloption:--tracefile-size and
148 nloption:--tracefile-count options in man:lttng-enable-channel(1)).
149
150 * No immediate rotation (`lttng rotate`) is currently happening.
151
152
153 include::common-cmd-footer.txt[]
154
155
156 SEE ALSO
157 --------
158 man:lttng-enable-rotation(1),
159 man:lttng-disable-rotation(1),
160 man:lttng(1)
This page took 0.0456 seconds and 4 git commands to generate.