1LTTNG-SNAPSHOT(1) LTTng Manual LTTNG-SNAPSHOT(1)
2
6 lttng-snapshot - Take LTTng snapshots and configure snapshot outputs
7
9 Add a snapshot output:
10 lttng [GENERAL OPTIONS] snapshot add-output [--max-size=SIZE]
12 [--name=NAME] [--session=SESSION]
13 (--ctrl-url=URL --data-url=URL | URL)
14 Remove a snapshot output:
16 lttng [GENERAL OPTIONS] snapshot del-output [--session=SESSION]
18 (ID | NAME)
19 List current snapshot outputs:
21 lttng [GENERAL OPTIONS] snapshot list-output [--session=SESSION]
23 Take a snapshot:
25 lttng [GENERAL OPTIONS] snapshot record [--max-size=SIZE]
27 [--name=NAME] [--session=SESSION]
28 (--ctrl-url=URL --data-url=URL | URL)
29
31 The lttng snapshot command manages the snapshot outputs and takes
32 snapshots.
33 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 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 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 Snapshot outputs
47 Snapshot outputs are the destinations of snapshot files when a snapshot
48 is taken using the record action.
49 As of this version, only one snapshot output is allowed.
51 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 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 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 Snapshot outputs can be listed using the list-output action.
67 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 Taking a snapshot
73 Taking a snapshot of the current tracing session is as easy as:
74 $ lttng snapshot record
76 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 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
90 General options are described in lttng(1).
91 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 Snapshot output
99 -C URL, --ctrl-url=URL
100 Set control path URL to URL (must use --data-url option also).
101 -D URL, --data-url=URL
103 Set data path URL to URL (must use --ctrl-url option also).
104 -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 -n NAME, --name=NAME
111 Assign the name NAME to the snapshot output.
112 Program information
114 -h, --help
115 Show command help.
116 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 --list-options
122 List available command options.
123
125 LTTNG_ABORT_ON_ERROR
126 Set to 1 to abort the process after the first error is encountered.
127 LTTNG_HOME
129 Overrides the $HOME environment variable. Useful when the user
130 running the commands has a non-writable home directory.
131 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 LTTNG_SESSION_CONFIG_XSD_PATH
137 Path in which the session.xsd session configuration XML schema may
138 be found.
139 LTTNG_SESSIOND_PATH
141 Full session daemon binary path.
142 The --sessiond-path option has precedence over this environment
144 variable.
145 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
151 $LTTNG_HOME/.lttngrc
152 User LTTng runtime configuration.
153 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 $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 $LTTNG_HOME/.lttng
164 User LTTng runtime and configuration directory.
165 $LTTNG_HOME/.lttng/sessions
167 Default location of saved user tracing sessions (see lttng-save(1)
168 and lttng-load(1)).
169 /usr/local/etc/lttng/sessions
171 System-wide location of saved tracing sessions (see lttng-save(1)
172 and lttng-load(1)).
173 Note
175 $LTTNG_HOME defaults to $HOME when not explicitly set.
176
178 0
179 Success
180 1
182 Command error
183 2
185 Undefined command
186 3
188 Fatal error
189 4
191 Command warning (something went wrong during the command)
192
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
198 · LTTng project website <http://lttng.org>
199 · LTTng documentation <http://lttng.org/docs>
201 · Git repositories <http://git.lttng.org>
203 · GitHub organization <http://github.com/lttng>
205 · Continuous integration <http://ci.lttng.org/>
207 · Mailing list <http://lists.lttng.org> for support and development:
209 lttng-dev@lists.lttng.org
210 · IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net
212
214 This program is part of the LTTng-tools project.
215 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
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 Also thanks to the Ericsson teams working on tracing which helped us
227 greatly with detailed bug reports and unusual test cases.
228
230 LTTng-tools was originally written by Mathieu Desnoyers, Julien
231 Desfossez, and David Goulet. More people have since contributed to it.
232 LTTng-tools is currently maintained by Jérémie Galarneau
234 <mailto:jeremie.galarneau@efficios.com>.
235
237 lttng(1)
238LTTng 2.10.7 05/24/2019 LTTNG-SNAPSHOT(1)