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

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