Commit | Line | Data |
---|---|---|
12397c59 PP |
1 | lttng-snapshot(1) |
2 | ================= | |
990cbf52 | 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 | |
49 | taking snapshots is allowed. This is done at tracing session creation | |
7c1a4458 | 50 | time using the man:lttng-create(1) command. |
12397c59 PP |
51 | |
52 | Note that, when a snapshot is taken, the sub-buffers are not cleared. | |
53 | This means that different recorded snapshots may contain the same | |
54 | events. | |
55 | ||
56 | ||
57 | Snapshot outputs | |
58 | ~~~~~~~~~~~~~~~~ | |
59 | Snapshot outputs are the destinations of snapshot files when a | |
60 | snapshot is taken using the `record` action. | |
61 | ||
62 | As of this version, only one snapshot output is allowed. | |
63 | ||
64 | A snapshot output can be added using the `add-output` action. The | |
65 | output destination URL is set using either the 'URL' positional | |
66 | argument, or both the option:--ctrl-url and option:--data-url options. | |
7c1a4458 | 67 | See man:lttng-create(1) to learn more about the URL format. |
12397c59 PP |
68 | |
69 | A name can be assigned to an output when adding it using the | |
70 | option:--name option. This name is part of the names of the | |
71 | snapshot files written to this output. | |
72 | ||
73 | By default, the snapshot files can be as big as the sum of the | |
74 | sizes of all the sub-buffers or all the channels of the selected | |
75 | tracing session. The maximum total size of all the snapshot files can | |
76 | be configured using the option:--max-size option. | |
77 | ||
78 | Snapshot outputs can be listed using the `list-output` action. | |
79 | ||
80 | Snapshot outputs can be removed using the `del-output` action. The | |
81 | configured name can be used when removing an output, or an ID as | |
82 | listed by the `list-output` action. | |
83 | ||
84 | ||
85 | Taking a snapshot | |
86 | ~~~~~~~~~~~~~~~~~ | |
87 | Taking a snapshot of the current tracing session is as easy as: | |
88 | ||
d25b4989 | 89 | [role="term"] |
03c5529d PP |
90 | ---- |
91 | $ lttng snapshot record | |
92 | ---- | |
12397c59 PP |
93 | |
94 | This writes the snapshot files to the configured output. It is possible | |
95 | to use a custom, unregistered output at record time using the same | |
96 | options supported by the `add-output` action. | |
97 | ||
98 | NOTE: Before taking a snapshot on a system with a high event throughput, | |
99 | it is recommended to first run `lttng stop` (see | |
7c1a4458 | 100 | man:lttng-stop(1)). Otherwise, the snapshot could contain "holes", |
12397c59 PP |
101 | the result of the tracers overwriting unconsumed trace packets during |
102 | the record operation. After the snapshot is recorded, the tracers can be | |
7c1a4458 | 103 | started again with `lttng start` (see man:lttng-start(1)). |
12397c59 PP |
104 | |
105 | ||
106 | include::common-cmd-options-head.txt[] | |
107 | ||
108 | ||
109 | Target | |
110 | ~~~~~~ | |
59b19c3c | 111 | option:-s 'SESSION', option:--session='SESSION':: |
12397c59 PP |
112 | Take a snapshot of the sub-buffers of the channels contained in |
113 | the tracing session named 'SESSION' instead of the current | |
114 | tracing session. | |
115 | ||
116 | ||
117 | Snapshot output | |
118 | ~~~~~~~~~~~~~~~ | |
59b19c3c | 119 | option:-C 'URL', option:--ctrl-url='URL':: |
12397c59 PP |
120 | Set control path URL to 'URL' (must use option:--data-url option |
121 | also). | |
122 | ||
59b19c3c | 123 | option:-D 'URL', option:--data-url='URL':: |
12397c59 PP |
124 | Set data path URL to 'URL' (must use option:--ctrl-url option |
125 | also). | |
126 | ||
59b19c3c | 127 | option:-m 'SIZE', option:--max-size='SIZE':: |
12397c59 PP |
128 | Limit the total size of all the snapshot files written when |
129 | recording a snapshot to 'SIZE' bytes. The `k` (kiB), `M` (MiB), | |
130 | and `G` (GiB) suffixes are supported. | |
131 | ||
59b19c3c | 132 | option:-n 'NAME', option:--name='NAME':: |
12397c59 PP |
133 | Assign the name 'NAME' to the snapshot output. |
134 | ||
135 | ||
136 | include::common-cmd-help-options.txt[] | |
137 | ||
138 | ||
139 | include::common-cmd-footer.txt[] | |
140 | ||
141 | ||
142 | SEE ALSO | |
143 | -------- | |
7c1a4458 | 144 | man:lttng(1) |