| 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. |