contents/using-lttng/controlling-tracing/taking-a-snapshot.md

   1 ---
   2 id: taking-a-snapshot
   3 ---
   4
   5 The normal behavior of LTTng is to record trace data as trace files.
   6 This is ideal for keeping a long history of events that occurred on
   7 the target system and applications, but may be too much data in some
   8 situations. For example, you may wish to trace your application
   9 continuously until some critical situation happens, in which case you
  10 would only need the latest few recorded events to perform the desired
  11 analysis, not multi-gigabyte trace files.
  12
  13 LTTng has an interesting feature called _snapshots_. When creating
  14 a tracing session in snapshot mode, no trace files are written; the
  15 tracers' sub-buffers are constantly overwriting the oldest recorded
  16 events with the newest. At any time, either when the tracers are started
  17 or stopped, you may take a snapshot of those sub-buffers.
  18
  19 There is no difference between the format of a normal trace file and the
  20 format of a snapshot: viewers of LTTng traces will also support LTTng
  21 snapshots. By default, snapshots are written to disk, but they may also
  22 be sent over the network.
  23
  24 To create a tracing session in snapshot mode, do:
  25
  26 <pre class="term">
  27 lttng create --snapshot my-snapshot-session
  28 </pre>
  29
  30 Next, enable channels, events and add context to channels as usual.
  31 Once a tracing session is created in snapshot mode, channels will be
  32 forced to use the
  33 [overwrite](#doc-channel-overwrite-mode-vs-discard-mode) mode
  34 (`--overwrite` option of the `enable-channel` command; also called
  35 _flight recorder mode_) and have an `mmap()` channel type
  36 (`--output mmap`).
  37
  38 Start tracing. When you're ready to take a snapshot, do:
  39
  40 <pre class="term">
  41 lttng snapshot record --name my-snapshot
  42 </pre>
  43
  44 This will record a snapshot named `my-snapshot` of all channels of
  45 all domains of the current tracing session. By default, snapshots files
  46 are recorded in the path returned by `lttng snapshot list-output`. You
  47 may change this path or decide to send snapshots over the network
  48 using either:
  49
  50   1. an output path/URL specified when creating the tracing session
  51      (`lttng create`)
  52   2. an added snapshot output path/URL using
  53      `lttng snapshot add-output`
  54   3. an output path/URL provided directly to the
  55      `lttng snapshot record` command
  56
  57 Method 3 overrides method 2 which overrides method 1. When specifying
  58 a URL, a relay daemon must be listening on some machine (see
  59 [Sending trace data over the network](#doc-sending-trace-data-over-the-network)).
  60
  61 If you need to make absolutely sure that the output file won't be
  62 larger than a certain limit, you can set a maximum snapshot size when
  63 taking it with the `--max-size` option:
  64
  65 <pre class="term">
  66 lttng snapshot record --name my-snapshot --max-size 2M
  67 </pre>
  68
  69 Older recorded events will be discarded in order to respect this
  70 maximum size.