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 LTTng archives a trace chunk, it 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 LTTng 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 an immediate 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`:
  43
  44 * At any time when the tracing session is active (see
  45   man:lttng-start(1)).
  46 * A single time once the tracing session becomes inactive
  47   (see man:lttng-stop(1)).
  48
  49 By default, the `lttng rotate` command ensures that LTTng finished
  50 performing the tracing session rotation before it prints the archived
  51 trace chunk's path and exits. The printed path is absolute when the
  52 tracing session was created in normal mode and relative to the relay
  53 daemon's output directory (see the nloption:--output option in
  54 man:lttng-relayd(8)) when it was created in network streaming mode (see
  55 man:lttng-create(1)).
  56
  57 With the option:--no-wait option, the command finishes immediately, so
  58 that LTTng might not have completed the rotation when the command exits.
  59 In this case, there is no easy way to know when the current trace chunk
  60 becomes archived, and the command does not print the archived trace
  61 chunk's path.
  62
  63 Because when LTTng performs a tracing session rotation, it flushes the
  64 tracing session's current sub-buffers, archived trace chunks are never
  65 redundant, that is, they do not overlap over time like snapshots can
  66 (see man:lttng-snapshot(1)). Also, a rotation does not directly cause
  67 discarded event records or packets.
  68
  69 See <<limitations,LIMITATIONS>> for important limitations regarding
  70 this command.
  71
  72
  73 Trace chunk archive naming
  74 ~~~~~~~~~~~~~~~~~~~~~~~~~~
  75 A trace chunk archive is a subdirectory of the `archives` subdirectory
  76 within a tracing session's output directory (see the nloption:--output
  77 option in man:lttng-create(1) and man:lttng-relayd(8)).
  78
  79 A trace chunk archive contains, through tracing domain and possibly
  80 UID/PID subdirectories, metadata and data stream files.
  81
  82 A trace chunk archive is, at the same time:
  83
  84 * A self-contained LTTng trace.
  85 * A member of a set of trace chunk archives which form the complete
  86   trace of a tracing session.
  87
  88 In other words, an LTTng trace reader can read both the tracing
  89 session output directory (all the trace chunk archives), or a
  90 single trace chunk archive.
  91
  92 When LTTng performs a tracing session rotation, it names the resulting
  93 trace chunk archive as such, relative to the tracing session's output
  94 directory:
  95
  96 [verse]
  97 archives/__BEGIN__-__END__-__ID__
  98
  99 __BEGIN__::
 100     Date and time of the beginning of the trace chunk archive with
 101     the ISO{nbsp}8601-compatible `YYYYmmddTHHMMSS±HHMM` form, where
 102     `YYYYmmdd` is the date and `HHMMSS±HHMM` is the time with the
 103     time zone offset from UTC.
 104 +
 105 Example: `20171119T152407-0500`
 106
 107 __END__::
 108     Date and time of the end of the trace chunk archive with
 109     the ISO{nbsp}8601-compatible `YYYYmmddTHHMMSS±HHMM` form, where
 110     `YYYYmmdd` is the date and `HHMMSS±HHMM` is the time with the
 111     time zone offset from UTC.
 112 +
 113 Example: `20180118T152407+0930`
 114
 115 __ID__::
 116     Unique numeric identifier of the trace chunk within its tracing
 117     session.
 118
 119 Trace chunk archive name example:
 120
 121 ----
 122 archives/20171119T152407-0500-20171119T151422-0500-3
 123 ----
 124
 125
 126 include::common-cmd-options-head.txt[]
 127
 128
 129 option:-n, option:--no-wait::
 130     Do not ensure that the rotation is done before returning to
 131     the prompt.
 132
 133
 134 include::common-cmd-help-options.txt[]
 135
 136
 137 [[limitations]]
 138 LIMITATIONS
 139 -----------
 140 The `lttng rotate` command only works when:
 141
 142 * The tracing session is created in normal mode or in network streaming
 143   mode (see man:lttng-create(1)).
 144
 145 * No channel was created with a configured trace file count or size
 146   limit (see the nloption:--tracefile-size and
 147   nloption:--tracefile-count options in man:lttng-enable-channel(1)).
 148
 149 * No immediate rotation (`lttng rotate`) is currently happening.
 150
 151
 152 include::common-cmd-footer.txt[]
 153
 154
 155 SEE ALSO
 156 --------
 157 man:lttng-enable-rotation(1),
 158 man:lttng-disable-rotation(1),
 159 man:lttng(1)