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