1LTTNG-REGENERATE(1) LTTng Manual LTTNG-REGENERATE(1)
2
3
4
6 lttng-regenerate - Regenerate specific data of an LTTng recording
7 session
8
10 Regenerate the metadata of a recording session:
11
12 lttng [GENERAL OPTIONS] regenerate metadata [--session=SESSION]
13
14 Regenerate the state dump event records of a recording session:
15
16 lttng [GENERAL OPTIONS] regenerate statedump [--session=SESSION]
17
19 The lttng regenerate command regenerates specific data of:
20
21 With the --session=SESSION option
22 The recording session named SESSION.
23
24 Without the --session option
25 The current recording session (see lttng-concepts(7) to learn more
26 about the current recording session).
27
28 See lttng-concepts(7) to learn more about recording sessions.
29
30 As of this version, the metadata and statedump targets are available.
31
32 See the “EXAMPLES” section below for usage examples.
33
34 Regenerate the metadata of a recording session
35 Use the metadata target to resample the offset between the monotonic
36 clock and the wall time of the system, and then regenerate the metadata
37 stream files.
38
39 More specifically, you may want to resample the wall time following a
40 major NTP <https://en.wikipedia.org/wiki/Network_Time_Protocol>
41 correction. As such, LTTng can trace a system booting with an incorrect
42 wall time before its wall time is NTP-corrected. Regenerating the
43 metadata of the selected recording session ensures that trace readers
44 can accurately determine the event record timestamps relative to the
45 Unix epoch.
46
47 Note that if you plan to rotate (see lttng-concepts(7) to learn more)
48 the selected recording session, this target only regenerates the
49 metadata stream files of the current and next trace chunks.
50
51 Important
52 You can only use the metadata target when the selected recording
53 session:
54
55 • Is not in live mode (--live option of lttng-create(1)).
56
57 • If it has user space channels, they’re configured to use a
58 per-user buffering scheme (--buffers-uid option of lttng-
59 enable-channel(1)).
60
61 See lttng-concepts(7) to learn more about channels.
62
63 Regenerate the state dump event records of a recording session
64 Use the statedump target to collect up-to-date state dump information
65 and create corresponding event records.
66
67 This is particularly useful if the selected recording session is in
68 snapshot mode (--snapshot option of the lttng-create(1) command) or if
69 LTTng rotates trace files for one of its channels (see lttng-
70 concepts(7)): in both cases, the state dump information may be lost.
71
73 See lttng(1) for GENERAL OPTIONS.
74
75 -s SESSION, --session=SESSION
76 Regenerate specific data of the recording session named SESSION
77 instead of the current recording session.
78
79 Program information
80 -h, --help
81 Show help.
82
83 This option attempts to launch /usr/bin/man to view this manual
84 page. Override the manual pager path with the LTTNG_MAN_BIN_PATH
85 environment variable.
86
87 --list-options
88 List available command options and quit.
89
91 0
92 Success
93
94 1
95 Command error
96
97 2
98 Undefined command
99
100 3
101 Fatal error
102
103 4
104 Command warning (something went wrong during the command)
105
107 LTTNG_ABORT_ON_ERROR
108 Set to 1 to abort the process after the first error is encountered.
109
110 LTTNG_HOME
111 Path to the LTTng home directory.
112
113 Defaults to $HOME.
114
115 Useful when the Unix user running the commands has a non-writable
116 home directory.
117
118 LTTNG_MAN_BIN_PATH
119 Absolute path to the manual pager to use to read the LTTng
120 command-line help (with lttng-help(1) or with the --help option)
121 instead of /usr/bin/man.
122
123 LTTNG_SESSION_CONFIG_XSD_PATH
124 Path to the directory containing the session.xsd recording session
125 configuration XML schema.
126
127 LTTNG_SESSIOND_PATH
128 Absolute path to the LTTng session daemon binary (see lttng-
129 sessiond(8)) to spawn from the lttng-create(1) command.
130
131 The --sessiond-path general option overrides this environment
132 variable.
133
135 $LTTNG_HOME/.lttngrc
136 Unix user’s LTTng runtime configuration.
137
138 This is where LTTng stores the name of the Unix user’s current
139 recording session between executions of lttng(1). lttng-create(1)
140 and lttng-set-session(1) set the current recording session.
141
142 $LTTNG_HOME/lttng-traces
143 Default output directory of LTTng traces in local and snapshot
144 modes.
145
146 Override this path with the --output option of the lttng-create(1)
147 command.
148
149 $LTTNG_HOME/.lttng
150 Unix user’s LTTng runtime and configuration directory.
151
152 $LTTNG_HOME/.lttng/sessions
153 Default directory containing the Unix user’s saved recording
154 session configurations (see lttng-save(1) and lttng-load(1)).
155
156 /usr/local/etc/lttng/sessions
157 Directory containing the system-wide saved recording session
158 configurations (see lttng-save(1) and lttng-load(1)).
159
160 Note
161 $LTTNG_HOME defaults to the value of the HOME environment variable.
162
164 Example 1. Regenerate the metadata of the current recording session.
165
166 $ lttng regenerate metadata
167
168 Example 2. Regenerate the state dump event records of a specific
169 recording session.
170
171 See the --session option.
172
173 $ lttng regenerate statedump --session=my-session
174
176 • LTTng project website <https://lttng.org>
177
178 • LTTng documentation <https://lttng.org/docs>
179
180 • LTTng bug tracker <https://bugs.lttng.org>
181
182 • Git repositories <https://git.lttng.org>
183
184 • GitHub organization <https://github.com/lttng>
185
186 • Continuous integration <https://ci.lttng.org/>
187
188 • Mailing list <https://lists.lttng.org/> for support and
189 development: lttng-dev@lists.lttng.org
190
191 • IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net
192
194 This program is part of the LTTng-tools project.
195
196 LTTng-tools is distributed under the GNU General Public License
197 version 2 <http://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html>.
198 See the LICENSE <https://github.com/lttng/lttng-
199 tools/blob/master/LICENSE> file for details.
200
202 Special thanks to Michel Dagenais and the DORSAL laboratory
203 <http://www.dorsal.polymtl.ca/> at École Polytechnique de Montréal for
204 the LTTng journey.
205
206 Also thanks to the Ericsson teams working on tracing which helped us
207 greatly with detailed bug reports and unusual test cases.
208
210 lttng(1), lttng-concepts(7)
211
212
213
214LTTng 2.13.7 14 June 2021 LTTNG-REGENERATE(1)