doc/man/lttng-rotate.1.txt

   1 lttng-rotate(1)
   2 ===============
   3 :revdate: 14 June 2021
   4
   5
   6 NAME
   7 ----
   8 lttng-rotate - Archive the current trace chunk of an LTTng recording session
   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 to the file system
  20 the current trace chunk of:
  21
  22 With the 'SESSION' argument::
  23     The recording session named 'SESSION'.
  24
  25 Without the 'SESSION' argument::
  26     The current recording session (see man:lttng-concepts(7) to learn
  27     more about the current recording session).
  28
  29 This action is called a _recording session rotation_.
  30
  31 See man:lttng-concepts(7) to learn more about the recording session
  32 rotation and trace chunk concepts.
  33
  34 You can use the `rotate` command:
  35
  36 * Any time the recording session is active.
  37
  38 * A single time once the recording session becomes inactive.
  39
  40 See man:lttng-concepts(7) to learn more about the activity of a
  41 recording session.
  42
  43 By default, the `rotate` command ensures that LTTng finished performing
  44 the recording session rotation before it prints the path of the archived
  45 trace chunk and exits. The printed path is absolute when the recording
  46 session was created in normal mode and relative to the base output
  47 directory of the relay daemon (see the nloption:--output option of
  48 man:lttng-relayd(8)) when it was created in network streaming mode (see
  49 man:lttng-create(1)).
  50
  51 Make the command exit immediately with the option:--no-wait option. In
  52 this case, there's no easy way to know when the current trace chunk
  53 becomes archived, and the command does :not: print the path of the
  54 archived trace chunk.
  55
  56 Because LTTng flushes the current sub-buffers of the selected recording
  57 session when it performs a recording session rotation, archived trace
  58 chunks are never redundant, that is, they do not overlap over time like
  59 snapshots can (see man:lttng-snapshot(1)). Also, a rotation does :not:
  60 directly cause discarded event records or packets.
  61
  62 A `rotate-session` trigger action can also rotate a recording session
  63 (see man:lttng-add-trigger(1)).
  64
  65 See the ``<<examples,EXAMPLES>>'' section below for usage examples.
  66
  67 [IMPORTANT]
  68 ====
  69 You may only use the `rotate` command when:
  70
  71 * The selected recording session was created in normal mode or in
  72   network streaming mode (see man:lttng-create(1)).
  73
  74 * LTTng is not currently performing an immediate rotation (this
  75   command).
  76 ====
  77
  78
  79 include::common-lttng-cmd-options-head.txt[]
  80
  81
  82 option:-n, option:--no-wait::
  83     Do not ensure that the recording session rotation operation is
  84     completed before exiting.
  85
  86
  87 include::common-lttng-cmd-help-options.txt[]
  88
  89
  90 include::common-lttng-cmd-after-options.txt[]
  91
  92
  93 [[examples]]
  94 EXAMPLES
  95 --------
  96 .Rotate the current recording session.
  97 ====
  98 [role="term"]
  99 ----
 100 $ lttng rotate
 101 ----
 102 ====
 103
 104 .Rotate a specific recording session.
 105 ====
 106 [role="term"]
 107 ----
 108 $ lttng rotate my-session
 109 ----
 110 ====
 111
 112 .Rotate the current recording session without waiting for completion.
 113 ====
 114 See the option:--no-wait option.
 115
 116 [role="term"]
 117 ----
 118 $ lttng rotate --no-wait
 119 ----
 120 ====
 121
 122
 123 include::common-footer.txt[]
 124
 125
 126 SEE ALSO
 127 --------
 128 man:lttng(1),
 129 man:lttng-disable-rotation(1),
 130 man:lttng-enable-rotation(1),
 131 man:lttng-concepts(7)