doc/man/lttng-rotate.1.txt

   1 lttng-rotate(1)
   2 ===============
   3 :revdate: 17 May 2021
   4
   5
   6 NAME
   7 ----
   8 lttng-rotate - Archive the current trace chunk of an LTTng tracing 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 tracing session named 'SESSION'.
  24
  25 Without the 'SESSION' argument::
  26     The current tracing session (see man:lttng-concepts(7) to learn more
  27     about the current tracing session).
  28
  29 This action is called a _tracing session rotation_.
  30
  31 See man:lttng-concepts(7) to learn more about the tracing session
  32 rotation and trace chunk concepts.
  33
  34 You can use the `rotate` command:
  35
  36 * Any time the tracing session is active.
  37
  38 * A single time once the tracing session becomes inactive.
  39
  40 See man:lttng-concepts(7) to learn more about the activity of a
  41 tracing session.
  42
  43 By default, the `rotate` command ensures that LTTng finished performing
  44 the tracing session rotation before it prints the path of the archived
  45 trace chunk and exits. The printed path is absolute when the tracing
  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 tracing
  57 session when it performs a tracing 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 tracing session (see
  63 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 tracing session was created in normal mode or in network
  72   streaming mode (see man:lttng-create(1)).
  73
  74 * No channel was created with a configured trace file count or size
  75   limit (see the nloption:--tracefile-size and
  76   nloption:--tracefile-count options of the man:lttng-enable-channel(1)
  77   command).
  78
  79 * LTTng is not currently performing an immediate rotation (this
  80   command).
  81 ====
  82
  83
  84 include::common-lttng-cmd-options-head.txt[]
  85
  86
  87 option:-n, option:--no-wait::
  88     Do not ensure that the tracing session rotation operation is
  89     completed before exiting.
  90
  91
  92 include::common-lttng-cmd-help-options.txt[]
  93
  94
  95 include::common-lttng-cmd-after-options.txt[]
  96
  97
  98 [[examples]]
  99 EXAMPLES
 100 --------
 101 .Rotate the current tracing session.
 102 ====
 103 [role="term"]
 104 ----
 105 $ lttng rotate
 106 ----
 107 ====
 108
 109 .Rotate a specific tracing session.
 110 ====
 111 [role="term"]
 112 ----
 113 $ lttng rotate my-session
 114 ----
 115 ====
 116
 117 .Rotate the current tracing session without waiting for completion.
 118 ====
 119 See the option:--no-wait option.
 120
 121 [role="term"]
 122 ----
 123 $ lttng rotate --no-wait
 124 ----
 125 ====
 126
 127
 128 include::common-footer.txt[]
 129
 130
 131 SEE ALSO
 132 --------
 133 man:lttng(1),
 134 man:lttng-disable-rotation(1),
 135 man:lttng-enable-rotation(1),
 136 man:lttng-concepts(7)