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 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 are
  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 records 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 are discarded in order to respect this
  70 maximum size.