lttng-regenerate(1)

1LTTNG-REGENERATE(1)              LTTng Manual              LTTNG-REGENERATE(1)
2
3
4

NAME

6       lttng-regenerate - Regenerate specific data of an LTTng recording
7       session
8

SYNOPSIS

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

DESCRIPTION

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

OPTIONS

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

EXIT STATUS

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

ENVIRONMENT

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

FILES

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

EXAMPLES

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

RESOURCES

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

COPYRIGHT

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

THANKS

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