lttng-regenerate(1)
-=================
+===================
+:revdate: 14 June 2021
NAME
----
-lttng-regenerate - Manage an LTTng tracing session's data regeneration
+lttng-regenerate - Regenerate specific data of an LTTng recording session
SYNOPSIS
--------
-Regenerate the metadata of a session:
+Regenerate the metadata of a recording session:
[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *regenerate metadata* [option:--session='SESSION']
-Regenerate the state dump of a session:
+Regenerate the state dump event records of a recording session:
[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *regenerate statedump* [option:--session='SESSION']
+
DESCRIPTION
-----------
-The `lttng regenerate` command regenerates specific data of a tracing session.
+The `lttng regenerate` command regenerates specific data of:
+
+With the option:--session='SESSION' option::
+ The recording session named 'SESSION'.
+
+Without the option:--session option::
+ The current recording session (see man:lttng-concepts(7) to learn
+ more about the current recording session).
-As of this version, the `metadata` and `statedump` actions are
+See man:lttng-concepts(7) to learn more about recording sessions.
+
+As of this version, the `metadata` and `statedump` targets are
available.
+See the ``<<examples,EXAMPLES>>'' section below for usage examples.
+
+
+Regenerate the metadata of a recording session
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Use the `metadata` target to resample the offset between the monotonic
+clock and the wall time of the system, and then regenerate the metadata
+stream files.
+
+More specifically, you may want to resample the wall time following a
+major link:https://en.wikipedia.org/wiki/Network_Time_Protocol[NTP]
+correction. As such, LTTng can trace a system booting with an incorrect
+wall time before its wall time is NTP-corrected. Regenerating the
+metadata of the selected recording session ensures that trace readers
+can accurately determine the event record timestamps relative to the
+Unix epoch.
+
+Note that if you plan to rotate (see man:lttng-concepts(7) to learn
+more) the selected recording session, this target only regenerates the
+metadata stream files of the current and next trace chunks.
+
+[IMPORTANT]
+====
+You can only use the `metadata` target when the selected
+recording session:
+
+* Is not in live mode (nloption:--live option of
+ man:lttng-create(1)).
-Regenerating a tracing session's metadata
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The `lttng regenerate metadata` action can be used to resample the offset
-between the system's monotonic clock and the wall-clock time.
+* If it has user space channels, they're configured to use a
+ per-user buffering scheme (nloption:--buffers-uid option of
+ man:lttng-enable-channel(1)).
++
+See man:lttng-concepts(7) to learn more about channels.
+====
-This action is meant to be used to resample the wall-clock time following a
-major link:https://en.wikipedia.org/wiki/Network_Time_Protocol[NTP] correction.
-As such, a system booting with an incorrect wall time can be traced before its
-wall time is NTP-corrected. Regenerating the tracing session's metadata ensures
-that trace viewers can accurately determine the events time relative to Unix
-Epoch.
+Regenerate the state dump event records of a recording session
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Use the `statedump` target to collect up-to-date state dump information
+and create corresponding event records.
-Regenerating a tracing session's state dump
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The `lttng regenerate statedump` action can be used to collect up-to-date state
-dump information during the tracing session. This is particularly useful in
-snapshot (see man:lttng-snapshot(1)) or trace file rotation (see
-man:lttng-enable-channel(1)) modes where the state dump information may be
+This is particularly useful if the selected recording session is in
+snapshot mode (nloption:--snapshot option of the man:lttng-create(1)
+command) or if LTTng rotates trace files for one of its channels (see
+man:lttng-concepts(7)): in both cases, the state dump information may be
lost.
-include::common-cmd-options-head.txt[]
+include::common-lttng-cmd-options-head.txt[]
option:-s 'SESSION', option:--session='SESSION'::
- Regenerate the data of the tracing session named 'SESSION'
- instead of the current tracing session.
+ Regenerate specific data of the recording session named 'SESSION'
+ instead of the current recording session.
-include::common-cmd-help-options.txt[]
+include::common-lttng-cmd-help-options.txt[]
-LIMITATIONS
------------
-The `lttng regenerate metadata` command can only be used on kernel and
-user space tracing sessions (using per-user buffering), in non-live
-mode.
+include::common-lttng-cmd-after-options.txt[]
+
-See man:lttng-enable-channel(1) for more information about
-buffering schemes and man:lttng-create(1) for more information
-about the different tracing session modes.
+[[examples]]
+EXAMPLES
+--------
+.Regenerate the metadata of the current recording session.
+====
+[role="term"]
+----
+$ lttng regenerate metadata
+----
+====
+
+.Regenerate the state dump event records of a specific recording session.
+====
+See the option:--session option.
+
+[role="term"]
+----
+$ lttng regenerate statedump --session=my-session
+----
+====
-include::common-cmd-footer.txt[]
+include::common-footer.txt[]
SEE ALSO
--------
-man:lttng(1)
+man:lttng(1),
+man:lttng-concepts(7)