lttng-snapshot(1) ================= :revdate: 14 June 2021 NAME ---- lttng-snapshot - Take a snapshot of an LTTng recording session SYNOPSIS -------- Take a recording 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 recording 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 recording session: [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *snapshot* *list-output* [option:--session='SESSION'] Remove the snapshot output from a recording 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 recording session named 'SESSION'. Without the option:--session option:: The current recording session (see man:lttng-concepts(7) to learn more about the current recording session). See man:lttng-concepts(7) to learn more about recording sessions. A _snapshot_ is a dump of the current sub-buffers of all the channels of the selected recording session. When LTTng takes a snapshot, it sends the sub-buffer dump of the selected recording 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 recording session. In other words, different snapshots of the selected recording session can contain the same event records. You must have created the selected recording 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 recording session modes) to use the `snapshot` command. A `snapshot-session` trigger action can also take a recording 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 recording 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 recording session with the man:lttng-start(1) command. ==== [[output]] Snapshot output ~~~~~~~~~~~~~~~ When you take a recording 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 recording session. + Add a snapshot output to a recording session with the `add-output` action. As of LTTng{nbsp}{lttng_version}, you may only add one snapshot output to a given recording session. + When you create a snapshot mode recording 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 recording 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 recording session. Otherwise:: A subdirectory, under the `$LTTNG_HOME/lttng-traces` (`$LTTNG_HOME` defaults to `$HOME`) directory, of which the name contains the recording session name and the date/time. -- + Show the current snapshot output of a recording session with the `list-output` action. + Remove the snapshot output of a recording 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 recording 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 recording session named 'SESSION' instead of the current recording 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 recording session, sending the trace files to its snapshot output. ==== [role="term"] ---- $ lttng snapshot record ---- ==== .Take a snapshot of a specific recording 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 recording 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 recording 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 recording 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)