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 that taking snapshots is allowed. This is done at tracing session
40 creation time using the lttng-create(1) command’s --snapshot option.
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 If you want, instead, to keep all the trace data, but divide it into
47 archived chunks which are then free to process (just like snapshots),
48 see the lttng-rotate(1) and lttng-enable-rotation(1) commands. Trace
49 chunk archives do not overlap like snapshots can.
50 Snapshot outputs
52 Snapshot outputs are the destinations of snapshot files when a snapshot
53 is taken using the record action.
54 As of this version, only one snapshot output is allowed.
56 A snapshot output can be added using the add-output action. The output
58 destination URL is set using either the URL positional argument, or
59 both the --ctrl-url and --data-url options. See lttng-create(1) to
60 learn more about the URL format.
61 A name can be assigned to an output when adding it using the --name
63 option. This name is part of the names of the snapshot files written to
64 this output.
65 By default, the snapshot files can be as big as the sum of the sizes of
67 all the sub-buffers or all the channels of the selected tracing
68 session. The maximum total size of all the snapshot files can be
69 configured using the --max-size option.
70 Snapshot outputs can be listed using the list-output action.
72 Snapshot outputs can be removed using the del-output action. The
74 configured name can be used when removing an output, or an ID as listed
75 by the list-output action.
76 Taking a snapshot
78 Taking a snapshot of the current tracing session is as easy as:
79 $ lttng snapshot record
81 This writes the snapshot files to the configured output. It is possible
83 to use a custom, unregistered output at record time using the same
84 options supported by the add-output action.
85 Note
87 Before taking a snapshot on a system with a high event throughput,
88 it is recommended to first run lttng stop (see lttng-stop(1)).
89 Otherwise, the snapshot could contain "holes", the result of the
90 tracers overwriting unconsumed trace packets during the record
91 operation. After the snapshot is recorded, the tracers can be
92 started again with lttng start (see lttng-start(1)).
93
95 General options are described in lttng(1).
96 Target
98 -s SESSION, --session=SESSION
99 Take a snapshot of the sub-buffers of the channels contained in the
100 tracing session named SESSION instead of the current tracing
101 session.
102 Snapshot output
104 -C URL, --ctrl-url=URL
105 Set control path URL to URL (must use --data-url option also).
106 -D URL, --data-url=URL
108 Set data path URL to URL (must use --ctrl-url option also).
109 -m SIZE, --max-size=SIZE
111 Limit the total size of all the snapshot files written when
112 recording a snapshot to SIZE bytes. The k (kiB), M (MiB), and G
113 (GiB) suffixes are supported.
114 -n NAME, --name=NAME
116 Assign the name NAME to the snapshot output.
117 Program information
119 -h, --help
120 Show command help.
121 This option, like lttng-help(1), attempts to launch /usr/bin/man to
123 view the command’s man page. The path to the man pager can be
124 overridden by the LTTNG_MAN_BIN_PATH environment variable.
125 --list-options
127 List available command options.
128
130 LTTNG_ABORT_ON_ERROR
131 Set to 1 to abort the process after the first error is encountered.
132 LTTNG_HOME
134 Overrides the $HOME environment variable. Useful when the user
135 running the commands has a non-writable home directory.
136 LTTNG_MAN_BIN_PATH
138 Absolute path to the man pager to use for viewing help information
139 about LTTng commands (using lttng-help(1) or lttng COMMAND --help).
140 LTTNG_SESSION_CONFIG_XSD_PATH
142 Path in which the session.xsd session configuration XML schema may
143 be found.
144 LTTNG_SESSIOND_PATH
146 Full session daemon binary path.
147 The --sessiond-path option has precedence over this environment
149 variable.
150 Note that the lttng-create(1) command can spawn an LTTng session daemon
152 automatically if none is running. See lttng-sessiond(8) for the
153 environment variables influencing the execution of the session daemon.
154
156 $LTTNG_HOME/.lttngrc
157 User LTTng runtime configuration.
158 This is where the per-user current tracing session is stored
160 between executions of lttng(1). The current tracing session can be
161 set with lttng-set-session(1). See lttng-create(1) for more
162 information about tracing sessions.
163 $LTTNG_HOME/lttng-traces
165 Default output directory of LTTng traces. This can be overridden
166 with the --output option of the lttng-create(1) command.
167 $LTTNG_HOME/.lttng
169 User LTTng runtime and configuration directory.
170 $LTTNG_HOME/.lttng/sessions
172 Default location of saved user tracing sessions (see lttng-save(1)
173 and lttng-load(1)).
174 /usr/local/etc/lttng/sessions
176 System-wide location of saved tracing sessions (see lttng-save(1)
177 and lttng-load(1)).
178 Note
180 $LTTNG_HOME defaults to $HOME when not explicitly set.
181
183 0
184 Success
185 1
187 Command error
188 2
190 Undefined command
191 3
193 Fatal error
194 4
196 Command warning (something went wrong during the command)
197
199 If you encounter any issue or usability problem, please report it on
200 the LTTng bug tracker <https://bugs.lttng.org/projects/lttng-tools>.
201
203 · LTTng project website <https://lttng.org>
204 · LTTng documentation <https://lttng.org/docs>
206 · Git repositories <http://git.lttng.org>
208 · GitHub organization <http://github.com/lttng>
210 · Continuous integration <http://ci.lttng.org/>
212 · Mailing list <http://lists.lttng.org> for support and development:
214 lttng-dev@lists.lttng.org
215 · IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net
217
219 This program is part of the LTTng-tools project.
220 LTTng-tools is distributed under the GNU General Public License version
222 2 <http://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html>. See the
223 LICENSE <https://github.com/lttng/lttng-tools/blob/master/LICENSE> file
224 for details.
225
227 Special thanks to Michel Dagenais and the DORSAL laboratory
228 <http://www.dorsal.polymtl.ca/> at École Polytechnique de Montréal for
229 the LTTng journey.
230 Also thanks to the Ericsson teams working on tracing which helped us
232 greatly with detailed bug reports and unusual test cases.
233
235 lttng(1)
236LTTng 2.12.2 9 November 2018 LTTNG-SNAPSHOT(1)