doc/man/lttng-rotate.1.txt

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