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 overwrite mode (`--overwrite` option of the
  33 `enable-channel` command) and have an `mmap()` channel type
  34 (`--output mmap`).
  35
  36 Start tracing. When you're ready to take a snapshot, do:
  37
  38 <pre class="term">
  39 lttng snapshot record --name my-snapshot
  40 </pre>
  41
  42 This will record a snapshot named `my-snapshot` of all channels of
  43 all domains of the current tracing session. By default, snapshots files
  44 are recorded in the path returned by `lttng snapshot list-output`. You
  45 may change this path or decide to send snapshots over the network
  46 using either:
  47
  48   1. an output path/URL specified when creating the tracing session
  49      (`lttng create`)
  50   2. an added snapshot output path/URL using
  51      `lttng snapshot add-output`
  52   3. an output path/URL provided directly to the
  53      `lttng snapshot record` command
  54
  55 Method 3 overrides method 2 which overrides method 1. When specifying
  56 a URL, a relay daemon must be listening on some machine (see
  57 [Sending trace data over the network](#doc-sending-trace-data-over-the-network)).
  58
  59 If you need to make absolutely sure that the output file won't be
  60 larger than a certain limit, you can set a maximum snapshot size when
  61 taking it with the `--max-size` option:
  62
  63 <pre class="term">
  64 lttng snapshot record --name my-snapshot --max-size 2M
  65 </pre>
  66
  67 Older recorded events will be discarded in order to respect this
  68 maximum size.