doc/man/lttng-snapshot.1.txt

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