Commit | Line | Data |
---|---|---|
12397c59 PP |
1 | lttng-snapshot(1) |
2 | ================= | |
4605890e | 3 | :revdate: 9 November 2018 |
12397c59 PP |
4 | |
5 | ||
6 | NAME | |
7 | ---- | |
8 | lttng-snapshot - Take LTTng snapshots and configure snapshot outputs | |
9 | ||
10 | ||
11 | SYNOPSIS | |
12 | -------- | |
13 | Add a snapshot output: | |
14 | ||
15 | [verse] | |
ce19b9ed | 16 | *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *snapshot add-output* [option:--max-size='SIZE'] |
12397c59 PP |
17 | [option:--name='NAME'] [option:--session='SESSION'] |
18 | (option:--ctrl-url='URL' option:--data-url='URL' | 'URL') | |
19 | ||
20 | Remove a snapshot output: | |
21 | ||
22 | [verse] | |
ce19b9ed | 23 | *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *snapshot del-output* [option:--session='SESSION'] |
12397c59 PP |
24 | ('ID' | 'NAME') |
25 | ||
26 | List current snapshot outputs: | |
27 | ||
28 | [verse] | |
ce19b9ed | 29 | *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *snapshot list-output* [option:--session='SESSION'] |
12397c59 PP |
30 | |
31 | Take a snapshot: | |
32 | ||
33 | [verse] | |
ce19b9ed | 34 | *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *snapshot record* [option:--max-size='SIZE'] |
12397c59 PP |
35 | [option:--name='NAME'] [option:--session='SESSION'] |
36 | (option:--ctrl-url='URL' option:--data-url='URL' | 'URL') | |
37 | ||
38 | ||
39 | DESCRIPTION | |
40 | ----------- | |
41 | The `lttng snapshot` command manages the snapshot outputs and takes | |
42 | snapshots. | |
43 | ||
44 | A _snapshot_ is a dump of the current sub-buffers of all the channels | |
45 | of a given tracing session. When a snapshot is taken, the memory dump | |
46 | is sent to the registered snapshot outputs. | |
47 | ||
48 | The tracing session should be created in _snapshot mode_ to make sure | |
d539dc89 PP |
49 | that taking snapshots is allowed. This is done at tracing session |
50 | creation time using the man:lttng-create(1) command's | |
51 | nloption:--snapshot option. | |
12397c59 PP |
52 | |
53 | Note that, when a snapshot is taken, the sub-buffers are not cleared. | |
54 | This means that different recorded snapshots may contain the same | |
55 | events. | |
56 | ||
d539dc89 PP |
57 | If you want, instead, to keep all the trace data, but divide it into |
58 | archived chunks which are then free to process (just like snapshots), | |
59 | see the lttng-rotate(1) and lttng-enable-rotation(1) commands. Trace | |
60 | chunk archives do not overlap like snapshots can. | |
61 | ||
12397c59 PP |
62 | |
63 | Snapshot outputs | |
64 | ~~~~~~~~~~~~~~~~ | |
65 | Snapshot outputs are the destinations of snapshot files when a | |
66 | snapshot is taken using the `record` action. | |
67 | ||
68 | As of this version, only one snapshot output is allowed. | |
69 | ||
70 | A snapshot output can be added using the `add-output` action. The | |
71 | output destination URL is set using either the 'URL' positional | |
72 | argument, or both the option:--ctrl-url and option:--data-url options. | |
7c1a4458 | 73 | See man:lttng-create(1) to learn more about the URL format. |
12397c59 PP |
74 | |
75 | A name can be assigned to an output when adding it using the | |
76 | option:--name option. This name is part of the names of the | |
77 | snapshot files written to this output. | |
78 | ||
79 | By default, the snapshot files can be as big as the sum of the | |
80 | sizes of all the sub-buffers or all the channels of the selected | |
81 | tracing session. The maximum total size of all the snapshot files can | |
82 | be configured using the option:--max-size option. | |
83 | ||
84 | Snapshot outputs can be listed using the `list-output` action. | |
85 | ||
86 | Snapshot outputs can be removed using the `del-output` action. The | |
87 | configured name can be used when removing an output, or an ID as | |
88 | listed by the `list-output` action. | |
89 | ||
90 | ||
91 | Taking a snapshot | |
92 | ~~~~~~~~~~~~~~~~~ | |
93 | Taking a snapshot of the current tracing session is as easy as: | |
94 | ||
d25b4989 | 95 | [role="term"] |
03c5529d PP |
96 | ---- |
97 | $ lttng snapshot record | |
98 | ---- | |
12397c59 PP |
99 | |
100 | This writes the snapshot files to the configured output. It is possible | |
101 | to use a custom, unregistered output at record time using the same | |
102 | options supported by the `add-output` action. | |
103 | ||
104 | NOTE: Before taking a snapshot on a system with a high event throughput, | |
105 | it is recommended to first run `lttng stop` (see | |
7c1a4458 | 106 | man:lttng-stop(1)). Otherwise, the snapshot could contain "holes", |
12397c59 PP |
107 | the result of the tracers overwriting unconsumed trace packets during |
108 | the record operation. After the snapshot is recorded, the tracers can be | |
7c1a4458 | 109 | started again with `lttng start` (see man:lttng-start(1)). |
12397c59 PP |
110 | |
111 | ||
112 | include::common-cmd-options-head.txt[] | |
113 | ||
114 | ||
115 | Target | |
116 | ~~~~~~ | |
59b19c3c | 117 | option:-s 'SESSION', option:--session='SESSION':: |
12397c59 PP |
118 | Take a snapshot of the sub-buffers of the channels contained in |
119 | the tracing session named 'SESSION' instead of the current | |
120 | tracing session. | |
121 | ||
122 | ||
123 | Snapshot output | |
124 | ~~~~~~~~~~~~~~~ | |
59b19c3c | 125 | option:-C 'URL', option:--ctrl-url='URL':: |
12397c59 PP |
126 | Set control path URL to 'URL' (must use option:--data-url option |
127 | also). | |
128 | ||
59b19c3c | 129 | option:-D 'URL', option:--data-url='URL':: |
12397c59 PP |
130 | Set data path URL to 'URL' (must use option:--ctrl-url option |
131 | also). | |
132 | ||
59b19c3c | 133 | option:-m 'SIZE', option:--max-size='SIZE':: |
12397c59 PP |
134 | Limit the total size of all the snapshot files written when |
135 | recording a snapshot to 'SIZE' bytes. The `k` (kiB), `M` (MiB), | |
136 | and `G` (GiB) suffixes are supported. | |
137 | ||
59b19c3c | 138 | option:-n 'NAME', option:--name='NAME':: |
12397c59 PP |
139 | Assign the name 'NAME' to the snapshot output. |
140 | ||
141 | ||
142 | include::common-cmd-help-options.txt[] | |
143 | ||
144 | ||
145 | include::common-cmd-footer.txt[] | |
146 | ||
147 | ||
148 | SEE ALSO | |
149 | -------- | |
7c1a4458 | 150 | man:lttng(1) |