1LTTNG-SNAPSHOT(1)                LTTng Manual                LTTNG-SNAPSHOT(1)
2
3
4

NAME

6       lttng-snapshot - Take LTTng snapshots and configure snapshot outputs
7

SYNOPSIS

9       Add a snapshot output:
10
11       lttng [GENERAL OPTIONS] snapshot add-output [--max-size=SIZE]
12             [--name=NAME] [--session=SESSION]
13             (--ctrl-url=URL --data-url=URL | URL)
14
15       Remove a snapshot output:
16
17       lttng [GENERAL OPTIONS] snapshot del-output [--session=SESSION]
18             (ID | NAME)
19
20       List current snapshot outputs:
21
22       lttng [GENERAL OPTIONS] snapshot list-output [--session=SESSION]
23
24       Take a snapshot:
25
26       lttng [GENERAL OPTIONS] snapshot record [--max-size=SIZE]
27             [--name=NAME] [--session=SESSION]
28             (--ctrl-url=URL --data-url=URL | URL)
29

DESCRIPTION

31       The lttng snapshot command manages the snapshot outputs and takes
32       snapshots.
33
34       A snapshot is a dump of the current sub-buffers of all the channels of
35       a given tracing session. When a snapshot is taken, the memory dump is
36       sent to the registered snapshot outputs.
37
38       The tracing session should be created in snapshot mode to make sure
39       taking snapshots is allowed. This is done at tracing session creation
40       time using the lttng-create(1) command.
41
42       Note that, when a snapshot is taken, the sub-buffers are not cleared.
43       This means that different recorded snapshots may contain the same
44       events.
45
46   Snapshot outputs
47       Snapshot outputs are the destinations of snapshot files when a snapshot
48       is taken using the record action.
49
50       As of this version, only one snapshot output is allowed.
51
52       A snapshot output can be added using the add-output action. The output
53       destination URL is set using either the URL positional argument, or
54       both the --ctrl-url and --data-url options. See lttng-create(1) to
55       learn more about the URL format.
56
57       A name can be assigned to an output when adding it using the --name
58       option. This name is part of the names of the snapshot files written to
59       this output.
60
61       By default, the snapshot files can be as big as the sum of the sizes of
62       all the sub-buffers or all the channels of the selected tracing
63       session. The maximum total size of all the snapshot files can be
64       configured using the --max-size option.
65
66       Snapshot outputs can be listed using the list-output action.
67
68       Snapshot outputs can be removed using the del-output action. The
69       configured name can be used when removing an output, or an ID as listed
70       by the list-output action.
71
72   Taking a snapshot
73       Taking a snapshot of the current tracing session is as easy as:
74
75           $ lttng snapshot record
76
77       This writes the snapshot files to the configured output. It is possible
78       to use a custom, unregistered output at record time using the same
79       options supported by the add-output action.
80
81           Note
82           Before taking a snapshot on a system with a high event throughput,
83           it is recommended to first run lttng stop (see lttng-stop(1)).
84           Otherwise, the snapshot could contain "holes", the result of the
85           tracers overwriting unconsumed trace packets during the record
86           operation. After the snapshot is recorded, the tracers can be
87           started again with lttng start (see lttng-start(1)).
88

OPTIONS

90       General options are described in lttng(1).
91
92   Target
93       -s SESSION, --session=SESSION
94           Take a snapshot of the sub-buffers of the channels contained in the
95           tracing session named SESSION instead of the current tracing
96           session.
97
98   Snapshot output
99       -C URL, --ctrl-url=URL
100           Set control path URL to URL (must use --data-url option also).
101
102       -D URL, --data-url=URL
103           Set data path URL to URL (must use --ctrl-url option also).
104
105       -m SIZE, --max-size=SIZE
106           Limit the total size of all the snapshot files written when
107           recording a snapshot to SIZE bytes. The k (kiB), M (MiB), and G
108           (GiB) suffixes are supported.
109
110       -n NAME, --name=NAME
111           Assign the name NAME to the snapshot output.
112
113   Program information
114       -h, --help
115           Show command help.
116
117           This option, like lttng-help(1), attempts to launch /usr/bin/man to
118           view the command’s man page. The path to the man pager can be
119           overridden by the LTTNG_MAN_BIN_PATH environment variable.
120
121       --list-options
122           List available command options.
123

ENVIRONMENT VARIABLES

125       LTTNG_ABORT_ON_ERROR
126           Set to 1 to abort the process after the first error is encountered.
127
128       LTTNG_HOME
129           Overrides the $HOME environment variable. Useful when the user
130           running the commands has a non-writable home directory.
131
132       LTTNG_MAN_BIN_PATH
133           Absolute path to the man pager to use for viewing help information
134           about LTTng commands (using lttng-help(1) or lttng COMMAND --help).
135
136       LTTNG_SESSION_CONFIG_XSD_PATH
137           Path in which the session.xsd session configuration XML schema may
138           be found.
139
140       LTTNG_SESSIOND_PATH
141           Full session daemon binary path.
142
143           The --sessiond-path option has precedence over this environment
144           variable.
145
146       Note that the lttng-create(1) command can spawn an LTTng session daemon
147       automatically if none is running. See lttng-sessiond(8) for the
148       environment variables influencing the execution of the session daemon.
149

FILES

151       $LTTNG_HOME/.lttngrc
152           User LTTng runtime configuration.
153
154           This is where the per-user current tracing session is stored
155           between executions of lttng(1). The current tracing session can be
156           set with lttng-set-session(1). See lttng-create(1) for more
157           information about tracing sessions.
158
159       $LTTNG_HOME/lttng-traces
160           Default output directory of LTTng traces. This can be overridden
161           with the --output option of the lttng-create(1) command.
162
163       $LTTNG_HOME/.lttng
164           User LTTng runtime and configuration directory.
165
166       $LTTNG_HOME/.lttng/sessions
167           Default location of saved user tracing sessions (see lttng-save(1)
168           and lttng-load(1)).
169
170       /usr/local/etc/lttng/sessions
171           System-wide location of saved tracing sessions (see lttng-save(1)
172           and lttng-load(1)).
173
174           Note
175           $LTTNG_HOME defaults to $HOME when not explicitly set.
176

EXIT STATUS

178       0
179           Success
180
181       1
182           Command error
183
184       2
185           Undefined command
186
187       3
188           Fatal error
189
190       4
191           Command warning (something went wrong during the command)
192

BUGS

194       If you encounter any issue or usability problem, please report it on
195       the LTTng bug tracker <https://bugs.lttng.org/projects/lttng-tools>.
196

RESOURCES

198       ·   LTTng project website <http://lttng.org>
199
200       ·   LTTng documentation <http://lttng.org/docs>
201
202       ·   Git repositories <http://git.lttng.org>
203
204       ·   GitHub organization <http://github.com/lttng>
205
206       ·   Continuous integration <http://ci.lttng.org/>
207
208       ·   Mailing list <http://lists.lttng.org> for support and development:
209           lttng-dev@lists.lttng.org
210
211       ·   IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net
212

COPYRIGHTS

214       This program is part of the LTTng-tools project.
215
216       LTTng-tools is distributed under the GNU General Public License version
217       2 <http://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html>. See the
218       LICENSE <https://github.com/lttng/lttng-tools/blob/master/LICENSE> file
219       for details.
220

THANKS

222       Special thanks to Michel Dagenais and the DORSAL laboratory
223       <http://www.dorsal.polymtl.ca/> at École Polytechnique de Montréal for
224       the LTTng journey.
225
226       Also thanks to the Ericsson teams working on tracing which helped us
227       greatly with detailed bug reports and unusual test cases.
228

AUTHORS

230       LTTng-tools was originally written by Mathieu Desnoyers, Julien
231       Desfossez, and David Goulet. More people have since contributed to it.
232
233       LTTng-tools is currently maintained by Jérémie Galarneau
234       <mailto:jeremie.galarneau@efficios.com>.
235

SEE ALSO

237       lttng(1)
238
239
240
241LTTng 2.10.5                      07/24/2018                 LTTNG-SNAPSHOT(1)
Impressum