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