Commit | Line | Data |
---|---|---|
5e0cbfb0 PP |
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 | |
47bfcb75 | 20 | format of a snapshot: viewers of LTTng traces also support LTTng |
5e0cbfb0 PP |
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. | |
47bfcb75 | 31 | Once a tracing session is created in snapshot mode, channels are |
6d30cd92 PP |
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 | |
5e0cbfb0 PP |
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 | ||
47bfcb75 | 44 | This records a snapshot named `my-snapshot` of all channels of |
5e0cbfb0 PP |
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 | ||
47bfcb75 | 69 | Older recorded events are discarded in order to respect this |
5e0cbfb0 | 70 | maximum size. |