scope-exit: Clarify scope_exit noexcept requirement
[lttng-tools.git] / doc / man / lttng-snapshot.1.txt
CommitLineData
12397c59
PP
1lttng-snapshot(1)
2=================
e9711845 3:revdate: 14 June 2021
12397c59
PP
4
5
6NAME
7----
e9711845 8lttng-snapshot - Take a snapshot of an LTTng recording session
12397c59
PP
9
10
11SYNOPSIS
12--------
e9711845 13Take a recording session snapshot:
12397c59
PP
14
15[verse]
26f0c779 16*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *snapshot* *record* [option:--max-size='SIZE']
12397c59 17 [option:--name='NAME'] [option:--session='SESSION']
26f0c779 18 [option:--ctrl-url='URL' option:--data-url='URL' | 'URL']
12397c59 19
e9711845 20Add a snapshot output to a recording session:
12397c59
PP
21
22[verse]
26f0c779
PP
23*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *snapshot* *add-output* [option:--max-size='SIZE']
24 [option:--name='NAME'] [option:--session='SESSION']
25 (option:--ctrl-url='URL' option:--data-url='URL' | 'URL')
12397c59 26
e9711845 27Show the snapshot output of a recording session:
12397c59
PP
28
29[verse]
26f0c779 30*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *snapshot* *list-output* [option:--session='SESSION']
12397c59 31
e9711845 32Remove the snapshot output from a recording session:
12397c59
PP
33
34[verse]
26f0c779 35*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *snapshot* *del-output* [option:--session='SESSION'] *1*
12397c59
PP
36
37
38DESCRIPTION
39-----------
26f0c779
PP
40The `lttng snapshot` command can take a snapshot of, add or remove a
41snapshot output, and show the snapshot output of:
12397c59 42
26f0c779 43With the option:--session='SESSION' option::
e9711845 44 The recording session named 'SESSION'.
12397c59 45
26f0c779 46Without the option:--session option::
e9711845
PP
47 The current recording session (see man:lttng-concepts(7) to learn more
48 about the current recording session).
12397c59 49
e9711845 50See man:lttng-concepts(7) to learn more about recording sessions.
12397c59 51
26f0c779 52A _snapshot_ is a dump of the current sub-buffers of all the channels of
e9711845 53the selected recording session.
12397c59 54
26f0c779 55When LTTng takes a snapshot, it sends the sub-buffer dump of the
e9711845
PP
56selected recording session to the local file system or over the network
57to a listening relay daemon (man:lttng-relayd(8)). See the
da39b67c 58``<<output,Snapshot output>>'' section below to learn more.
12397c59 59
26f0c779 60When LTTng takes a snapshot, it does :not: clear the sub-buffers of the
e9711845
PP
61selected recording session. In other words, different snapshots of the
62selected recording session can contain the same event records.
12397c59 63
e9711845
PP
64You must have created the selected recording session in snapshot mode
65(see the nloption:--snapshot option of the man:lttng-create(1) command
66as well as man:lttng-concepts(7) to learn more about recording session
67modes) to use the `snapshot` command.
12397c59 68
e9711845 69A `snapshot-session` trigger action can also take a recording session
26f0c779 70snapshot (see man:lttng-add-trigger(1)).
12397c59 71
da39b67c 72See the ``<<examples,EXAMPLES>>'' section below for usage examples.
f0197e11 73
26f0c779
PP
74If you want, instead, to keep all the trace data, but divide it into
75archived chunks which are then, like snapshots, ready to be processed,
e9711845
PP
76see the recording session rotation feature in man:lttng-concepts(7).
77Trace chunk archives do :not: overlap like snapshots can.
12397c59 78
26f0c779
PP
79[NOTE]
80====
81Before you take a snapshot on a system with a high event throughput, the
82LTTng project recommends that you first run the man:lttng-stop(1)
83command. Otherwise, the snapshot could contain ``holes'', the result of
84the tracers overwriting unconsumed trace packets during the snapshot
85operation.
12397c59 86
e9711845
PP
87After LTTng writes the snapshot trace data, you can restart the
88recording session with the man:lttng-start(1) command.
26f0c779 89====
12397c59 90
12397c59 91
26f0c779
PP
92[[output]]
93Snapshot output
94~~~~~~~~~~~~~~~
e9711845 95When you take a recording session snapshot with the `record` action, LTTng
26f0c779
PP
96writes the snapshot trace files to:
97
98If you specify the 'URL' non-option argument or the option:--ctrl-url and option:--data-url options::
99 The output defined by the 'URL' non-option argument or by the
100 arguments of the options.
101+
102See man:lttng-create(1) for the format of 'URL'.
103
104Otherwise::
e9711845 105 The snapshot output of the selected recording session.
26f0c779 106+
e9711845
PP
107Add a snapshot output to a recording session with the `add-output`
108action. As of LTTng{nbsp}{lttng_version}, you may only add one snapshot
109output to a given recording session.
26f0c779 110+
e9711845 111When you create a snapshot mode recording session with the
26f0c779
PP
112nloption:--snapshot option of the man:lttng-create(1) command, and
113without its nloption:--no-output option, the `create` command
114automatically adds a snapshot output named `snapshot-1` to the created
e9711845 115recording session:
26f0c779
PP
116+
117--
118With its nloption:--output, nloption:--set-url, nloption:--ctrl-url, or nloption:--data-url options::
119 Equivalent to using the `add-output` action with the provided or
e9711845 120 equivalent URL(s) immediately after creating the recording session.
26f0c779
PP
121
122Otherwise::
123 A subdirectory, under the `$LTTNG_HOME/lttng-traces` (`$LTTNG_HOME`
124 defaults to `$HOME`) directory, of which the name contains the
e9711845 125 recording session name and the date/time.
26f0c779
PP
126--
127+
e9711845 128Show the current snapshot output of a recording session with the
26f0c779
PP
129`list-output` action.
130+
e9711845 131Remove the snapshot output of a recording session with the
26f0c779
PP
132`del-output` action.
133
134For both the `record` and `add-output` actions:
135
136* Assign a name to a snapshot output with the option:--name='NAME'
137 option.
138+
139'NAME' becomes part of the snapshot trace file names which LTTng sends
140to this output.
141
142* By default, the snapshot files can be as big as the sum of the sizes
e9711845 143 of all the sub-buffers of all the channels of the selected recording
26f0c779
PP
144 session.
145+
146Set the maximum total size of all the snapshot trace files LTTng writes
147with the option:--max-size option.
12397c59
PP
148
149
f5511eea 150include::common-lttng-cmd-options-head.txt[]
12397c59
PP
151
152
26f0c779
PP
153Recording target
154~~~~~~~~~~~~~~~~
59b19c3c 155option:-s 'SESSION', option:--session='SESSION'::
e9711845
PP
156 Take a snapshot of the sub-buffers of the recording session named
157 'SESSION' instead of the current recording session.
12397c59
PP
158
159
26f0c779
PP
160Output
161~~~~~~
da39b67c 162See the ``<<output,Snapshot output>>'' section above.
26f0c779 163
59b19c3c 164option:-C 'URL', option:--ctrl-url='URL'::
26f0c779
PP
165 Set the control path URL to 'URL'.
166+
167You must also use the option:--data-url option.
168+
169See man:lttng-create(1) for the format of 'URL'.
12397c59 170
59b19c3c 171option:-D 'URL', option:--data-url='URL'::
26f0c779
PP
172 Set the trace data path URL to 'URL'.
173+
174You must also use the option:--ctrl-url option.
175+
176See man:lttng-create(1) for the format of 'URL'.
12397c59 177
59b19c3c 178option:-m 'SIZE', option:--max-size='SIZE'::
26f0c779
PP
179 Set the maximum total size of all the snapshot trace files LTTng
180 writes when taking a snapshot to 'SIZE' bytes.
181+
182The `k`{nbsp}(KiB), `M`{nbsp}(MiB), and `G`{nbsp}(GiB) suffixes are
183supported.
12397c59 184
59b19c3c 185option:-n 'NAME', option:--name='NAME'::
12397c59
PP
186 Assign the name 'NAME' to the snapshot output.
187
188
f5511eea 189include::common-lttng-cmd-help-options.txt[]
12397c59
PP
190
191
f5511eea
PP
192include::common-lttng-cmd-after-options.txt[]
193
194
f0197e11
PP
195[[examples]]
196EXAMPLES
197--------
e9711845 198.Take a snapshot of the current recording session, sending the trace files to its snapshot output.
f0197e11
PP
199====
200[role="term"]
201----
202$ lttng snapshot record
203----
204====
205
e9711845 206.Take a snapshot of a specific recording session, giving it a custom name.
f0197e11
PP
207====
208See the option:--session and option:--name options.
209
210[role="term"]
211----
212$ lttng snapshot record --session=my-session --name=SNAP
213----
214====
215
e9711845 216.Take a snapshot of the current recording session, sending the trace files to a custom location.
f0197e11
PP
217====
218See the ``Output directory'' section of man:lttng-relayd(8) to
219understand where the relay daemon to connect to (`3.96.87.215`) writes
220the received traces.
221
222[role="term"]
223----
224$ lttng snapshot record net://3.96.87.215
225----
226====
227
e9711845 228.Replace the snapshot output of a specific recording session with a local file system path.
f0197e11
PP
229====
230See the option:--session option.
231
232[role="term"]
233----
234$ lttng snapshot del-output --session=monk 1
235$ lttng snapshot add-output --session=monk \
236 file:///path/to/snapshots
237----
238====
239
e9711845 240.Take a snapshot of the current recording session, making sure its size is not over 4{nbsp}MiB.
f0197e11
PP
241====
242See the option:--max-size option.
243
244[role="term"]
245----
246$ lttng snapshot record --max-size=4M
247----
248====
249
250
f5511eea 251include::common-footer.txt[]
12397c59
PP
252
253
254SEE ALSO
255--------
26f0c779 256man:lttng(1),
af1c4164
PP
257man:lttng-create(1),
258man:lttng-concepts(7)
This page took 0.059544 seconds and 5 git commands to generate.