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