X-Git-Url: https://git.liburcu.org/?a=blobdiff_plain;f=doc%2Fman%2Flttng-snapshot.1.txt;h=94bf7c9f585c7e6b5aca7b8347d887ce40e59549;hb=26f0c7794376456fcb5b13d4eae91c0ccf0dfe66;hp=2d2b6c68fd5d5167c2b00a8485c12f0dd8769de0;hpb=4fd116d0a92783f76416ae77d41b28690e553380;p=lttng-tools.git diff --git a/doc/man/lttng-snapshot.1.txt b/doc/man/lttng-snapshot.1.txt index 2d2b6c68f..94bf7c9f5 100644 --- a/doc/man/lttng-snapshot.1.txt +++ b/doc/man/lttng-snapshot.1.txt @@ -1,133 +1,186 @@ lttng-snapshot(1) ================= +:revdate: 3 May 2021 NAME ---- -lttng-snapshot - Take LTTng snapshots and configure snapshot outputs +lttng-snapshot - Take a snapshot of an LTTng tracing session SYNOPSIS -------- -Add a snapshot output: +Take a tracing session snapshot: [verse] -*lttng* ['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 tracing session: [verse] -*lttng* ['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 tracing session: [verse] -*lttng* ['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 tracing session: [verse] -*lttng* ['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 tracing 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 linklttng:lttng-create(1) command. +Without the option:--session option:: + The current tracing session (see man:lttng-concepts(7) to learn more + about the current tracing 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 tracing sessions. +A _snapshot_ is a dump of the current sub-buffers of all the channels of +the selected tracing session. -Snapshot outputs -~~~~~~~~~~~~~~~~ -Snapshot outputs are the destinations of snapshot files when a -snapshot is taken using the `record` action. - -As of this version, only one snapshot output is allowed. - -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 linklttng:lttng-create(1) to learn more about the URL format. +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. -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. +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. -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. +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. -Snapshot outputs can be listed using the `list-output` action. +A `snapshot-session` trigger action can also take a tracing session +snapshot (see man:lttng-add-trigger(1)). -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. +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. -Taking a snapshot -~~~~~~~~~~~~~~~~~ -Taking a snapshot of the current tracing session is as easy as: +After LTTng writes the snapshot trace data, you can restart the tracing +session with the man:lttng-start(1) command. +==== ---------------------- -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 -linklttng: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 linklttng:lttng-start(1)). +[[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-cmd-options-head.txt[] -Target -~~~~~~ -option:-s, 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. - - -Snapshot output -~~~~~~~~~~~~~~~ -option:-C, option:--ctrl-url='URL':: - Set control path URL to 'URL' (must use option:--data-url option - also). - -option:-D, option:--data-url='URL':: - Set data path URL to 'URL' (must use option:--ctrl-url option - also). +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. -option:-m, 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. -option:-n, option:--name='NAME':: +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. @@ -139,4 +192,6 @@ include::common-cmd-footer.txt[] SEE ALSO -------- -linklttng:lttng(1) +man:lttng(1), +man:lttng-concepts(7), +man:lttng-create(1)