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