doc/man/lttng-regenerate.1.txt

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