doc/man/lttng-snapshot.1.txt

   1 lttng-snapshot(1)
   2 =================
   3 :revdate: 3 May 2021
   4
   5
   6 NAME
   7 ----
   8 lttng-snapshot - Take a snapshot of an LTTng tracing session
   9
  10
  11 SYNOPSIS
  12 --------
  13 Take a tracing session snapshot:
  14
  15 [verse]
  16 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *snapshot* *record* [option:--max-size='SIZE']
  17       [option:--name='NAME'] [option:--session='SESSION']
  18       [option:--ctrl-url='URL' option:--data-url='URL' | 'URL']
  19
  20 Add a snapshot output to a tracing session:
  21
  22 [verse]
  23 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *snapshot* *add-output* [option:--max-size='SIZE']
  24       [option:--name='NAME'] [option:--session='SESSION']
  25       (option:--ctrl-url='URL' option:--data-url='URL' | 'URL')
  26
  27 Show the snapshot output of a tracing session:
  28
  29 [verse]
  30 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *snapshot* *list-output* [option:--session='SESSION']
  31
  32 Remove the snapshot output from a tracing session:
  33
  34 [verse]
  35 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *snapshot* *del-output* [option:--session='SESSION'] *1*
  36
  37
  38 DESCRIPTION
  39 -----------
  40 The `lttng snapshot` command can take a snapshot of, add or remove a
  41 snapshot output, and show the snapshot output of:
  42
  43 With the option:--session='SESSION' option::
  44     The tracing session named 'SESSION'.
  45
  46 Without the option:--session option::
  47     The current tracing session (see man:lttng-concepts(7) to learn more
  48     about the current tracing session).
  49
  50 See man:lttng-concepts(7) to learn more about tracing sessions.
  51
  52 A _snapshot_ is a dump of the current sub-buffers of all the channels of
  53 the selected tracing session.
  54
  55 When LTTng takes a snapshot, it sends the sub-buffer dump of the
  56 selected tracing session to the local file system or over the network to
  57 a listening relay daemon (man:lttng-relayd(8)). See the
  58 <<output,Snapshot output>> section below to learn more.
  59
  60 When LTTng takes a snapshot, it does :not: clear the sub-buffers of the
  61 selected tracing session. In other words, different snapshots of the
  62 selected tracing session can contain the same event records.
  63
  64 You must have created the selected tracing session in snapshot mode (see
  65 the nloption:--snapshot option of the man:lttng-create(1) command as
  66 well as man:lttng-concepts(7) to learn more about tracing session modes)
  67 to use the `snapshot` command.
  68
  69 A `snapshot-session` trigger action can also take a tracing session
  70 snapshot (see man:lttng-add-trigger(1)).
  71
  72 If you want, instead, to keep all the trace data, but divide it into
  73 archived chunks which are then, like snapshots, ready to be processed,
  74 see the tracing session rotation feature in man:lttng-concepts(7). Trace
  75 chunk archives do :not: overlap like snapshots can.
  76
  77 [NOTE]
  78 ====
  79 Before you take a snapshot on a system with a high event throughput, the
  80 LTTng project recommends that you first run the man:lttng-stop(1)
  81 command. Otherwise, the snapshot could contain ``holes'', the result of
  82 the tracers overwriting unconsumed trace packets during the snapshot
  83 operation.
  84
  85 After LTTng writes the snapshot trace data, you can restart the tracing
  86 session with the man:lttng-start(1) command.
  87 ====
  88
  89
  90 [[output]]
  91 Snapshot output
  92 ~~~~~~~~~~~~~~~
  93 When you take a tracing session snapshot with the `record` action, LTTng
  94 writes the snapshot trace files to:
  95
  96 If you specify the 'URL' non-option argument or the option:--ctrl-url and option:--data-url options::
  97     The output defined by the 'URL' non-option argument or by the
  98     arguments of the options.
  99 +
 100 See man:lttng-create(1) for the format of 'URL'.
 101
 102 Otherwise::
 103     The snapshot output of the selected tracing session.
 104 +
 105 Add a snapshot output to a tracing session with the `add-output` action.
 106 As of LTTng{nbsp}{lttng_version}, you may only add one snapshot output
 107 to a given tracing session.
 108 +
 109 When you create a snapshot mode tracing session with the
 110 nloption:--snapshot option of the man:lttng-create(1) command, and
 111 without its nloption:--no-output option, the `create` command
 112 automatically adds a snapshot output named `snapshot-1` to the created
 113 tracing session:
 114 +
 115 --
 116 With its nloption:--output, nloption:--set-url, nloption:--ctrl-url, or nloption:--data-url options::
 117     Equivalent to using the `add-output` action with the provided or
 118     equivalent URL(s) immediately after creating the tracing session.
 119
 120 Otherwise::
 121     A subdirectory, under the `$LTTNG_HOME/lttng-traces` (`$LTTNG_HOME`
 122     defaults to `$HOME`) directory, of which the name contains the
 123     tracing session name and the date/time.
 124 --
 125 +
 126 Show the current snapshot output of a tracing session with the
 127 `list-output` action.
 128 +
 129 Remove the snapshot output of a tracing session with the
 130 `del-output` action.
 131
 132 For both the `record` and `add-output` actions:
 133
 134 * Assign a name to a snapshot output with the option:--name='NAME'
 135   option.
 136 +
 137 'NAME' becomes part of the snapshot trace file names which LTTng sends
 138 to this output.
 139
 140 * By default, the snapshot files can be as big as the sum of the sizes
 141   of all the sub-buffers of all the channels of the selected tracing
 142   session.
 143 +
 144 Set the maximum total size of all the snapshot trace files LTTng writes
 145 with the option:--max-size option.
 146
 147
 148 include::common-cmd-options-head.txt[]
 149
 150
 151 Recording target
 152 ~~~~~~~~~~~~~~~~
 153 option:-s 'SESSION', option:--session='SESSION'::
 154     Take a snapshot of the sub-buffers of the tracing session named
 155     'SESSION' instead of the current tracing session.
 156
 157
 158 Output
 159 ~~~~~~
 160 See the <<output,Snapshot output>> section above.
 161
 162 option:-C 'URL', option:--ctrl-url='URL'::
 163     Set the control path URL to 'URL'.
 164 +
 165 You must also use the option:--data-url option.
 166 +
 167 See man:lttng-create(1) for the format of 'URL'.
 168
 169 option:-D 'URL', option:--data-url='URL'::
 170     Set the trace data path URL to 'URL'.
 171 +
 172 You must also use the option:--ctrl-url option.
 173 +
 174 See man:lttng-create(1) for the format of 'URL'.
 175
 176 option:-m 'SIZE', option:--max-size='SIZE'::
 177     Set the maximum total size of all the snapshot trace files LTTng
 178     writes when taking a snapshot to 'SIZE' bytes.
 179 +
 180 The `k`{nbsp}(KiB), `M`{nbsp}(MiB), and `G`{nbsp}(GiB) suffixes are
 181 supported.
 182
 183 option:-n 'NAME', option:--name='NAME'::
 184     Assign the name 'NAME' to the snapshot output.
 185
 186
 187 include::common-cmd-help-options.txt[]
 188
 189
 190 include::common-cmd-footer.txt[]
 191
 192
 193 SEE ALSO
 194 --------
 195 man:lttng(1),
 196 man:lttng-concepts(7),
 197 man:lttng-create(1)