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 that taking snapshots is allowed. This is done at tracing session
  50 creation time using the man:lttng-create(1) command's
  51 nloption:--snapshot option.
  52
  53 Note that, when a snapshot is taken, the sub-buffers are not cleared.
  54 This means that different recorded snapshots may contain the same
  55 events.
  56
  57 If you want, instead, to keep all the trace data, but divide it into
  58 archived chunks which are then free to process (just like snapshots),
  59 see the lttng-rotate(1) and lttng-enable-rotation(1) commands. Trace
  60 chunk archives do not overlap like snapshots can.
  61
  62
  63 Snapshot outputs
  64 ~~~~~~~~~~~~~~~~
  65 Snapshot outputs are the destinations of snapshot files when a
  66 snapshot is taken using the `record` action.
  67
  68 As of this version, only one snapshot output is allowed.
  69
  70 A snapshot output can be added using the `add-output` action. The
  71 output destination URL is set using either the 'URL' positional
  72 argument, or both the option:--ctrl-url and option:--data-url options.
  73 See man:lttng-create(1) to learn more about the URL format.
  74
  75 A name can be assigned to an output when adding it using the
  76 option:--name option. This name is part of the names of the
  77 snapshot files written to this output.
  78
  79 By default, the snapshot files can be as big as the sum of the
  80 sizes of all the sub-buffers or all the channels of the selected
  81 tracing session. The maximum total size of all the snapshot files can
  82 be configured using the option:--max-size option.
  83
  84 Snapshot outputs can be listed using the `list-output` action.
  85
  86 Snapshot outputs can be removed using the `del-output` action. The
  87 configured name can be used when removing an output, or an ID as
  88 listed by the `list-output` action.
  89
  90
  91 Taking a snapshot
  92 ~~~~~~~~~~~~~~~~~
  93 Taking a snapshot of the current tracing session is as easy as:
  94
  95 [role="term"]
  96 ----
  97 $ lttng snapshot record
  98 ----
  99
 100 This writes the snapshot files to the configured output. It is possible
 101 to use a custom, unregistered output at record time using the same
 102 options supported by the `add-output` action.
 103
 104 NOTE: Before taking a snapshot on a system with a high event throughput,
 105 it is recommended to first run `lttng stop` (see
 106 man:lttng-stop(1)). Otherwise, the snapshot could contain "holes",
 107 the result of the tracers overwriting unconsumed trace packets during
 108 the record operation. After the snapshot is recorded, the tracers can be
 109 started again with `lttng start` (see man:lttng-start(1)).
 110
 111
 112 include::common-cmd-options-head.txt[]
 113
 114
 115 Target
 116 ~~~~~~
 117 option:-s 'SESSION', option:--session='SESSION'::
 118     Take a snapshot of the sub-buffers of the channels contained in
 119     the tracing session named 'SESSION' instead of the current
 120     tracing session.
 121
 122
 123 Snapshot output
 124 ~~~~~~~~~~~~~~~
 125 option:-C 'URL', option:--ctrl-url='URL'::
 126     Set control path URL to 'URL' (must use option:--data-url option
 127     also).
 128
 129 option:-D 'URL', option:--data-url='URL'::
 130     Set data path URL to 'URL' (must use option:--ctrl-url option
 131     also).
 132
 133 option:-m 'SIZE', option:--max-size='SIZE'::
 134     Limit the total size of all the snapshot files written when
 135     recording a snapshot to 'SIZE' bytes. The `k` (kiB), `M` (MiB),
 136     and `G` (GiB) suffixes are supported.
 137
 138 option:-n 'NAME', option:--name='NAME'::
 139     Assign the name 'NAME' to the snapshot output.
 140
 141
 142 include::common-cmd-help-options.txt[]
 143
 144
 145 include::common-cmd-footer.txt[]
 146
 147
 148 SEE ALSO
 149 --------
 150 man:lttng(1)