X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;f=doc%2Fman%2Flttng-snapshot.1.txt;h=1cf522f1d2029940547c3073266b18f579b967ae;hb=refs%2Fheads%2Fsow-2021-0002-rev1;hp=a749e1c02e99629945da9a76631459e1a65fd0f1;hpb=59b19c3c82a824b602b4e3cd70e1cb22448fcb9d;p=lttng-tools.git diff --git a/doc/man/lttng-snapshot.1.txt b/doc/man/lttng-snapshot.1.txt index a749e1c02..1cf522f1d 100644 --- a/doc/man/lttng-snapshot.1.txt +++ b/doc/man/lttng-snapshot.1.txt @@ -1,142 +1,258 @@ lttng-snapshot(1) ================= +:revdate: 14 June 2021 NAME ---- -lttng-snapshot - Take LTTng snapshots and configure snapshot outputs +lttng-snapshot - Take a snapshot of an LTTng recording session SYNOPSIS -------- -Add a snapshot output: +Take a recording session snapshot: [verse] -*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *snapshot add-output* [option:--max-size='SIZE'] +*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') + [option:--ctrl-url='URL' option:--data-url='URL' | 'URL'] -Remove a snapshot output: +Add a snapshot output to a recording session: [verse] -*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *snapshot del-output* [option:--session='SESSION'] - ('ID' | 'NAME') +*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') -List current snapshot outputs: +Show the snapshot output of a recording session: [verse] -*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *snapshot list-output* [option:--session='SESSION'] +*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *snapshot* *list-output* [option:--session='SESSION'] -Take a snapshot: +Remove the snapshot output from a recording session: [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') +*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *snapshot* *del-output* [option:--session='SESSION'] *1* DESCRIPTION ----------- -The `lttng snapshot` command manages the snapshot outputs and takes -snapshots. +The `lttng snapshot` command can take a snapshot of, add or remove a +snapshot output, and show the snapshot output of: -A _snapshot_ is a dump of the current sub-buffers of all the channels -of a given tracing session. When a snapshot is taken, the memory dump -is sent to the registered snapshot outputs. +With the option:--session='SESSION' option:: + The recording session named 'SESSION'. -The tracing session should be created in _snapshot mode_ to make sure -taking snapshots is allowed. This is done at tracing session creation -time using the man:lttng-create(1) command. +Without the option:--session option:: + The current recording session (see man:lttng-concepts(7) to learn more + about the current recording session). -Note that, when a snapshot is taken, the sub-buffers are not cleared. -This means that different recorded snapshots may contain the same -events. +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. -Snapshot outputs -~~~~~~~~~~~~~~~~ -Snapshot outputs are the destinations of snapshot files when a -snapshot is taken using the `record` action. +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. -As of this version, only one snapshot output is allowed. +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. -A snapshot output can be added using the `add-output` action. The -output destination URL is set using either the 'URL' positional -argument, or both the option:--ctrl-url and option:--data-url options. -See man:lttng-create(1) to learn more about the URL format. +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 name can be assigned to an output when adding it using the -option:--name option. This name is part of the names of the -snapshot files written to this output. +A `snapshot-session` trigger action can also take a recording session +snapshot (see man:lttng-add-trigger(1)). -By default, the snapshot files can be as big as the sum of the -sizes of all the sub-buffers or all the channels of the selected -tracing session. The maximum total size of all the snapshot files can -be configured using the option:--max-size option. +See the ``<>'' section below for usage examples. -Snapshot outputs can be listed using the `list-output` action. +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. -Snapshot outputs can be removed using the `del-output` action. The -configured name can be used when removing an output, or an ID as -listed by the `list-output` action. +[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. +==== -Taking a snapshot -~~~~~~~~~~~~~~~~~ -Taking a snapshot of the current tracing session is as easy as: ---------------------- -lttng snapshot record ---------------------- - -This writes the snapshot files to the configured output. It is possible -to use a custom, unregistered output at record time using the same -options supported by the `add-output` action. - -NOTE: Before taking a snapshot on a system with a high event throughput, -it is recommended to first run `lttng stop` (see -man:lttng-stop(1)). Otherwise, the snapshot could contain "holes", -the result of the tracers overwriting unconsumed trace packets during -the record operation. After the snapshot is recorded, the tracers can be -started again with `lttng start` (see man:lttng-start(1)). - - -include::common-cmd-options-head.txt[] +[[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. -Target +Output ~~~~~~ -option:-s 'SESSION', option:--session='SESSION':: - Take a snapshot of the sub-buffers of the channels contained in - the tracing session named 'SESSION' instead of the current - tracing session. - +See the ``<>'' section above. -Snapshot output -~~~~~~~~~~~~~~~ option:-C 'URL', option:--ctrl-url='URL':: - Set control path URL to 'URL' (must use option:--data-url option - also). + 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 data path URL to 'URL' (must use option:--ctrl-url option - also). + 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':: - Limit the total size of all the snapshot files written when - recording a snapshot to 'SIZE' bytes. The `k` (kiB), `M` (MiB), - and `G` (GiB) suffixes are supported. + 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-cmd-help-options.txt[] +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-cmd-footer.txt[] +include::common-footer.txt[] SEE ALSO -------- -man:lttng(1) +man:lttng(1), +man:lttng-create(1), +man:lttng-concepts(7)