doc/man/lttng-snapshot.1.txt

   1 lttng-snapshot(1)
   2 =================
   3 :revdate: 9 November 2018
   4
   5
   6 NAME
   7 ----
   8 lttng-snapshot - Take LTTng snapshots and configure snapshot outputs
   9
  10
  11 SYNOPSIS
  12 --------
  13 Add a snapshot output:
  14
  15 [verse]
  16 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *snapshot add-output* [option:--max-size='SIZE']
  17       [option:--name='NAME'] [option:--session='SESSION']
  18       (option:--ctrl-url='URL' option:--data-url='URL' | 'URL')
  19
  20 Remove a snapshot output:
  21
  22 [verse]
  23 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *snapshot del-output* [option:--session='SESSION']
  24       ('ID' | 'NAME')
  25
  26 List current snapshot outputs:
  27
  28 [verse]
  29 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *snapshot list-output* [option:--session='SESSION']
  30
  31 Take a snapshot:
  32
  33 [verse]
  34 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *snapshot record* [option:--max-size='SIZE']
  35       [option:--name='NAME'] [option:--session='SESSION']
  36       (option:--ctrl-url='URL' option:--data-url='URL' | 'URL')
  37
  38
  39 DESCRIPTION
  40 -----------
  41 The `lttng snapshot` command manages the snapshot outputs and takes
  42 snapshots.
  43
  44 A _snapshot_ is a dump of the current sub-buffers of all the channels
  45 of a given tracing session. When a snapshot is taken, the memory dump
  46 is sent to the registered snapshot outputs.
  47
  48 The tracing session should be created in _snapshot mode_ to make sure
  49 taking snapshots is allowed. This is done at tracing session creation
  50 time using the man:lttng-create(1) command.
  51
  52 Note that, when a snapshot is taken, the sub-buffers are not cleared.
  53 This means that different recorded snapshots may contain the same
  54 events.
  55
  56
  57 Snapshot outputs
  58 ~~~~~~~~~~~~~~~~
  59 Snapshot outputs are the destinations of snapshot files when a
  60 snapshot is taken using the `record` action.
  61
  62 As of this version, only one snapshot output is allowed.
  63
  64 A snapshot output can be added using the `add-output` action. The
  65 output destination URL is set using either the 'URL' positional
  66 argument, or both the option:--ctrl-url and option:--data-url options.
  67 See man:lttng-create(1) to learn more about the URL format.
  68
  69 A name can be assigned to an output when adding it using the
  70 option:--name option. This name is part of the names of the
  71 snapshot files written to this output.
  72
  73 By default, the snapshot files can be as big as the sum of the
  74 sizes of all the sub-buffers or all the channels of the selected
  75 tracing session. The maximum total size of all the snapshot files can
  76 be configured using the option:--max-size option.
  77
  78 Snapshot outputs can be listed using the `list-output` action.
  79
  80 Snapshot outputs can be removed using the `del-output` action. The
  81 configured name can be used when removing an output, or an ID as
  82 listed by the `list-output` action.
  83
  84
  85 Taking a snapshot
  86 ~~~~~~~~~~~~~~~~~
  87 Taking a snapshot of the current tracing session is as easy as:
  88
  89 [role="term"]
  90 ----
  91 $ lttng snapshot record
  92 ----
  93
  94 This writes the snapshot files to the configured output. It is possible
  95 to use a custom, unregistered output at record time using the same
  96 options supported by the `add-output` action.
  97
  98 NOTE: Before taking a snapshot on a system with a high event throughput,
  99 it is recommended to first run `lttng stop` (see
 100 man:lttng-stop(1)). Otherwise, the snapshot could contain "holes",
 101 the result of the tracers overwriting unconsumed trace packets during
 102 the record operation. After the snapshot is recorded, the tracers can be
 103 started again with `lttng start` (see man:lttng-start(1)).
 104
 105
 106 include::common-cmd-options-head.txt[]
 107
 108
 109 Target
 110 ~~~~~~
 111 option:-s 'SESSION', option:--session='SESSION'::
 112     Take a snapshot of the sub-buffers of the channels contained in
 113     the tracing session named 'SESSION' instead of the current
 114     tracing session.
 115
 116
 117 Snapshot output
 118 ~~~~~~~~~~~~~~~
 119 option:-C 'URL', option:--ctrl-url='URL'::
 120     Set control path URL to 'URL' (must use option:--data-url option
 121     also).
 122
 123 option:-D 'URL', option:--data-url='URL'::
 124     Set data path URL to 'URL' (must use option:--ctrl-url option
 125     also).
 126
 127 option:-m 'SIZE', option:--max-size='SIZE'::
 128     Limit the total size of all the snapshot files written when
 129     recording a snapshot to 'SIZE' bytes. The `k` (kiB), `M` (MiB),
 130     and `G` (GiB) suffixes are supported.
 131
 132 option:-n 'NAME', option:--name='NAME'::
 133     Assign the name 'NAME' to the snapshot output.
 134
 135
 136 include::common-cmd-help-options.txt[]
 137
 138
 139 include::common-cmd-footer.txt[]
 140
 141
 142 SEE ALSO
 143 --------
 144 man:lttng(1)