From 12397c594ba2278cdd90f5b6655f63e1c70c0425 Mon Sep 17 00:00:00 2001 From: Philippe Proulx Date: Sat, 14 Nov 2015 01:02:29 -0500 Subject: [PATCH] doc/man: create lttng-snapshot(1) and update/fix content MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit Signed-off-by: Philippe Proulx Signed-off-by: Jérémie Galarneau --- doc/man/Makefile.am | 3 +- doc/man/lttng-snapshot.1.txt | 143 +++++++++++++++++++++++++++++++++++ 2 files changed, 145 insertions(+), 1 deletion(-) create mode 100644 doc/man/lttng-snapshot.1.txt diff --git a/doc/man/Makefile.am b/doc/man/Makefile.am index 27225dd27..316e28950 100644 --- a/doc/man/Makefile.am +++ b/doc/man/Makefile.am @@ -26,7 +26,8 @@ MAN1_NAMES = \ lttng-track \ lttng-untrack \ lttng-status \ - lttng-help + lttng-help \ + lttng-snapshot MAN3_NAMES = MAN8_NAMES = MAN1_NO_ASCIIDOC_NAMES = lttng-crash diff --git a/doc/man/lttng-snapshot.1.txt b/doc/man/lttng-snapshot.1.txt new file mode 100644 index 000000000..e779b2dd2 --- /dev/null +++ b/doc/man/lttng-snapshot.1.txt @@ -0,0 +1,143 @@ +lttng-snapshot(1) +================= + + +NAME +---- +lttng-snapshot - Take LTTng snapshots and configure snapshot outputs + + +SYNOPSIS +-------- +Add a snapshot output: + +[verse] +*lttng* ['GENERAL OPTIONS'] *snapshot add-output* [option:--max-size='SIZE'] + [option:--name='NAME'] [option:--session='SESSION'] + (option:--ctrl-url='URL' option:--data-url='URL' | 'URL') + +Remove a snapshot output: + +[verse] +*lttng* ['GENERAL OPTIONS'] *snapshot del-output* [option:--session='SESSION'] + ('ID' | 'NAME') + +List current snapshot outputs: + +[verse] +*lttng* ['GENERAL OPTIONS'] *snapshot list-output* [option:--session='SESSION'] + +Take a snapshot: + +[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') + + +DESCRIPTION +----------- +The `lttng snapshot` command manages the snapshot outputs and takes +snapshots. + +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. + +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. + +Note that, when a snapshot is taken, the sub-buffers are not cleared. +This means that different recorded snapshots may contain the same +events. + + +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. + +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. + +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. + +Snapshot outputs can be listed using the `list-output` action. + +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. + + +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 +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)). + + +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). + +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':: + Assign the name 'NAME' to the snapshot output. + + +include::common-cmd-help-options.txt[] + + +include::common-cmd-footer.txt[] + + +SEE ALSO +-------- +linklttng:lttng-untrack(1), +linklttng:lttng(1) -- 2.34.1