doc/man/lttng-enable-rotation.1.txt

   1 lttng-enable-rotation(1)
   2 ========================
   3 :revdate: 14 June 2021
   4
   5
   6 NAME
   7 ----
   8 lttng-enable-rotation - Set an LTTng recording session rotation schedule
   9
  10
  11 SYNOPSIS
  12 --------
  13 [verse]
  14 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-rotation* [option:--session='SESSION']
  15       (option:--timer='PERIODUS' | option:--size='SIZE' | option:--timer='PERIODUS' option:--size='SIZE')
  16
  17
  18 DESCRIPTION
  19 -----------
  20 The `lttng enable-rotation` command sets a recording session rotation
  21 schedule for:
  22
  23 With the option:--session='SESSION' option::
  24     The recording session named 'SESSION'.
  25
  26 Without the option:--session option::
  27     The current recording session (see man:lttng-concepts(7) to learn more
  28     about the current recording session).
  29
  30 See man:lttng-concepts(7) to learn more about the recording session
  31 rotation and trace chunk concepts.
  32
  33 With the option:--timer='PERIODUS' option, the `enable-rotation` command
  34 sets a rotation schedule so that LTTng performs an automatic rotation at
  35 least every 'PERIODUS'.
  36
  37 With the option:--size='SIZE' option, the `enable-rotation` command sets
  38 a rotation schedule so that LTTng performs an automatic rotation every
  39 time the total size of the flushed part of the current trace chunk is at
  40 least 'SIZE'.
  41
  42 For both the option:--timer and option:--size options, LTTng checks the
  43 schedule condition periodically using the monitor timers of the channels
  44 of the selected recording session (see the nloption:--monitor-timer
  45 option of the man:lttng-enable-channel(1) command). This means that:
  46
  47 * With the option:--timer='PERIODUS' option, LTTng can perform an
  48   automatic rotation when the elapsed time since the last automatic
  49   rotation is slightly greater than 'PERIODUS'.
  50 +
  51 The exact precision depends on the precision of the monitor timer, which
  52 relies on the precision of the platform implementation of POSIX timers.
  53
  54 * With the option:--size='SIZE' option, LTTng can perform an automatic
  55   rotation when the size of the flushed part of the current trace chunk
  56   is greater than 'SIZE'.
  57
  58 You may combine the option:--timer and option:--size options.
  59
  60 See the man:lttng-concepts(7) to learn how LTTng names a trace chunk
  61 archive directory.
  62
  63 See the ``<<examples,EXAMPLES>>'' section below for usage examples.
  64
  65 Unset a recording session rotation schedule with the
  66 man:lttng-disable-rotation(1) command.
  67
  68 [IMPORTANT]
  69 ====
  70 You may only use the `enable-rotation` command when:
  71
  72 * The selected recording session was created in normal mode or in
  73   network streaming mode (see man:lttng-create(1)).
  74
  75 * No channel was created with a configured trace file count or size
  76   limit (see the nloption:--tracefile-size and
  77   nloption:--tracefile-count options of the man:lttng-enable-channel(1)
  78   command).
  79
  80 For a given recording session, LTTng only performs an automatic rotation
  81 when it's not currently performing a rotation.
  82 ====
  83
  84
  85 include::common-lttng-cmd-options-head.txt[]
  86
  87
  88 Rotation schedule condition
  89 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  90 option:--size='SIZE'::
  91     Set a rotation schedule so that LTTng performs an automatic rotation
  92     every time the total size of the flushed part of the current trace
  93     chunk is at least 'SIZE' bytes.
  94 +
  95 The `k`{nbsp}(KiB), `M`{nbsp}(MiB), and `G`{nbsp}(GiB) suffixes are
  96 supported.
  97
  98 option:--timer='PERIODUS'::
  99     Set a rotation schedule so that LTTng performs an automatic rotation
 100     approximately every 'PERIODUS' microseconds.
 101 +
 102 The `ms`{nbsp}(milliseconds), `s`{nbsp}(seconds), `m`{nbsp}(minutes),
 103 and `h`{nbsp}(hours) suffixes are supported.
 104
 105
 106 Recording target
 107 ~~~~~~~~~~~~~~~~
 108 option:-s 'SESSION', option:--session='SESSION'::
 109     Set a rotation schedule for the recording session named 'SESSION'
 110     instead of the current recording session.
 111
 112
 113 include::common-lttng-cmd-help-options.txt[]
 114
 115
 116 include::common-lttng-cmd-after-options.txt[]
 117
 118
 119 [[examples]]
 120 EXAMPLES
 121 --------
 122 .Set the size-based rotation schedule of the current recording session.
 123 ====
 124 See the option:--size option.
 125
 126 [role="term"]
 127 ----
 128 $ lttng disable-rotation --size=256M
 129 ----
 130 ====
 131
 132 .Set the periodic rotation schedule of a specific recording session.
 133 ====
 134 See the option:--timer and option:--session options.
 135
 136 [role="term"]
 137 ----
 138 $ lttng disable-rotation --session=my-session --timer=5m
 139 ----
 140 ====
 141
 142
 143 include::common-footer.txt[]
 144
 145
 146 SEE ALSO
 147 --------
 148 man:lttng(1),
 149 man:lttng-create(1),
 150 man:lttng-disable-rotation(1),
 151 man:lttng-rotate(1),
 152 man:lttng-concepts(7)