Error early on invalid tracker type for UST domain
[lttng-tools.git] / doc / man / lttng-snapshot.1.txt
CommitLineData
12397c59
PP
1lttng-snapshot(1)
2=================
4605890e 3:revdate: 9 November 2018
12397c59
PP
4
5
6NAME
7----
8lttng-snapshot - Take LTTng snapshots and configure snapshot outputs
9
10
11SYNOPSIS
12--------
13Add a snapshot output:
14
15[verse]
ce19b9ed 16*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *snapshot add-output* [option:--max-size='SIZE']
12397c59
PP
17 [option:--name='NAME'] [option:--session='SESSION']
18 (option:--ctrl-url='URL' option:--data-url='URL' | 'URL')
19
20Remove a snapshot output:
21
22[verse]
ce19b9ed 23*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *snapshot del-output* [option:--session='SESSION']
12397c59
PP
24 ('ID' | 'NAME')
25
26List current snapshot outputs:
27
28[verse]
ce19b9ed 29*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *snapshot list-output* [option:--session='SESSION']
12397c59
PP
30
31Take a snapshot:
32
33[verse]
ce19b9ed 34*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *snapshot record* [option:--max-size='SIZE']
12397c59
PP
35 [option:--name='NAME'] [option:--session='SESSION']
36 (option:--ctrl-url='URL' option:--data-url='URL' | 'URL')
37
38
39DESCRIPTION
40-----------
41The `lttng snapshot` command manages the snapshot outputs and takes
42snapshots.
43
44A _snapshot_ is a dump of the current sub-buffers of all the channels
45of a given tracing session. When a snapshot is taken, the memory dump
46is sent to the registered snapshot outputs.
47
48The tracing session should be created in _snapshot mode_ to make sure
d539dc89
PP
49that taking snapshots is allowed. This is done at tracing session
50creation time using the man:lttng-create(1) command's
51nloption:--snapshot option.
12397c59
PP
52
53Note that, when a snapshot is taken, the sub-buffers are not cleared.
54This means that different recorded snapshots may contain the same
55events.
56
d539dc89
PP
57If you want, instead, to keep all the trace data, but divide it into
58archived chunks which are then free to process (just like snapshots),
59see the lttng-rotate(1) and lttng-enable-rotation(1) commands. Trace
60chunk archives do not overlap like snapshots can.
61
12397c59
PP
62
63Snapshot outputs
64~~~~~~~~~~~~~~~~
65Snapshot outputs are the destinations of snapshot files when a
66snapshot is taken using the `record` action.
67
68As of this version, only one snapshot output is allowed.
69
70A snapshot output can be added using the `add-output` action. The
71output destination URL is set using either the 'URL' positional
72argument, or both the option:--ctrl-url and option:--data-url options.
7c1a4458 73See man:lttng-create(1) to learn more about the URL format.
12397c59
PP
74
75A name can be assigned to an output when adding it using the
76option:--name option. This name is part of the names of the
77snapshot files written to this output.
78
79By default, the snapshot files can be as big as the sum of the
80sizes of all the sub-buffers or all the channels of the selected
81tracing session. The maximum total size of all the snapshot files can
82be configured using the option:--max-size option.
83
84Snapshot outputs can be listed using the `list-output` action.
85
86Snapshot outputs can be removed using the `del-output` action. The
87configured name can be used when removing an output, or an ID as
88listed by the `list-output` action.
89
90
91Taking a snapshot
92~~~~~~~~~~~~~~~~~
93Taking a snapshot of the current tracing session is as easy as:
94
d25b4989 95[role="term"]
03c5529d
PP
96----
97$ lttng snapshot record
98----
12397c59
PP
99
100This writes the snapshot files to the configured output. It is possible
101to use a custom, unregistered output at record time using the same
102options supported by the `add-output` action.
103
104NOTE: Before taking a snapshot on a system with a high event throughput,
105it is recommended to first run `lttng stop` (see
7c1a4458 106man:lttng-stop(1)). Otherwise, the snapshot could contain "holes",
12397c59
PP
107the result of the tracers overwriting unconsumed trace packets during
108the record operation. After the snapshot is recorded, the tracers can be
7c1a4458 109started again with `lttng start` (see man:lttng-start(1)).
12397c59
PP
110
111
112include::common-cmd-options-head.txt[]
113
114
115Target
116~~~~~~
59b19c3c 117option:-s 'SESSION', option:--session='SESSION'::
12397c59
PP
118 Take a snapshot of the sub-buffers of the channels contained in
119 the tracing session named 'SESSION' instead of the current
120 tracing session.
121
122
123Snapshot output
124~~~~~~~~~~~~~~~
59b19c3c 125option:-C 'URL', option:--ctrl-url='URL'::
12397c59
PP
126 Set control path URL to 'URL' (must use option:--data-url option
127 also).
128
59b19c3c 129option:-D 'URL', option:--data-url='URL'::
12397c59
PP
130 Set data path URL to 'URL' (must use option:--ctrl-url option
131 also).
132
59b19c3c 133option:-m 'SIZE', option:--max-size='SIZE'::
12397c59
PP
134 Limit the total size of all the snapshot files written when
135 recording a snapshot to 'SIZE' bytes. The `k` (kiB), `M` (MiB),
136 and `G` (GiB) suffixes are supported.
137
59b19c3c 138option:-n 'NAME', option:--name='NAME'::
12397c59
PP
139 Assign the name 'NAME' to the snapshot output.
140
141
142include::common-cmd-help-options.txt[]
143
144
145include::common-cmd-footer.txt[]
146
147
148SEE ALSO
149--------
7c1a4458 150man:lttng(1)
This page took 0.03385 seconds and 4 git commands to generate.