doc/man/lttng-regenerate.1.txt

   1 lttng-regenerate(1)
   2 ===================
   3 :revdate: 14 June 2021
   4
   5
   6 NAME
   7 ----
   8 lttng-regenerate - Regenerate specific data of an LTTng recording session
   9
  10
  11 SYNOPSIS
  12 --------
  13 Regenerate the metadata of a recording session:
  14
  15 [verse]
  16 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *regenerate metadata* [option:--session='SESSION']
  17
  18 Regenerate the state dump event records of a recording session:
  19
  20 [verse]
  21 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *regenerate statedump* [option:--session='SESSION']
  22
  23
  24 DESCRIPTION
  25 -----------
  26 The `lttng regenerate` command regenerates specific data of:
  27
  28 With the option:--session='SESSION' option::
  29     The recording session named 'SESSION'.
  30
  31 Without the option:--session option::
  32     The current recording session (see man:lttng-concepts(7) to learn
  33     more about the current recording session).
  34
  35 See man:lttng-concepts(7) to learn more about recording sessions.
  36
  37 As of this version, the `metadata` and `statedump` targets are
  38 available.
  39
  40 See the ``<<examples,EXAMPLES>>'' section below for usage examples.
  41
  42
  43 Regenerate the metadata of a recording session
  44 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  45 Use the `metadata` target to resample the offset between the monotonic
  46 clock and the wall time of the system, and then regenerate the metadata
  47 stream files.
  48
  49 More specifically, you may want to resample the wall time following a
  50 major link:https://en.wikipedia.org/wiki/Network_Time_Protocol[NTP]
  51 correction. As such, LTTng can trace a system booting with an incorrect
  52 wall time before its wall time is NTP-corrected. Regenerating the
  53 metadata of the selected recording session ensures that trace readers
  54 can accurately determine the event record timestamps relative to the
  55 Unix epoch.
  56
  57 Note that if you plan to rotate (see man:lttng-concepts(7) to learn
  58 more) the selected recording session, this target only regenerates the
  59 metadata stream files of the current and next trace chunks.
  60
  61 [IMPORTANT]
  62 ====
  63 You can only use the `metadata` target when the selected
  64 recording session:
  65
  66 * Is not in live mode (nloption:--live option of
  67   man:lttng-create(1)).
  68
  69 * If it has user space channels, they're configured to use a
  70   per-user buffering scheme (nloption:--buffers-uid option of
  71   man:lttng-enable-channel(1)).
  72 +
  73 See man:lttng-concepts(7) to learn more about channels.
  74 ====
  75
  76
  77 Regenerate the state dump event records of a recording session
  78 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  79 Use the `statedump` target to collect up-to-date state dump information
  80 and create corresponding event records.
  81
  82 This is particularly useful if the selected recording session is in
  83 snapshot mode (nloption:--snapshot option of the man:lttng-create(1)
  84 command) or if LTTng rotates trace files for one of its channels (see
  85 man:lttng-concepts(7)): in both cases, the state dump information may be
  86 lost.
  87
  88
  89 include::common-lttng-cmd-options-head.txt[]
  90
  91
  92 option:-s 'SESSION', option:--session='SESSION'::
  93     Regenerate specific data of the recording session named 'SESSION'
  94     instead of the current recording session.
  95
  96
  97 include::common-lttng-cmd-help-options.txt[]
  98
  99
 100 include::common-lttng-cmd-after-options.txt[]
 101
 102
 103 [[examples]]
 104 EXAMPLES
 105 --------
 106 .Regenerate the metadata of the current recording session.
 107 ====
 108 [role="term"]
 109 ----
 110 $ lttng regenerate metadata
 111 ----
 112 ====
 113
 114 .Regenerate the state dump event records of a specific recording session.
 115 ====
 116 See the option:--session option.
 117
 118 [role="term"]
 119 ----
 120 $ lttng regenerate statedump --session=my-session
 121 ----
 122 ====
 123
 124
 125 include::common-footer.txt[]
 126
 127
 128 SEE ALSO
 129 --------
 130 man:lttng(1),
 131 man:lttng-concepts(7)