lttng-snapshot(1) ================= :revdate: 17 May 2021 NAME ---- lttng-snapshot - Take a snapshot of an LTTng tracing session SYNOPSIS -------- Take a tracing session snapshot: [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *snapshot* *record* [option:--max-size='SIZE'] [option:--name='NAME'] [option:--session='SESSION'] [option:--ctrl-url='URL' option:--data-url='URL' | 'URL'] Add a snapshot output to a tracing session: [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *snapshot* *add-output* [option:--max-size='SIZE'] [option:--name='NAME'] [option:--session='SESSION'] (option:--ctrl-url='URL' option:--data-url='URL' | 'URL') Show the snapshot output of a tracing session: [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *snapshot* *list-output* [option:--session='SESSION'] Remove the snapshot output from a tracing session: [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *snapshot* *del-output* [option:--session='SESSION'] *1* DESCRIPTION ----------- The `lttng snapshot` command can take a snapshot of, add or remove a snapshot output, and show the snapshot output of: With the option:--session='SESSION' option:: The tracing session named 'SESSION'. Without the option:--session option:: The current tracing session (see man:lttng-concepts(7) to learn more about the current tracing session). See man:lttng-concepts(7) to learn more about tracing sessions. A _snapshot_ is a dump of the current sub-buffers of all the channels of the selected tracing session. When LTTng takes a snapshot, it sends the sub-buffer dump of the selected tracing session to the local file system or over the network to a listening relay daemon (man:lttng-relayd(8)). See the <> section below to learn more. When LTTng takes a snapshot, it does :not: clear the sub-buffers of the selected tracing session. In other words, different snapshots of the selected tracing session can contain the same event records. You must have created the selected tracing session in snapshot mode (see the nloption:--snapshot option of the man:lttng-create(1) command as well as man:lttng-concepts(7) to learn more about tracing session modes) to use the `snapshot` command. A `snapshot-session` trigger action can also take a tracing session snapshot (see man:lttng-add-trigger(1)). See the <> section below for usage examples. If you want, instead, to keep all the trace data, but divide it into archived chunks which are then, like snapshots, ready to be processed, see the tracing session rotation feature in man:lttng-concepts(7). Trace chunk archives do :not: overlap like snapshots can. [NOTE] ==== Before you take a snapshot on a system with a high event throughput, the LTTng project recommends that you first run the man:lttng-stop(1) command. Otherwise, the snapshot could contain ``holes'', the result of the tracers overwriting unconsumed trace packets during the snapshot operation. After LTTng writes the snapshot trace data, you can restart the tracing session with the man:lttng-start(1) command. ==== [[output]] Snapshot output ~~~~~~~~~~~~~~~ When you take a tracing session snapshot with the `record` action, LTTng writes the snapshot trace files to: If you specify the 'URL' non-option argument or the option:--ctrl-url and option:--data-url options:: The output defined by the 'URL' non-option argument or by the arguments of the options. + See man:lttng-create(1) for the format of 'URL'. Otherwise:: The snapshot output of the selected tracing session. + Add a snapshot output to a tracing session with the `add-output` action. As of LTTng{nbsp}{lttng_version}, you may only add one snapshot output to a given tracing session. + When you create a snapshot mode tracing session with the nloption:--snapshot option of the man:lttng-create(1) command, and without its nloption:--no-output option, the `create` command automatically adds a snapshot output named `snapshot-1` to the created tracing session: + -- With its nloption:--output, nloption:--set-url, nloption:--ctrl-url, or nloption:--data-url options:: Equivalent to using the `add-output` action with the provided or equivalent URL(s) immediately after creating the tracing session. Otherwise:: A subdirectory, under the `$LTTNG_HOME/lttng-traces` (`$LTTNG_HOME` defaults to `$HOME`) directory, of which the name contains the tracing session name and the date/time. -- + Show the current snapshot output of a tracing session with the `list-output` action. + Remove the snapshot output of a tracing session with the `del-output` action. For both the `record` and `add-output` actions: * Assign a name to a snapshot output with the option:--name='NAME' option. + 'NAME' becomes part of the snapshot trace file names which LTTng sends to this output. * By default, the snapshot files can be as big as the sum of the sizes of all the sub-buffers of all the channels of the selected tracing session. + Set the maximum total size of all the snapshot trace files LTTng writes with the option:--max-size option. include::common-lttng-cmd-options-head.txt[] Recording target ~~~~~~~~~~~~~~~~ option:-s 'SESSION', option:--session='SESSION':: Take a snapshot of the sub-buffers of the tracing session named 'SESSION' instead of the current tracing session. Output ~~~~~~ See the <> section above. option:-C 'URL', option:--ctrl-url='URL':: Set the control path URL to 'URL'. + You must also use the option:--data-url option. + See man:lttng-create(1) for the format of 'URL'. option:-D 'URL', option:--data-url='URL':: Set the trace data path URL to 'URL'. + You must also use the option:--ctrl-url option. + See man:lttng-create(1) for the format of 'URL'. option:-m 'SIZE', option:--max-size='SIZE':: Set the maximum total size of all the snapshot trace files LTTng writes when taking a snapshot to 'SIZE' bytes. + The `k`{nbsp}(KiB), `M`{nbsp}(MiB), and `G`{nbsp}(GiB) suffixes are supported. option:-n 'NAME', option:--name='NAME':: Assign the name 'NAME' to the snapshot output. include::common-lttng-cmd-help-options.txt[] include::common-lttng-cmd-after-options.txt[] [[examples]] EXAMPLES -------- .Take a snapshot of the current tracing session, sending the trace files to its snapshot output. ==== [role="term"] ---- $ lttng snapshot record ---- ==== .Take a snapshot of a specific tracing session, giving it a custom name. ==== See the option:--session and option:--name options. [role="term"] ---- $ lttng snapshot record --session=my-session --name=SNAP ---- ==== .Take a snapshot of the current tracing session, sending the trace files to a custom location. ==== See the ``Output directory'' section of man:lttng-relayd(8) to understand where the relay daemon to connect to (`3.96.87.215`) writes the received traces. [role="term"] ---- $ lttng snapshot record net://3.96.87.215 ---- ==== .Replace the snapshot output of a specific tracing session with a local file system path. ==== See the option:--session option. [role="term"] ---- $ lttng snapshot del-output --session=monk 1 $ lttng snapshot add-output --session=monk \ file:///path/to/snapshots ---- ==== .Take a snapshot of the current tracing session, making sure its size is not over 4{nbsp}MiB. ==== See the option:--max-size option. [role="term"] ---- $ lttng snapshot record --max-size=4M ---- ==== include::common-footer.txt[] SEE ALSO -------- man:lttng(1), man:lttng-create(1), man:lttng-concepts(7)