Commit | Line | Data |
---|---|---|
5e0cbfb0 PP |
1 | --- |
2 | id: taking-a-snapshot | |
86384750 | 3 | since: 2.3 |
5e0cbfb0 PP |
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 | |
47bfcb75 | 21 | format of a snapshot: viewers of LTTng traces also support LTTng |
5e0cbfb0 PP |
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. | |
47bfcb75 | 32 | Once a tracing session is created in snapshot mode, channels are |
6d30cd92 PP |
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 | |
5e0cbfb0 PP |
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 | ||
47bfcb75 | 45 | This records a snapshot named `my-snapshot` of all channels of |
5e0cbfb0 PP |
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 | ||
47bfcb75 | 70 | Older recorded events are discarded in order to respect this |
5e0cbfb0 | 71 | maximum size. |