doc/man/lttng-snapshot.1.txt

   1 lttng-snapshot(1)
   2 =================
   3 :revdate: 14 June 2021
   4
   5
   6 NAME
   7 ----
   8 lttng-snapshot - Take a snapshot of an LTTng recording session
   9
  10
  11 SYNOPSIS
  12 --------
  13 Take a recording 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 recording 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 recording session:
  28
  29 [verse]
  30 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *snapshot* *list-output* [option:--session='SESSION']
  31
  32 Remove the snapshot output from a recording 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 recording session named 'SESSION'.
  45
  46 Without the option:--session option::
  47     The current recording session (see man:lttng-concepts(7) to learn more
  48     about the current recording session).
  49
  50 See man:lttng-concepts(7) to learn more about recording sessions.
  51
  52 A _snapshot_ is a dump of the current sub-buffers of all the channels of
  53 the selected recording session.
  54
  55 When LTTng takes a snapshot, it sends the sub-buffer dump of the
  56 selected recording session to the local file system or over the network
  57 to 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 recording session. In other words, different snapshots of the
  62 selected recording session can contain the same event records.
  63
  64 You must have created the selected recording session in snapshot mode
  65 (see the nloption:--snapshot option of the man:lttng-create(1) command
  66 as well as man:lttng-concepts(7) to learn more about recording session
  67 modes) to use the `snapshot` command.
  68
  69 A `snapshot-session` trigger action can also take a recording session
  70 snapshot (see man:lttng-add-trigger(1)).
  71
  72 See the ``<<examples,EXAMPLES>>'' section below for usage examples.
  73
  74 If you want, instead, to keep all the trace data, but divide it into
  75 archived chunks which are then, like snapshots, ready to be processed,
  76 see the recording session rotation feature in man:lttng-concepts(7).
  77 Trace chunk archives do :not: overlap like snapshots can.
  78
  79 [NOTE]
  80 ====
  81 Before you take a snapshot on a system with a high event throughput, the
  82 LTTng project recommends that you first run the man:lttng-stop(1)
  83 command. Otherwise, the snapshot could contain ``holes'', the result of
  84 the tracers overwriting unconsumed trace packets during the snapshot
  85 operation.
  86
  87 After LTTng writes the snapshot trace data, you can restart the
  88 recording session with the man:lttng-start(1) command.
  89 ====
  90
  91
  92 [[output]]
  93 Snapshot output
  94 ~~~~~~~~~~~~~~~
  95 When you take a recording session snapshot with the `record` action, LTTng
  96 writes the snapshot trace files to:
  97
  98 If you specify the 'URL' non-option argument or the option:--ctrl-url and option:--data-url options::
  99     The output defined by the 'URL' non-option argument or by the
 100     arguments of the options.
 101 +
 102 See man:lttng-create(1) for the format of 'URL'.
 103
 104 Otherwise::
 105     The snapshot output of the selected recording session.
 106 +
 107 Add a snapshot output to a recording session with the `add-output`
 108 action. As of LTTng{nbsp}{lttng_version}, you may only add one snapshot
 109 output to a given recording session.
 110 +
 111 When you create a snapshot mode recording session with the
 112 nloption:--snapshot option of the man:lttng-create(1) command, and
 113 without its nloption:--no-output option, the `create` command
 114 automatically adds a snapshot output named `snapshot-1` to the created
 115 recording session:
 116 +
 117 --
 118 With its nloption:--output, nloption:--set-url, nloption:--ctrl-url, or nloption:--data-url options::
 119     Equivalent to using the `add-output` action with the provided or
 120     equivalent URL(s) immediately after creating the recording session.
 121
 122 Otherwise::
 123     A subdirectory, under the `$LTTNG_HOME/lttng-traces` (`$LTTNG_HOME`
 124     defaults to `$HOME`) directory, of which the name contains the
 125     recording session name and the date/time.
 126 --
 127 +
 128 Show the current snapshot output of a recording session with the
 129 `list-output` action.
 130 +
 131 Remove the snapshot output of a recording session with the
 132 `del-output` action.
 133
 134 For both the `record` and `add-output` actions:
 135
 136 * Assign a name to a snapshot output with the option:--name='NAME'
 137   option.
 138 +
 139 'NAME' becomes part of the snapshot trace file names which LTTng sends
 140 to this output.
 141
 142 * By default, the snapshot files can be as big as the sum of the sizes
 143   of all the sub-buffers of all the channels of the selected recording
 144   session.
 145 +
 146 Set the maximum total size of all the snapshot trace files LTTng writes
 147 with the option:--max-size option.
 148
 149
 150 include::common-lttng-cmd-options-head.txt[]
 151
 152
 153 Recording target
 154 ~~~~~~~~~~~~~~~~
 155 option:-s 'SESSION', option:--session='SESSION'::
 156     Take a snapshot of the sub-buffers of the recording session named
 157     'SESSION' instead of the current recording session.
 158
 159
 160 Output
 161 ~~~~~~
 162 See the ``<<output,Snapshot output>>'' section above.
 163
 164 option:-C 'URL', option:--ctrl-url='URL'::
 165     Set the control path URL to 'URL'.
 166 +
 167 You must also use the option:--data-url option.
 168 +
 169 See man:lttng-create(1) for the format of 'URL'.
 170
 171 option:-D 'URL', option:--data-url='URL'::
 172     Set the trace data path URL to 'URL'.
 173 +
 174 You must also use the option:--ctrl-url option.
 175 +
 176 See man:lttng-create(1) for the format of 'URL'.
 177
 178 option:-m 'SIZE', option:--max-size='SIZE'::
 179     Set the maximum total size of all the snapshot trace files LTTng
 180     writes when taking a snapshot to 'SIZE' bytes.
 181 +
 182 The `k`{nbsp}(KiB), `M`{nbsp}(MiB), and `G`{nbsp}(GiB) suffixes are
 183 supported.
 184
 185 option:-n 'NAME', option:--name='NAME'::
 186     Assign the name 'NAME' to the snapshot output.
 187
 188
 189 include::common-lttng-cmd-help-options.txt[]
 190
 191
 192 include::common-lttng-cmd-after-options.txt[]
 193
 194
 195 [[examples]]
 196 EXAMPLES
 197 --------
 198 .Take a snapshot of the current recording session, sending the trace files to its snapshot output.
 199 ====
 200 [role="term"]
 201 ----
 202 $ lttng snapshot record
 203 ----
 204 ====
 205
 206 .Take a snapshot of a specific recording session, giving it a custom name.
 207 ====
 208 See the option:--session and option:--name options.
 209
 210 [role="term"]
 211 ----
 212 $ lttng snapshot record --session=my-session --name=SNAP
 213 ----
 214 ====
 215
 216 .Take a snapshot of the current recording session, sending the trace files to a custom location.
 217 ====
 218 See the ``Output directory'' section of man:lttng-relayd(8) to
 219 understand where the relay daemon to connect to (`3.96.87.215`) writes
 220 the received traces.
 221
 222 [role="term"]
 223 ----
 224 $ lttng snapshot record net://3.96.87.215
 225 ----
 226 ====
 227
 228 .Replace the snapshot output of a specific recording session with a local file system path.
 229 ====
 230 See the option:--session option.
 231
 232 [role="term"]
 233 ----
 234 $ lttng snapshot del-output --session=monk 1
 235 $ lttng snapshot add-output --session=monk \
 236                  file:///path/to/snapshots
 237 ----
 238 ====
 239
 240 .Take a snapshot of the current recording session, making sure its size is not over 4{nbsp}MiB.
 241 ====
 242 See the option:--max-size option.
 243
 244 [role="term"]
 245 ----
 246 $ lttng snapshot record --max-size=4M
 247 ----
 248 ====
 249
 250
 251 include::common-footer.txt[]
 252
 253
 254 SEE ALSO
 255 --------
 256 man:lttng(1),
 257 man:lttng-create(1),
 258 man:lttng-concepts(7)