doc/man/lttng-rotate.1.txt

   1 lttng-rotate(1)
   2 ===============
   3 :revdate: 18 October 2019
   4
   5
   6 NAME
   7 ----
   8 lttng-rotate - Archive a tracing session's current trace chunk
   9
  10
  11 SYNOPSIS
  12 --------
  13 [verse]
  14 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *rotate* [option:--no-wait] ['SESSION']
  15
  16
  17 DESCRIPTION
  18 -----------
  19 The `lttng rotate` command archives the current trace chunk of the
  20 current tracing session, or of the tracing session named 'SESSION' if
  21 provided, to the file system. This action is called a tracing session
  22 _rotation_.
  23
  24 Once LTTng archives a trace chunk, it does not manage it anymore: you
  25 can read it, modify it, move it, or remove it.
  26
  27 An _archived trace chunk_ is a collection of metadata and data stream
  28 files which form a self-contained LTTng trace.
  29
  30 The _current trace chunk_ of a given tracing session includes:
  31
  32 * The stream files already written to the file system, and which are
  33   not part of a previously archived trace chunk, since the most recent
  34   event amongst:
  35 ** The first time the tracing session was started with
  36    man:lttng-start(1).
  37 ** The last rotation, either an immediate one with `lttng rotate`, or an
  38    automatic one from a rotation schedule previously set with
  39    man:lttng-enable-rotation(1).
  40 * The content of all the non-flushed sub-buffers of the tracing
  41   session's channels.
  42
  43 You can use `lttng rotate`:
  44
  45 * At any time when the tracing session is active (see
  46   man:lttng-start(1)).
  47 * A single time once the tracing session becomes inactive
  48   (see man:lttng-stop(1)).
  49
  50 By default, the `lttng rotate` command ensures that LTTng finished
  51 performing the tracing session rotation before it prints the archived
  52 trace chunk's path and exits. The printed path is absolute when the
  53 tracing session was created in normal mode and relative to the relay
  54 daemon's output directory (see the nloption:--output option in
  55 man:lttng-relayd(8)) when it was created in network streaming mode (see
  56 man:lttng-create(1)).
  57
  58 With the option:--no-wait option, the command finishes immediately, so
  59 that LTTng might not have completed the rotation when the command exits.
  60 In this case, there is no easy way to know when the current trace chunk
  61 becomes archived, and the command does not print the archived trace
  62 chunk's path.
  63
  64 Because when LTTng performs a tracing session rotation, it flushes the
  65 tracing session's current sub-buffers, archived trace chunks are never
  66 redundant, that is, they do not overlap over time like snapshots can
  67 (see man:lttng-snapshot(1)). Also, a rotation does not directly cause
  68 discarded event records or packets.
  69
  70 See <<limitations,LIMITATIONS>> for important limitations regarding
  71 this command.
  72
  73
  74 Trace chunk archive naming
  75 ~~~~~~~~~~~~~~~~~~~~~~~~~~
  76 A trace chunk archive is a subdirectory of the `archives` subdirectory
  77 within a tracing session's output directory (see the nloption:--output
  78 option in man:lttng-create(1) and man:lttng-relayd(8)).
  79
  80 A trace chunk archive contains, through tracing domain and possibly
  81 UID/PID subdirectories, metadata and data stream files.
  82
  83 A trace chunk archive is, at the same time:
  84
  85 * A self-contained LTTng trace.
  86 * A member of a set of trace chunk archives which form the complete
  87   trace of a tracing session.
  88
  89 In other words, an LTTng trace reader can read both the tracing
  90 session output directory (all the trace chunk archives), or a
  91 single trace chunk archive.
  92
  93 When LTTng performs a tracing session rotation, it names the resulting
  94 trace chunk archive as such, relative to the tracing session's output
  95 directory:
  96
  97 [verse]
  98 archives/__BEGIN__-__END__-__ID__
  99
 100 __BEGIN__::
 101     Date and time of the beginning of the trace chunk archive with
 102     the ISO{nbsp}8601-compatible `YYYYmmddTHHMMSS±HHMM` form, where
 103     `YYYYmmdd` is the date and `HHMMSS±HHMM` is the time with the
 104     time zone offset from UTC.
 105 +
 106 Example: `20171119T152407-0500`
 107
 108 __END__::
 109     Date and time of the end of the trace chunk archive with
 110     the ISO{nbsp}8601-compatible `YYYYmmddTHHMMSS±HHMM` form, where
 111     `YYYYmmdd` is the date and `HHMMSS±HHMM` is the time with the
 112     time zone offset from UTC.
 113 +
 114 Example: `20180118T152407+0930`
 115
 116 __ID__::
 117     Unique numeric identifier of the trace chunk within its tracing
 118     session.
 119
 120 Trace chunk archive name example:
 121
 122 ----
 123 archives/20171119T152407-0500-20171119T151422-0500-3
 124 ----
 125
 126
 127 include::common-cmd-options-head.txt[]
 128
 129
 130 option:-n, option:--no-wait::
 131     Do not ensure that the rotation is done before returning to
 132     the prompt.
 133
 134
 135 include::common-cmd-help-options.txt[]
 136
 137
 138 [[limitations]]
 139 LIMITATIONS
 140 -----------
 141 The `lttng rotate` command only works when:
 142
 143 * The tracing session is created in normal mode or in network streaming
 144   mode (see man:lttng-create(1)).
 145
 146 * No channel was created with a configured trace file count or size
 147   limit (see the nloption:--tracefile-size and
 148   nloption:--tracefile-count options in man:lttng-enable-channel(1)).
 149
 150 * No immediate rotation (`lttng rotate`) is currently happening.
 151
 152
 153 include::common-cmd-footer.txt[]
 154
 155
 156 SEE ALSO
 157 --------
 158 man:lttng-enable-rotation(1),
 159 man:lttng-disable-rotation(1),
 160 man:lttng(1)